EXT: SAV Library Extension Generator¶

What does it do?¶

The SAV Library extension contains:

• an “Extension Generator” based on the conventional kickstarter,
• a library which is required to run the generated extensions.

Thanks to simple configuration parameters it generates extensions without any PHP coding . The SAV Library Extension Generator includes:

• Creation of multiple views of the data,
• Front end input of the data,
• Views with folders,
• Simple interface in the Kickstarter with Context Sensitive Help,
• Generation of emails,
• Generation of RTF files using database tags,
• Data export in CSV format,
• Many other features.

Important: this extension is now obsolete. It is replaced by the SAV Library Plus extension which works with the SAV Library Kickstarter.

Screenshots¶

Important development remarks¶

When the development of this extension started, it was chosen to modify the Kickstarter using the XCLASS method. All the functionnalities of the Kickstarter are preserved and it can be used normally. The current version of the SAV Library Extension Generator works the Kickstarter 0.4.0, 0.5.0, 0.5.1 .

If you have developed extensions with the previous version of the SAV Library Generator, that is version 2.x.y, you will need to update all your extensions. A tool in the Extension Manager was specially designed to easily update extensions.

However the Kickstarter is an old code which is quite difficult to change because it does not clearly separate the code generation and the BE interface. Furthermore, having the generator and the library in the same extension is not the best solution. Therefore, I have decided to develop a specific kickstarter for the SAV Library extension. This new kickstarter, called sav_library_kickstarter, is based on fluid and extbase and is available in the TER ( https://typo3 .org/extensions/repository/view/sav_library_kickstarter/current/ ). Please use this new SAV Library Kickstarter for your developements .

The SAV Library extension still contains the kickstarter XCLASS files only for compatibility reasons with TYPO3 versions which doe not have “fluid” and “extbase”. For now, the dependency between the extension “sav_library” and “kickstarter” has been removed.

The latest developments of the SAV Library extension are available on TYPO3 Forge ( Extension Generator ).

Remember that “It's not abug, it's amissingfeature”. If you find some, please use the bug tracker on the TYPO3 Forge.

Related extensions¶

Several examples of extensions generated by the SAV Library are available in the TER.

• SAV Library Examples (“sav_library_exampleX”, where X is a number) - these extensions are described in the tutorial section.
• Other examples can be found in the “Other examples” section of this manual:
  • Downloading documents (sav_download)
  • Minutes of meetings (sav_meetings)
• SAV Library Filters (“sav_filter_name”, where name is the filter name) - these extensions are specially designed to work with the extensions generated by the SAV Library.
• SAV Library Extends (“sav_library_extends”) - this extension was designed to help you to add or overload default methods used in the SAV Library Extension Generator.

Installation¶

If not installed, download the extension “kickstarter” and install it.

Download the extension “sav_library” and install it.

Read the tutorial sections

Updating previously generated extensions¶

In case of a major release of the SAV Library Extension Generator you will need to update all the previously generated extensions.

A special tool is available in the Extension Manager to perform this task easily. Click on the Extension Manager and select “SAV Library extensions update” in the selector box.

All the loaded extensions which have been generated the SAV Library Extension Generator are displayed.

For each extension, several information are displayed:

The name of the extension, that is the extension key. By clicking on the name, the tool provides a quick access to an extension. It will be opened in the kickstarter.

By default, the SAV Library Extension Generator will generate a XML configuration file in the “pi1” directory of the extension. You may prefer to use the “php-array” generation. In that case, please uncheck the checkbox in the column “XML Generation”.

The list of the form used in the extension since one extension may contain several forms. For each form you can select if the plugin will behave as a USER for this form, that is caching will be possible. By default, the plugin will behave as a USER_INT for all forms, that is no caching is available. If you want to make a form behaving as a USER, just check it.

Check the update flag if you want to rebuild the extension. When clicking on the button “Update the extensions”, only the extensions with a “update” checkbox selected will be updated.

The version of the SAV Library Extension Generator which has been used to generate the extension is displayed. If the version of the generator is older than 3.0.0, “Unknown” is displayed.

The current version of the extension is displayed.

Kickstarter 0.4.0 has introduced changes in the type of the field in the SQL generation. The “SAV Library extensions update” tool will inform you about the required changes. Click once again on the button “Update the extensions” to execute the SQL field updates.

Running the tests¶

A bench of unit tests has been developed for the SAV Library Extension Generator. To run the tests :

Download the extension “phpunit” from the TER and install it.

Download the extension “sav_library_example1” from the TER and install it.

Click on PHPunit in the “Admin tools”.

Select the test to run.

New tests will be added in the next versions of the SAV Library Extension Generator.

Introduction¶

This section describes the different available configurations of the plugin generated by the SAV Library Extension Generator. Read the tutorial section first .

Flexform associated with the Plugin¶

The configuration of each generated extension is done by means of a flexform. The flexform has three folders:

• General
• Input controls
• Advanced

Help : click on the icon to get the context sensitive help.

Select form : use this selector to select the form name. Let use recall that the “sav_library” makes it possible to build several forms associated with the same extension, thus providing different views of your tables.

Show all if no filter : if set, all items are displayed if no filter is applied, for example by means of the “sav_filter_abc” extension.

If no information available : use the selector to choose what to display when no information are available.

Max number of items : maximum number of items that will be displayed in a page. If set to 0, all items are displayed.

Help page : use this selector to choose a page of your site which will be use as an help page for your extension. In this case, an icon is displayed in the title bar of your extension.

Help : click on the icon to get the context sensitive help.

Input on form : if set, Front End inputs are allowed (set by default).

Allowed groups : if you select user groups, user must belong to one of these groups to be allowed to input data in the Front End.

Input Admin field : put here a field under the form “tableName.fieldName” (if you use only “fieldName”, the main table is taken as “tableName”). This will restrict the input to users that have “Admin” right for this field in their TS Config. For example, if one user has “extKey_Admin=value1,value2” in his TS Config , he will be allowed to edit or delete items for which “fieldName” is equal to “value1” or “value2” for the extension “extKey”. The fields or the folders which have the attribute “editAdminPlus= 1;” can be modified if the user has the “Admin+” rights. For example, if the TS Config is “extKey_Admin=value1+,value2” , the user is an “Admin+” for the records where “fieldName” is equal to “value1” and just “Admin” for the records where “fieldName” is equal to “value2”. Users become “Super Admin” if their TS Config is “extKey_Admin=*”.

No “new” button : no new button is added to the form. It means that you can modify existing records but you cannot create new record.

No “edit” button : an edit button will not be added in front of the records in “show All” views.

No “delete” button : a delete button will not be added in front of the records in “show All” views.

Add a “delete” button only for records created by the user : add a "delete" button only for records created by the user.

Input start date : if set, inputs in the Front End will not be possible before this date.

Input end date : if set, inputs in the Front End will not be possible after this date.

Apply date limit : use the selector to set either “Nobody”, “All”, “Admin plus users”, “All excluding Super Admin”. The date limit is applied according to this selector.

Help : click on the icon to get the context sensitive help.

Permanent filter : you can use this field to add a where clause that will be “anded” to the where clause of the form query.

Add a fragment (# content id) to links : the content id is added as a fragment to the links.

Allow the use of the “query” property: the “query” property makes it possible to execute queries in “input” or “update” forms. Because any query may be executed, for security reason, only admin users can check this field when this property is needed.

Allow the use of the exec function in export: The use of the php exec function is allowed in export which makes the execution of text processors possible, for example.

Storage page : this option makes it possible to store your record in a storage page, for example a “sysfolder”, otherwise records are stored in the current page. When this option is used, records are fetched in the storage page and in the pages defined in the “starting point” if any.

Apply caching to : When the plugin is running as a USER for the form, that is when caching is required, these option control the caching for various buttons or links. If an option is set, a cHash will be added to the link.

Pages whose cache will be cleared on update in the input form : When the plugin is running as a USER for the form, that is when caching is required, updating items in the input form will clear the cache for the current page by default. If you need to clear the cache for other pages, select them here. Use also this option when the plugin is running as a USER_INT for the form and you need to clear the cache of another page used by a form for which caching is used.

Changing the icons¶

The extension “sav_library” comes with default icon files associated with its various functionalities. There are two ways of changing the icons:

Create a “res/icons” directory in the generated extension in which you put your icon files with the same names as in the default directory “res/icons” in the extension “sav_library”.

Create a directory where you want in the fileadmin directory, in which you put your icon files with the same names as in the default directory. Then, in the “Setup” of your template, write:plugin.tx_yourExtensionNameWithoutUnderscores_pi1.iconsDir = yourIconsDirwhere “yourExtensionNameWithoutUnderscores” is the key of the extension you have created with the generator, but without underscores if any, and “yourIconsDir” is the relative path of the directory where you have put your icon files.

Changing the template for the views¶

The extension “sav_library” comes with a default template file for the views. It is the file “sav_library.tmpl” in the “res” directory of the “sav_library” extension. There are two ways of changing the template:

Put your template file in the “res” directory of your extension under the name “yourExtensionName.tmpl”, where “yourExtensionName” is the key of the extension you have created with the generator.

Put your template file where you want in the fileadmin directory. Then, in the “Setup” of your template, write:plugin.tx_yourExtensionNameWithoutUnderscores_pi1.template = yourFileNamewhere “yourExtensionNameWithoutUnderscores” is the key of the extension you have created with the generator, but without underscores if any, and “yourFileName” is the filename with its relative path (i.e. fileadmin/....).

Changing the default CSS¶

The extension “sav_library” comes with a default CSS which is in the file “ext_typoscript_setup.txt” of the SAV Library directory. You may overload the styles in your CSS file to change them globally. You also may want to modify the default styles only for one specific extension. In that case, you just have to put a CSS file in the “res” directory of your extension under the name under the name “yourExtensionName.css”, where “yourExtensionName” is the key of the extension you have created with the generator. This CSS will be automatically added in the HTML <head> section (see “sav_library_example7” for such a case).

Configuration of the Queriers, Viewers, Item Viewers¶

The extension “sav_library” comes with a default configuration for queries, viewers, item viewers. It can be easily changed.

The configuration is defined by the file “sav_library.xml” which is in the “res” directory of the “sav_library” extension.

The xml file contains three parts:

• Definition of the queriers
• Definition of the viewers
• Definition of the item viewers

<update>
  UPDATE_defaultQuerier
</update>

<viewDate>
  <type>input</type>
  <conditions>
    <condition index="0">
      <field>eval</field>
      <ope>isEqual</ope>
      <value>date</value>
    </condition>
  </conditions>
</viewDateTime>

Modification of the SAV Library configuration¶

You may want to change the configuration and adapt it to your specific needs. For this purpose, a special extension called “sav_library_extends” was developed to extend the SAV Library. Download this extension from the TER and install it.

In the extension directory, you will find several classes which extends the SAV Library classes by means of XCLASS. Looking to the file “sav_library_extends.xml” in the directory “res”, you will see that a new item viewer “Example” is added. It is associated with a new type “example”.

Then, check the class “ux_tx_savlibrary_defaultItemviewers” in the file “class.ux_tx_savlibrary_defaultItemviewers.php” to understand how to add the new item viewer.

Check also the class “ux_tx_savlibrary_defaultVerifiers” in the file “class.ux_tx_savlibrary_defaultVerifiers.php” to see how to add a new verifier.

Now download the extension “sav_library_example5” and install it. It is a very simple example. Edit it in the kickstarter to see how the new type was associated with the field. Finally, use the extension in FE. Type “Hello” in the field to see the effect of the new verifier.

Reference for the field configuration¶

The SAV Library Extension Generator is based on the kickstarter. Therefore, the TCA configuration generated by the kickstarter is available and can be changed for each view by means of the field configuration interface. In the example below, the default width (size attribute in the TCA) is replaced by the value 40.

The SAV Library Extension Generator makes it possible to enter data in the Front End. However, since extensions are generated by means of the kickstarter, in most cases data can also be input in the Back End using the regular interface.

The following configurations have been added for the SAV Library Extension Generator. They are organized in the alphabetic order and the TCA type is recalled in parentheses. Of course, no type is provided for the general configuration which can be applied to any field and to the function options.

content =
 SELECT fe_users.uid as uid, fe_users.name as label
 FROM tx_mytable_rel_myfield_mm,fe_users
 WHERE
  tx_mytable_rel_myfields_mm.uid_local=###user###
 AND
  tx_mytable_rel_myfields_mm.uid_foreign=fe_users.ui
 ORDER by label;

format = %A %B %Y;

format = %A %B %Y at %H:%M;

AddToUploadFolderFromField = my_field;

windowBodyStyle = fontweight:bold\;font-color:blue\;;

xmlLabel = LLL:EXT:my_ext/locallang_db.xml:tx_myext.my_field.I.;

SELECT email AS value FROM fe_users WHERE ...

SELECT email AS value FROM fe_users WHERE ...

SELECT email AS value FROM fe_users WHERE ...

reqValue= SELECT name AS value
FROM fe_users
WHERE uid=(SELECT cruser_id FROM tx_mytable WHERE uid=###uid###);

Field configuration by means of the page TS Config¶

The configuration of any field can be changed by means of the page TS Config. The syntax is the following:

tx_extensionKey.formName.viewType.fieldName.fieldProperty = propertyValue.

For example, assume that one wants to change the width and the height of the image in the “All” view in the example 1.

• The “extensionKey” must have no underscore, i.e. “savlibraryexample1”,
• the “formName” is “Contact”,
• the “viewType” is “showAll” (use “showSingle” or “inputForm” for the other types),
• the “fieldName” is “image”,
• the “fieldProperty” is “width” or “height.

It leads to the following configuration:

tx_savlibraryexample1.Contact.showAll.image.width =200
tx_savlibraryexample1.Contact.showAll.image.height = 200

Maintenance configurations¶

The SAV Library Extension Generator includes flags to deal with maintenance operation.

A global maintenance flag is available at the SAV Library level using the Extension Manager. If you check the flag, a maintenance message will be displayed by all extensions built with the SAV Library and filters will not be displayed.

If you provide a list of users'id, separated by a comma, then these users will still see the extensions and the filters.

Global maintenance is useful for developers when global changes are performed on the SAV Library.

The maintenance can also be performed at the extension level. In order to have a maintenance flag in the Extension Manager, you must select “Add maintenance” when saving you extension in the Kickstarter.

A flag will be added for the extension, in the Extension Manager. If you check it, a maintenance message will be displayed except for allowed users in the configuration of the SAV Library.

Configuration of the code generation¶

You can either choose to have the configuration generated as a XML file or directly included as a php array in the pi1 class of the generated extension. Let us assume that we are generating the extension “sav_library_example1”.

• If you select the checkbox “Generate XML configuration”, the configuration will be saved in the file “pi1/ tx_savlibraryexample1_ pi1.xml”. The method initExtConfig() is automatically modified to read the configuration from the XML file. This configuration is set by default when the SAV Library Extension Generator is switched on.
• If you do not select this checkbox, the configuration generated by the kickstarter is saved in the file “pi1/class.tx_savlibraryexample1_ pi1.php” under the form of a php-array in the method initExtConfig().

Caching¶

A caching feature was introduced with the version 3.1.0 of the SAV Library Extension Generator. The plugin behaviour may be changed for each form. By default, the plugin runs as USER_INT for each form, that is no caching is performed. By selecting the checkbox “Allow caching” in the “Forms” section of the Kickstarter, the plugin will run as USER for this form. It means that caching will be set. A “cHash” parameter is added to each item links used to access to the “showSingle” view associated with the item.

A “cHash” parameter can also be added to other links such as:

• the close button,
• arrows in form and/or subform,
• page selector in form and/or subform.

This configuration is possible in the “Advanced” folder tab of the flexform associated with the plugin (see below).

When the plugin is running as USER (caching enabled) and an item is updated in the “inputForm” view, the cache of the current page is cleared on saving so that updated information could be displayed. If you need to clear the cache of other pages, select this pages in the flexform.

When the plugin is running as USER_INT (caching disabled) and an item is updated in the “inputForm” view, it may be needed to clear the cache of pages where another form of the same extension is running as USER. For example, it is the case when one uses an administration form and other forms to display the data. Select the pages whose cache must be cleared in the flexform.

Introduction¶

This example is taken from http://www.typo3journal.info/articles/developpement.html . It creates a contact list with the first name, last name, street, zip code, city and an image of the contact.

You can download this example from the TER (sav_library_example1). Install it and enjoy. The following sections explain how to create the extension and the new features, if you do not download it.

Creation of the extension¶

Create the extension by filling the language, plugin, table, field sections using the Kickstarter as in the original tutorial.

Using the extension¶

Create a page and insert a plugin content element and select “Contact list” in the plugin selector.

The configuration of the plugin is performed by means of a flexform which comes with default values. Just select your form name, that is “Contact” in the “Select form” selector, save your content element and clear the cache .

Go to your page in Front End and you should see the following caption (message should be in French if your configuration is in French).

Click on the right icon to be in the input mode. A new icon appears at the left hand side of the form. Click on it to input a new item.

Your generated input form is shown. As it can be seen on the following caption, the size of the field firstname is longer than the other fields of the same type. This is due to the configuration parameter “size = 40;” that we have added. The other fields take the default configuration of the Kickstarter, that is a default size of 30.

Fill the form with information. Use the browser to select the image and save.

When your have completed your input quit the input form. Note that you can also use the save and close icon. Now, your extension will display one item in your “All” view.

Click on the toggle mode button to add another item, edit the previous one or suppress it.

At that level, nothing more can be done and we cannot display information in our “Single” view. Thus, we need to modify slightly our extension. Let us assume that we want to open the “Single” view when clicking on the image.

Click on the extension manager, select the extension and select “Edit in Kickstarter”. In fact, with “sav_library” the kickstarter is used as a configuration tool.

Click on the table “Members” then on the tab “All” and finally go to the image field by clicking on it.

Now, we will add a configuration parameter to the image field. Using “func = makeItemLink;” we create an item link associated with the field.

Save your new extension by clicking on “View result” then on “WRITE” as done previously. Now, go to your extension, reload, click on the image and you will access to the “Single” view.

Let us note that if you click on the icon at the right hand side, you will access to the “Input” view and be able to edit the content.

How to ?¶

<label index="pi_list_browseresults_page"></label>

Introduction¶

This example is taken from Kasper's video Episode III (http://typo3.org/documentation/videos/wmv-format/). It creates a list of CD albums. It includes artist name, title of the album, date of purchase, cover image, artist web link, category fields.

You can download this example from the TER (sav_library_example2). Install it, add your CD categories in the Back End and enjoy. The following sections explain how to create the extension and the new features, if you do not download it.

Creation of the extension¶

Proceed exactly as in the video.

Define your views, query and form as in Example 1.

Using the extension¶

Create a page and insert a plugin content element and select “CD Collection” in the plugin selector.

The configuration of the plugin is performed by means of a flexform which comes with default values. Just select your form name, that is “CD Album” in the “Select form” selector, save your content element and clear the cache .

Add your CD categories in the Back End (in list mode, create on or several “CD Category” records: Rock, Jazz, Pop...).

Finally, go to your page in Front End and add items to your collection.

As it can be seen, a new icon is associated with the fields “artist” and “album_title”. It indicates that these fields are required (if you have selected “Required” as shown in the video, of course !). You will not be able to save your record if you do not fill these fields and an error message will be displayed.

Let us note that you can also mark any field as required using the configuration parameter:

required = 1;

You can use a date picker by clicking on the button associated with a date.

The icons displayed for the RTE depend on the Front End configuration of the RTE.

How to ?¶

Introduction¶

This example illustrates other features of the extension generator (MM table, email link, fields on the same line).

You can download this example from the TER (sav_library_example3). Install it, add your CD categories in the backend and enjoy. The following sections explain how to create the extension and the new features, if you do not download it.

Creation of the extension¶

Duplicate the extension from sav_library_example2 using the kickstarter as shown below:

• Type sav_library_example3 in the input window;
• Click on “Update result” ;
• Click on “WRITE”;
• Install the new extension.

How to ?¶

Introduction¶

This example makes it possible to add your friends and to lend them your CDs. It illustrates other features of the extension generator (MM relation in a double window selector, input table which is not in relation with an item).

You can download this example from the TER (sav_library_example4). Install it, add your CD categories in the backend and enjoy. The following sections explain how to create the extension and the new features, if you do not download it.

Creation of the extension¶

Duplicate “sav_library_example3” as explained in the previous section.

Using the extension¶

Add your friends. In the double-window selector, double-click on the items to make them go from one window to the other. The left hand side defines what is saved in the table.

Finally, input the lendings of your CDs.

Introduction¶

This example shows how to extend the SAV Library with your own methods. It is described in section 4.7.

Introduction¶

This example shows how emails and RTF file generation can be used. You can download this example from the TER (sav_library_example6).

Install the extension,

Copy the file “invoice.rtf”, which is in the extension directory, in the “fileadmin” directory,

Add the following line in the field TSconfig of the page where you have installed the extension: tx_savlibraryexample6.View1.inputForm.email_flag.mailSender = `your_email@your <mailto:your_email@your>`_ _provider It will overload the email sender defined in the extension as it will be described in the configuration section.

The objective of this example is a very simple conference registration tool. It contains different fields:

• the participant name,
• the participant address,
• the registration items,
• the participant email,
• the email flag which is used to send emails,
• the email language,
• the link for the RTF file.

Use the input form to enter a conference participant as in the following caption.

Then select the email language (default or French) and click on the email icon. If the email is correct, the form will slightly change as shown below. You cannot click on the email icon anymore (if you need to re-send the email, cancel the checkbox at the right hand side of the email icon and save the form).

You should have received an email as the one below:

Dear Yolf,

Thank you for your registration to the conference.

Your registration includes:

X Conference
- Proceedings
X Meals
X Banquet


Your invoice will be available at the registration desk.

Looking forwards to seeing you.

Best regards,

The conference organization committee.

To generate the RTF file, click on the icon associated with the invoice, then open the generated file by clicking on the link and print it (the fields are automatically updated).

The configuration explained¶

Open the extension in the Kickstarter and select “SAV Example6 – Email and RTF” in the “New Database Tables”, then select the “Input” folder. As it can be seen, only the fields “email_flag”, “email_language” and “invoice” have special configurations.

How to ?¶

Introduction¶

The aim of this extension is to deal with multiple forms of the same table and to explain how update views can be used. It creates a guest book which is inspired from the extension “ve_guestbook ” (Modern guest book) available in the TER. You can download this example from the TER (sav_library_example7). This extension uses a table with the following fields:

• the guest firstname,
• the guest lastname,
• the guest email,
• the guest website,
• the guest message,
• a comment field.

We want to have three forms associated with this table:

• one form for the guest input (FORM),
• one form for the list of guest inputs (LIST),
• one form for a teaser of the most recent entries (TEASER).

For the guest input, we want to avoid spams and to control the content. Therefore, we want the following behavior:

The guest will answer to a captcha, then his/her email will be required.

If he/she has given a valid email, he/she will receive a personal link by email.

Using this link, the guest will be able to input data. His/her firstname, lastname and message should be required fields.

The guest input will only appear on your website if you validate the data.

To perform this task, we will use new concepts: the “update view” and the filter “sav_filter_pageaccess” (you already know the filter “sav_filter_abc” used in example 1 - cf. 5.1.10.4).

Extension overview¶

Edit the extension “sav_library_example7” in the Kickstarter to get an overview. It contains:

• Three forms (FORM, LIST, TEASER),
• Four views (FORM_update, FORM_All, LIST_All, TEASER_All),
• Three queries (FORM_Query, LIST_Query, TEASER_Query).

The guest input form (FORM)¶

Click on “FORM” in the “Forms” section. As you can see, the form has a “Show all” view, an “alt” view and a query.

The “Alt” view, named “FORM_Update” is used to generate the guest input form. The “Show all” view is used to validate the data in the administration mode. Now, let us analyze each view.

The guest input list (LIST)¶

Nothing very special here. The form LIST includes a conventional “show All” view. Analyze the view, the query and the field configurations (use the Context Sensitive Help if necessary). Below are two useful comments.

The teaser (TEASER)¶

The form “TEASER” includes a conventional “show All” view. Analyze the view, the query and the field configurations (use the Context Sensitive Help if necessary). The only specific configuration concerns the field “message”. We want to have it cropped to 60 characters and have a more link right to the text to go to the page where the “LIST” form is.

• “stdWrapValue =crop = 60|...;” defines a conventional TS stdWrap property. You can add here full TS syntax. Do not forget that the configuration field is ended by a semi-column, therefore if you need a semi-column in your TS, write it “;”.
• “addRightIfNotNull = $$$more$$$;” adds the label to the right hand site of the content if it is not null. The localization marker $$$more$$$ is used and will be replaced by its value in “pi1/locallang.xml”.
• “funcRight = makeLink;” applies the internal function “makeLink”, which creates an internal link, to the right hand side part, that is to the more link.
• “setUidRight = 123;” defines the page uid associated with the link. The value 123 is just for example, you can either replace it by your page uid or overload it using the TS pageConfig as explained in the configuration section “Field configuration by means of the page TS Config”.

If the extension is correctly installed, you should get:

Installation and configuration¶

Click on the following link to access to the service
Guest input
This link is valid only for one request.

Template and CSS files¶

You have certainly remarked that the forms and the styles used in the guest book were not the same as in the other SAV Library examples. The reason is very simple. The extension “sav_library_example7” comes with its own template and CSS files. By convention:

• if a file “extensionKey.tmpl” is in the “res” directory of an extension, this file is used for the template instead of the default one,
• if a file “extensionKey.css” is in the “res” directory of an extension, this file is loaded in the <head> section of the HTML. It is used to overload several default styles.

Introduction¶

The aim of this tutorial is to show how an extension can be easily built from an existing table. It will also be explained how to export data in CSV from the extension.

The example deals with the fe_users table from which we want to build two forms :

• The first one (USER) is for the authenticated user who wants to manage his/her personal data.
• The second one (ADMIN) is for a FE Admin user who may manage all users and export them.

You can download this example from the TER (sav_library_example8).

Extension overview¶

Edit the extension “sav_library_example8” in the Kickstarter to get an overview. It contains:

• Two forms (USER, ADMIN),
• Five views (USER_All, User_Input, ADMIN_All, ADMIN_Single, ADMIN_Input),
• Two queries (USER_Query, ADMIN_Query).

The organization of the forms is quite similar to the previous examples. Just click on them to analyze it. Let us focus on the configurations associated with the existing table “fe_users” by clicking on the link “fe_users”. As it can be seen, all fields have type “Only shown in SAV Form”.

By clicking on the link Import fields from table as “Only shown in SAV form” , all fields from the table “fe_users” were imported, then unwanted fields were removed.

The user form (USER)¶

In this example, it was chosen to design a very simple form consisting in the display of the user image field. The image is associated with a link, that is a <a> tag, to open the user form input.

.tx-savlibraryexample8-pi1-USER .sav-library .showAll {width:62px;background-color:#ffffff;}
.tx-savlibraryexample8-pi1-USER .sav-library .showAll .title {display:none;}
.tx-savlibraryexample8-pi1-USER .sav-library .showAll .items .item {border:none;background-color:#ffffff;}

The administration form (ADMIN)¶

The administration form is used in the Front End to manage, give rights, export FE users. It is based on a conventional query, “Show all”, “Show single” and “Input form” views for which no specific configuration is needed. Just click on the different views and tabs to see how fields are grouped.

Installation and configuration¶

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 TS Config field or in a group TS Config :

sav_library_example8_Export = *

In general, it is done in the Back End. However, our extension makes it possible to do it in the Front End for the user as shown below.

Now, close the view and verify that you obtain a new “CSV” icon in the ADMIN “Show All” 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 “test”, 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.

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.

Click on the red CSV icon to export your data. Below is the result obtained when the CSV file is imported in OpenOffice Calc.

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 the locallang.xml file, $$$label[field_name]$$$ to obtain the label associated with a field,
• constant markers under the form $$$constant[tag]$$$ (e.g. $$$constant[PATH_site]$$$).

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 associated “sav_id” attribute changes in the rows,
  • “cutIfEmpty”: the XML tag and its children will be cut if the associated “sav_id” attribute is empty in the row,
  • “cutIfNotEmpty”: the XML tag and its children will be cut if the associated “sav_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 associated “sav_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 the “sav_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 http://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 “res” directory of this extension. As it can be seen, this file uses several markers and attributes which are in bold in the following listing.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://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="$$$constant[PATH_site]$$$###fe_users.image###" width="2cm" scalefit="1" />
              </imageobject>
            </mediaobject>
          </entry>
          <entry>###fe_users.name###</entry>
          <entry>###fe_users.email###</entry>
          <entry>###fe_users.usergroup###</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)”).

The resulting file name is the same as with the CSV format, e.g. “sav_library_example8_admin_28_2009_08_04_08_37.csv”. It is built as follows: “extensionName_formName_contentId_year_month_da y_hour_minute.csv”.Save the generated file and rename it if you want. Then, use your favorite docbook processor. For example, the following caption was obtained using FOP ( http://xmlgraphics.apache.org/fop/ ) to produce a pdf output.

As you may also add a XSLT file ( http://xmlfr.org/w3c/TR/xslt/ ), the resulting XML output can be transformed to virtually any file format. For example, this process was used to produce limesurvey import files ( http://www.limesurvey.org/ ). It was also used to transform docbook XML file before the FOP processing, especially when RTE field content are used. RTE content is HTML based, therefore , <p>, <ul>, <ol> ... tags have to be transformed to docbook tags.

Finally, you may want to automatically process the document, by calling for example the docbook processor, 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.

It will lead to a new field in the FE export form as shown below:

Fill this field with your command (it will be saved if you use the save icon). In the above caption, the following input is used for calling the FOP command.

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. In our example it will be replaced by “sav_library_example8_admin_28_2009_08_04_08_37.csv”. 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.

Introduction¶

The aim of this tutorial is to show how to include XML JpGraphs into an extension (see the extension “sav_jpgraph” for detailed information and a tutorial).

In this example, we want to display list of events as Gantt graphs. Each graph is a period of time as, for example months or quarters. Two forms are requested:

• The first one (Admin) will be used to input events in FE. An event includes a title, a begin and a end date, a category. Categories will be input in BE. They have a name and a color which will be used in the Gantt graph.
• The second one (Display) is the Gantt graph display.

You can download this example from the TER (sav_library_example9).

FE input events (Admin)¶

If you have followed the previous tutorials, you are now familiar with the SAV Library Extension Generator. The “Admin” form has three views: “Admin_All”, “Admin_Single” and “Admin_Input”.

Download the extension “sav_library_example9” from the TER and open it in the Kickstarter.

Look at each folder tab and analyze the configuration of each field.

Create a page and a sysfolder as shown below.

Insert the extension in the page “Admin” and configure the “Storage page” in the “Advanced tab” so that it points to the sysfolder (“Events” in the example).

In the List mode (Web->List), create the categories and the periods in the sysfolder. Use color names recognized by JpGraph library. In this example, the year events are organized by quarters.

Go to the Front End and insert events. Events are displayed in the “All” view by decreasing order of the begin date (see the “Order clause” in the “Admin_Query”).

Gantt graphs display (Display)¶

The “Display” form has only one view : “Admin_All”. This view displays only one field named “graph”. Its configuration is the following:

The fields with a type XML JpGraph are not created in the database. They are displayed in the view if selected.

The configuration includes several lines:

• graphTemplate = typo3/ext/sav_library_example9/res/events.xml; defines the file to be used as a template for the graph display.
• markers = marker#begin = ###beginPeriod###, marker#end = ###endPeriod###; This attribute is used to define XML SAV JpGraph markers. The syntax is a comma-separated list of definitions. Let us analyze the first one: “marker#begin = ###beginPeriod###”. It says that the “marker” whose id is “begin” in the template will be replace by the SAV Library marker “###beginPeriod###”, that is by the alias “beginPeriod”. Thus it is necessary for this alias to be defined as shown in the query section of the form.

Now, download the extension “sav_jpgraph” from the TER and install it.

Then, install the extension in the page where you want to display the graph.

In the folder tab “Options” of the page, set the “General Record Storage page” to the folder where the data are stored.

In the folder tab “General” of the extension, select the form “Display” and set the starting point to the sysfolder containing your events.

In the folder tab “Input controls”, uncheck “Input on form”.

Save and go to your Front End page. You should obtain something similar to the following view, depending on your events.

Finally, open the files “events.xml” and “eventsTemplate.xml” in the directory “res” of the extension and analyze them. The file “eventsTemplate.xml” is the general template for the graph display (see the extension “sav_jpgraph” for more details). The file “events.xml” contains the user definitions for the references used in the general template. The only tricky part is the use of the SQL variable @row to number the position of the bar plots.

Using the graph with a year selector¶

To introduce a year selector, we are going to use a new filter called “SAV Filter Selectors”.

Download the extension “sav_filter_selectors” from the TER and install it. Let us note that this extension is very useful to develop quickly selectors, checkboxes, radio buttons, search boxes which can be used to filter extensions produced by means of the SAV Library Generator ... even if the syntax is sometimes surprising !

Introduction¶

The aim of this tutorial is to show how to use TypoScript into an extension.

In this example, we want to display a gallery of pictures. We will use three views in only one form for the sake of the simplicity (see previous examples to create an admin form):

The “showAll” view to display small images.

The “inputForm” to enter the picture, its title, a description and the address corresponding to the picture.

The “showSingle” view with a special organization. The picture is on the left, then the title and the description is displayed at the right of the picture and, finally, the google map, where the marker is defined by the address, goes to the right of the description. By clicking on the image, it should be displayed in its original size.

Several authenticated users may use the plugin. Each user can modify or delete the records he/she has created.

• Download this example from the TER (sav_library_example10) and install it.
• Download also the extension “wec_map” from the TER, read the documentation, get your google map API key and install it.

The “showAll” view¶

The template of this view is very simple since the only field to display is the image. However, we want to take advantage of the TYPO3 image processing instead of using the conventional modification of the size of the image through the properties “width” and “height”.

When the field is an image and you use the property “tsProperties”, an IMAGE cObject is generated with the provided TS properties. You can use markers to refer to the fields. In the example, the configuration is the following:

func = makeItemLink;

tsProperties =
file = uploads/tx_savlibraryexample10/###image###
file.width= 100
;

The first property is already known. It makes it possible to open the “showSingle” view by clicking on the image.

The second one is just TypoScript syntax for an IMAGE cObject. It defines the file using the ###image### marker, that is the file name and it sets the width to 100px. You may insert any other TS property as, for example, GIFBUILDER.

The syntax is exactly the same as in TypoScript. Do not forget to end the property by a semicolon. If you need a semicolon in a TypoScript property, please use “;”.

The last problem to solve in the “showAll” view is to have several images on the same line instead of having them one per line. It can be simply done by changing the default style (See the file “sav_library_example10.css” in the “res” directory) as follows:

.tx-savlibraryexample10-pi1-Gallery .sav-library .showAll .items .item {
        width:120px;height:100px;background-color:#ffffff;
}

The “inputForm” view¶

This view has nothing special. No configuration is needed. Of course you can change the size of the input fields if needed.

The “showSingle” view¶

In this view, we have to deal with two problems:

• positioning correctly the fields,
• executing the plugin “wec_map”.

wrapItem = <div class="container"><div class="image"> | </div>;

tsObject = <plugin.tx_thePluginName_pi1;

tsObject = COA;

tsProperties =
10 = TEXT
10.dataWrap = <script type="text/javascript">setTimeout("drawMap_map{field:uid}()",500)\;</script>
20 = < plugin.tx_wecmap_pi1
20 {
 height = 300
 width = 300
 showDirections = 0
 prefillAddress = 0
 initialMapType = G_NORMAL_MAP
 showInfoOnLoad = 0
 controls {
 showOverviewMap = 0
 showMapType = 1
 showScale = 0
 mapControlSize = small
 }
 markers.1 {
 title = ###title###
 street = ###address###
 city = ###city###
 zip = ###zip###
 country = ###country###
 }
}
;

cutIf = address = EMPTY;

Configuration of the plugin¶

The last step is the configuration of the plugin so that the authenticated users can only modified their images.

This can be simply done by using the “cruser_id” field in the “Input Admin Field” of the flexform as shown below.

Downloading documents (sav_download)¶

Minutes of meetings (sav_meetings)¶

whereSelect=###group_list=sav_meetings###;

tx_savmeetings.Meetings.inputForm.participants.whereSelect = ###group_list=testgroup###
tx_savmeetings.Meetings.inputForm.proposed_by.whereSelect = ###group_list=testgroup###

Sponsors¶

Thanks to:

Dipool ( http://www.dipool.net/ ) for supporting the development of the “tsObject” and “tsProperties” properties and the extension “sav_library_example10”. It has also supported the development of a special processing for workspaces.

Credits¶

Thanks to:

Paul Boomkamp and Thomas Hirt for having detected several bugs in the version 3.0.0.

Stable 3.3.0¶

Stable 3.2.3¶

Stable 3.2.2¶

Stable 3.2.1¶

Stable 3.2.0¶

Beta 3.1.3¶

Beta 3.1.2¶

Beta 3.1.1¶

Beta 3.1.0¶

Beta 3.0.5¶

Beta 3.0.4¶

Beta 3.0.3¶

Beta 3.0.2¶

Beta 3.0.1¶

Beta 3.0.0¶

Beta 2.0.8¶

Beta 2.0.7¶

Beta 2.0.6¶

Beta 2.0.5¶

Beta 2.0.4¶

Beta 2.0.3¶

Beta 2.0.2¶

Beta 2.0.1¶

106