Index.rst 13.7 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../Includes.txt


.. _admin-manual:

Administrator Manual
====================

14
15
16
Preparation
-----------

17
18
19
Report & Form
^^^^^^^^^^^^^

20
The QFQ extension needs in PHP 5.x the PHP MySQL native driver. The following functions are used and are only available with the
21
22
23
24
25
native driver (see also: http://dev.mysql.com/downloads/connector/php-mysqlnd/):

* mysqli::get_result (important),
* mysqli::fetch_all (nice to use)

26
27
28
29
To normalize UTF8 input, the *php5-intl* resp. *php7.0-intl* package is needed by

* normalizer::normalize()

30
Preparation for Ubuntu 14.04::
31

32
	sudo apt-get install php5-mysqlnd php5-intl
33
34
35
	sudo php5enmod mysqlnd
	sudo service apache2 restart

36
37
Preparation steps for Ubuntu 16.04::

Carsten  Rose's avatar
Carsten Rose committed
38
	sudo apt install php7.0-intl
39

40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
Print page via wkhtmltopdf
^^^^^^^^^^^^^^^^^^^^^^^^^^

Different browser prints the same page in different variations. To prevent this, QFQ implements a small PHP wrapper `print.php`
which uses http://wkhtmltopdf.org/ (webkit based) to convert HTML to PDF. The converter is not included in QFQ and has
to be manually installed.

Hint: The Ubuntu package `wkhtmltopdf` needs a running Xserver - this does not work on a headless webserver. Best is to
install the QT version from the named website above.

In config.qfq.ini specify the:
* installed `wkhtmltopdf` binary,
* the site base URL.

Provide a `print this page`-link (replace {current pageId})::

	<a href="typo3conf/ext/qfq/qfq/api/print.php?id={current pageId}">Print this page</a>

Any parameter specified after `print.php` will be delivered to `wkhtmltopdf` as part of the URL.

Typoscript code to implement a print link on every page::

	10 = TEXT
	10 {
		wrap = <a href="typo3conf/ext/qfq/qfq/api/print.php?id=|&type=2"><span class="glyphicon glyphicon-print" aria-hidden="true"></span> Printview</a>
		data = page:uid
	}

68
69
70
71
Setup
-----

* Install the extension via the Extensionmanager.
72
73

  * If you install the extension by manual download/upload and get an error message
74
    "can't activate extension": rename the downloaded zip file to `qfq.zip` or `qfq_<version>.zip` (e.g. version: 0.9.1).
75

76
77
78
  * If the Extensionmanager stops after importing: check your memory limit in php.ini.

* Enable the online Documentation_.
79
80
81
* Copy/rename the file *<Documentroot>/typo3conf/ext/<ext_dir>/config.example.qfq.ini* to
  *<Documentroot>/typo3conf/config.qfq.ini* and configure the necessary values: `config.qfq.ini`_
  The configuration file is outside the extension directory to not loose it during updates.
82
* Play the SQL File *<ext_dir>/qfq/sql/formEditor.sql* to fill the database with the *FormEditor* records.
83
* Configure Typoscript to include Bootstrap, jQuery, QFQ javascript and CSS files.
84
85
86

::

87
88
89
90
91
92
	page.meta {
	  X-UA-Compatible = IE=edge
	  X-UA-Compatible.attribute = http-equiv
	  viewport=width=device-width, initial-scale=1
	}

93
94
	page.includeCSS {

95
96
97
		file1 = typo3conf/ext/qfq/Resources/Public/Css/bootstrap.min.css
		file2 = typo3conf/ext/qfq/Resources/Public/Css/bootstrap-theme.min.css
		file3 = typo3conf/ext/qfq/Resources/Public/Css/jqx.base.css
Carsten  Rose's avatar
Carsten Rose committed
98
		file4 = typo3conf/ext/qfq/Resources/Public/Css/jqx.bootstrap.css
99
		file5 = typo3conf/ext/qfq/Resources/Public/Css/qfq-bs.css
100
101
102
103
	}

	page.includeJS {

104
105
106
107
		file1 = typo3conf/ext/qfq/Resources/Public/JavaScript/jquery.min.js
		file2 = typo3conf/ext/qfq/Resources/Public/JavaScript/bootstrap.min.js
		file3 = typo3conf/ext/qfq/Resources/Public/JavaScript/validator.min.js
		file4 = typo3conf/ext/qfq/Resources/Public/JavaScript/jqx-all.js
108
109
110
111
		file5 = typo3conf/ext/qfq/Resources/Public/JavaScript/globalize.js
		file6 = typo3conf/ext/qfq/Resources/Public/JavaScript/tinymce.min.js
		file7 = typo3conf/ext/qfq/Resources/Public/JavaScript/EventEmitter.min.js
		file8 = typo3conf/ext/qfq/Resources/Public/JavaScript/qfq.min.js
112
113
	}

114

115
116
117
118
119
120
FormEditor
----------
Setup a *report* to manage all *forms*: Create a Typo3 page and insert a content record of type *qfq*. In the bodytext insert the following code:

::

121
122
	# If there is a form given by SIP: show
	form={{form:S}}
123
124

	10 {
125
		# List of Forms: Do not show this list of forms if there is a form given by SIP.
126
127
128
129
130
131
132
133
134
135
		# Table header.
		sql = SELECT CONCAT('{{pageId:T}}&form=Form&') as Pagen, '#', 'Name', 'Title', 'Table' FROM (SELECT 1) AS fake WHERE  '{{form:SE}}'=''
		head = <table class="table table-hover">
		tail = </table>
		rbeg = <thead><tr>
		rend = </tr></thead>
		fbeg = <th>
		fend = </th>

		10 {
136
137
			# All forms
			sql = SELECT CONCAT('{{pageId:T}}&form=Form&r=', f.id) as Pagee, f.id, f.name, f.title, f.tableName, CONCAT('form=Form&r=', f.id) as Paged FROM Form AS f  ORDER BY f.name
138
139
140
141
142
143
			rbeg = <tr>
			rend = </tr>
			fbeg = <td>
			fend = </td>
		}
	}
144

Carsten  Rose's avatar
Carsten Rose committed
145
.. _config-qfq-ini:
146

147
config.qfq.ini
148
--------------
149

150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| Keyword                     | Example                                 | Description                                                                |
+=============================+=========================================+============================================================================+
| DB_USER                     | DB_USER=qfqUser                         | Credentials configured in MySQL                                            |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| DB_PASSWORD                 | DB_PASSWORD=12345678                    | Credentials configured in MySQL                                            |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| DB_SERVER                   | DB_SERVER=localhost                     | Hostname of MySQL Server                                                   |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| DB_NAME                     | DB_NAME=qfq_db                          | Database name                                                              |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| DB_NAME_TEST                | DB_NAME_TEST=qfq_db_test                | Used during development of QFQ                                             |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| DB_INIT                     | DB_INIT=set names utf8                  | Global init for using the database.                                        |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| SQL_LOG                     | SQL_LOG=sql.log                         | Filename to log SQL commands: relative to <ext_dir> or absolute.           |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| SQL_LOG_MODE                | SQL_LOG_MODE=modify                     | *all*: every statement will be logged - this is a lot                      |
|                             |                                         | *modify*: log only statements who change data                              |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| SHOW_DEBUG_INFO             | SHOW_DEBUG_INFO=auto                    | Possible values: auto|yes|no. For 'auto': If a BE User is logged in,       |
|                             |                                         | debug information will be shown on the fronend.                            |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| CSS_LINK_CLASS_INTERNA    L | CSS_LINK_CLASS_INTERNAL=internal        | CSS class name of links which points to internal tagets                    |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| CSS_LINK_CLASS_EXTERNAL     | CSS_LINK_CLASS_EXTERNAL=external        | CSS class name of links which points to internal tagets                    |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| CSS_CLASS_QFQ_CONTAINER     |CSS_CLASS_QFQ_CONTAINER=container        | QFQ with own Bootstrap: 'container'.                                       |
|                             |                                         | QFQ already nested in Bootstrap of mainpage: <empty>                       |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| CSS_CLASS_QFQ_FORM_PILL     |CSS_CLASS_QFQ_FORM_PILL=qfq-color-grey-1 | Wrap around title bar for pills: CSS Class, typically a background color   |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| CSS_CLASS_QFQ_FORM_BODY     |CSS_CLASS_QFQ_FORM_BODY=qfq-color-grey-2 | Wrap around formelements: CSS Class, typically a background color          |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| DATE_FORMAT                 | DATE_FORMAT= yyyy-mm-dd                 | Possible options: yyyy-mm-dd, dd.mm.yyyy                                   |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| FORM_DATA_PATTERN_ERROR     |FORM_DATA_PATTERN_ERROR=please check pa. | Customizable error message used in validator.js. 'pattern' violation       |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| FORM_DATA_REQUIRED_ERROR    |FORM_DATA_REQUIRED_ERROR=missing value   | Customizable error message used in validator.js. 'required' fields         |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| FORM_DATA_MATCH_ERROR       |FORM_DATA_MATCH_ERROR=type error         | Customizable error message used in validator.js. 'match' retype mismatch   |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| FORM_DATA_ERROR             |FORM_DATA_ERROR=generic error            | Customizable error message used in validator.js. 'no specific' given       |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
194
| FORM_BUTTON_ON_CHANGE_CLASS | FORM_BUTTON_ON_CHANGE_CLASS=alert-info btn-info | Color for save button after modification                           |
195
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
196
197
198
199
| BASE_URL_PRINT              | BASE_URL_PRINT=http://example.com       | URL where wkhtmltopdf will fetch the HTML (no parameter, those comes later)|
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
| WKHTMLTOPDF                 | WKHTMLTOPDF=/usr/bin/wkhtmltopdf        | Binary where to find wkhtmltopdf                                           |
+-----------------------------+-----------------------------------------+----------------------------------------------------------------------------+
200

201

202
Example: *typo3conf/config.qfq.ini*
203
204
205

::

Carsten  Rose's avatar
Carsten Rose committed
206
	; To get internal default values, inactivate the option by commenting (= ';') it.
207
208
209
210
	DB_USER = qfqUser
	DB_SERVER = localhost
	DB_PASSWORD = 12345678
	DB_NAME = qfq_db
211
	DB_INIT = set names utf8
212
	SQL_LOG = sql.log
213
214
	SHOW_DEBUG_INFO = auto
	CSS_LINK_CLASS_INTERNAL = internal
215
	CSS_LINK_CLASS_EXT = external
Carsten  Rose's avatar
Carsten Rose committed
216
217
218
219
220
221
222
223
	;CSS_CLASS_QFQ_CONTAINER =
	;CSS_CLASS_QFQ_FORM =
	CSS_CLASS_QFQ_FORM_PILL = qfq-color-grey-1
	CSS_CLASS_QFQ_FORM_BODY = qfq-color-grey-2
	;FORM_DATA_PATTERN_ERROR =
	;FORM_DATA_REQUIRED_ERROR =
	;FORM_DATA_MATCH_ERROR =
	;FORM_DATA_ERROR =
224
225
226
	;FORM_BS_LABEL_COLUMNS = 3
	;FORM_BS_INPUT_COLUMNS = 6
	;FORM_BS_NOTE_COLUMNS = 3
227
228
	BASE_URL_PRINT=http://example.com
	WKHTMLTOPDF=/usr/bin/wkhtmltopdf
229
230
231
232
233
234

Documentation
-------------

To render the QFQ reST documentation:

235
* Take care to have 'unzip' and 'Python setuptools' installed (necessary to run).
236
237
238

Preparation for Ubuntu 16.04::

Carsten  Rose's avatar
Carsten Rose committed
239
	sudo apt install unzip python-setuptools python-pip
240

241
242
243
244
245
246
247
248
* Install the extension "Sphinx Python Documentation Generator and Viewer" (sphinx).

  * Execute the update script (symbol 'two arrows as a circle' behind the extension name)
  * Choose 'Sphinx 1.4.4' - click on 'Import'.

* In the Exension Manager open the configuration dialog of the extension 'sphinx'. Activate the 'Sphinx 1.4.4' option and save it.
* On top of the browser window click on the 'question mark' to open the menu, choose 'Sphinx'.
* Show doumentation 'QFQ Extension'
Carsten  Rose's avatar
Carsten Rose committed
249
250

* If you have problems with the rendering, please check: http://mbless.de/blog/2015/01/26/sphinx-doc-installation-steps.html