Installation and Configuration¶
Installation¶
The following installation is just an example for testing the extension.
Download the extension sav_library_example8 from the TER and install it.
Create a folder for the frontend users.
In the folder, create a frontend group for regular users and a frontend group for admin users.
In the folder, create a regular user and an admin user for the test.
Create a test page for the USER form and another for the ADMIN form.
In the USER page, insert the plugin and select the USER form.
Click on the folder
Input controls
. SelectAllow authenticated FE users to input data
. Enterfe_users.uid
in theInput Admin Field
. SelectNo "new" button
,No "edit" button
,"No delete button
and save.
Edit the Page Properties and add the following configuration TypoScript configuration in the folder
Resources
. It will change thePartials
root path to thePartials
directory provided with this extension.
Authenticate the user and go to the
USER
page. You should see either the user's image (hereuser_defined.gif
icon was used) or a question mark image if no input was provided.
Click on the image link to open the edit view. As it can been seen, the new title bar has been taken into account and only
Save
andClose
buttons are displayed.
In the ADMIN page, insert the plugin, select the
ADMIN
form and include the user folder in theRecord Storage Page
field.
Click on the folder
Input controls
. SelectAllow authenticated FE users to input data
to allow the input. Add your administration group (hereadmin
) inAllowed group
. SelectNo new button
if you do not want to allow the creation of new users.
Authenticate the administration user and go to the ADMIN page. The view displays the users'name, their email, their phone number and their groups. The behavior of the form is the same as in the previous examples. Click on the name to see the user's configuration. Use the edit icon to modify the fields.
Exporting Data to CSV Format¶
Exporting data is possible for any form built with the SAV Library
Generator. To allow this feature you simply have to add the following
line either in the user TSConfig field or in a group TSConfig
:
sav_library_example8_Export = *
In general, it is done in the Back End. However, our extension makes it possible to do it in the frontend for the user as shown below.
Now, close the view and verify that you obtain a new CSV icon in the
ADMIN List
view and click on it to obtain the export view.
The configuration can be used to save, load, delete an export
configuration. Use the toogle button to display only selected fields
or to display all fields. In the above caption, the export
configuration Fe Users (CSV)
, previously saved, was reloaded.
XML and XSLT files can be used to export data to other formats (see next section).
Checkboxes are used to select the fields to be exported. If the first checkbox is selected, the raw data are displayed, that is the content of the field in the data base. If the second one is selected, a rendering is done. The field is displayed as it would have been in a Single view.
The Where clause
field is used to filter the data to be exported.
Let us note that if you double-click on a field name, it will be added
in the Where clause
field. It is useful to avoid mistakes.
The Order clause
field is used to order the data to export.
Additional tables
can be used for more complex export where you need
to link data used by the extension to data in other tables. In that
case do not forget to add a condition in the Where clause
to join
correctly the tables.
Export MM records
can be set when your extension use MM tables and
you want to export all data. In that case you may also need to add a
Group by clause
.
Include all fields
can be used when you want to export fields like
uid, pid, crdate, ... which are hidden by default. Click on the red
CSV icon to include all the fields. Use the toogle button if you have
previously restricted the display to selected fields.
Export field names
can be selected when you want to have the field
names as the first line in the CSV file.
Order of the fields
can be used to change the order in which the
fields are extracted. By default, it is the order in which the appear
in the checkbox list from left to right. In the above example, without
information in this field, fe_users.username
comes first, then
fe_users.usergroup
is extracted, then fe_users.name
and so on.
Provide a list of fields separated by a semi-column (one field per
line makes it simple to read) in the text area to change this order.
Let us also note that you can put the same field several time, which
is sometimes useful when you process directly the CSV file.
Fields configuration
can be used to add a configuration for the
field rendering. The syntax is the same as in the SAV Library
Kickstarter but each configuration must start by the full field name.
See after for an example.
Click on the red CSV icon to export your data. Below is the result obtained when the CSV file is imported in LibreOffice Calc.
As it can be seen, the user groups are displayed as a comma-separated list because the fields were exported in the raw mode. By selected, the second checkbox, it is displayed with the same rendering as in a single view.
Depending on the field type, HTML tags can be exported, which is the
case with the usergroup field of the fe_users
table. If you want to
process these tags, use a stdWrapItem attribute for the field . For
example, to remove them, add the following configuration in Fields
configuration
as shown below (see Changing the field configuration ).
Exporting Data to Other Formats¶
The exporting form contains two fields XML file
and XSLT file
which enable the export to other formats.
The XML file
field must be a XML file which will be used as a
template. It may contain:
field markers under the conventional format in the SAV Library Extension Generator, that is
###field_name###
,localization markers under the conventional format in the SAV Library Extension Generator, that is
$$$tag$$$
for a marker in thelocallang.xlf
file,$$$label[field_name]$$$
to obtain the label associated with a field,constant markers under the form
$$$constant[tag]$$$
.
The XML tag may contain special attributes:
sav_type
can be set to:
replaceAlways
: the XML tag and its children will be processed for all exported rows,replaceDistinct
: the XML tag and its children will be processed each time the associatedsav_id
attribute changes in the rows,cutIfEmpty
: the XML tag and its children will be cut if the associatedsav_id
attribute is empty in the row,cutIfNotEmpty
: the XML tag and its children will be cut if the associatedsav_id
attribute is not empty in the row,cutIfEqual
,cutIfNotEqual
,cutIfgreater
,cutIfLower
,cutIfgreaterEqual
,cutIfLessEqual
: the XML tag and its children will be cut if the associatedsav_id
attribute in the row is respectively equal to, not equal to, greater than, less than, greater than or equal to, lower than or equal to, a given value provided by thesav_value
attribute.
sav_id
must be a field name,sav_value
must be a value.
Let us illustrate this principle to generate a docbook article. If your are not familiar with docbook, please read https://www.oasis- open.org/docbook/documentation/reference/html/docbook.html and http://www.sagehill.net/docbookxsl/ . The former is the docbook definitive guide and the later the docbook xsl complete guide.
Assume that we want to produce the FE user list under the form of a
table with four columns: the user image, his/her name, email and
groups. It can be solved used the XML file to_docbook.xml
,
available in the Resources/Private/Files
directory of this
extension. As it can be seen, this file uses several markers and
attributes.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "https://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article lang="en">
<title>List of FE users</title>
<informaltable>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry align="center"></entry>
<entry align="center">$$$label[fe_users.name]$$$</entry>
<entry align="center">$$$label[fe_users.email]$$$</entry>
<entry align="center">$$$label[fe_users.usergroup]$$$</entry>
</row>
</thead>
<tbody>
<row sav_type="replaceAlways">
<entry align="center">
<mediaobject sav_type="cutIfEmpty" sav_id="fe_users.image">
<imageobject>
<imagedata fileref="fileadmin###sys_file.identifier###" width="2cm" scalefit="1" />
</imageobject>
</mediaobject>
</entry>
<entry>###fe_users.name###</entry>
<entry>###fe_users.email###</entry>
<entry><itemizedlist spacing="compact">###fe_users.usergroup###</itemizedlist></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</article>
In order to produce the XML file, the process is the same as for the
CSV export. Each field marker have to be selected to be replaced and
the template file has to be provided in the XML file
field as shown
in the following caption. The configuration was saved in FE users
(docbook)
.
Note
Because DocBook needs the path to the user's image, the Additional tables
and the Additional fields
fiels are filed to retrieve the path from the FAL.
In this example, the document is processed automatically, by calling
for example the FOP docbook processor (https://xmlgraphics.apache.org/fop/), in the extension. In order
to do so, an admin user must allow the use of the php exec function in
the Advanced
folder of the configuration of the extension as shown
in the following caption.
A XSLT file (http://xmlfr.org/w3c/TR/xslt/) is used to process the resulting XML. Output can be transformed to virtually any file format. In this example, it transforms docbook XML file before the FOP processing.
The Exec field is filled with the following input in order to call FOP.
fop -xml ###FILE### -xsl c:/Program Files/fop/xsl/fo/docbook.xsl -pdf ###SITEPATH###/fileadmin/test.pdf
The tag ###FILE###
will be replaced by the resulting file name. The
xsl path for the file name docbook.xsl depends on your installation of
the FOP processor.
The tag ###SITEPATH###
will be replaced by your site path. Here, the
generated file will be test.pdf
in the fileadmin
directory of the
site. It leads to the following caption.
Using a Query for Exporting Data¶
A query may be used instead of using the export view fields to select the data to be exported. In order to do so, the user TypoScript Config field or the group TypoScript Config must contain the following line :
sav_library_example8_ExportWithQuery = *
A new icon should be displayed in the export view.
Clicking on this icon toggle the export view to the query mode where a query can be entered. As it can be seen below, no field are displayed.
Click on the export icon to get the fields.
Finally, select the fields, fill the configuration if any and click again on export icon to get the CSV file.