.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ===================== FORMidable by example ===================== :Created: 2004-12-21T14:35:09 :Changed: 2007-02-13T17:39:57 :Author: Jerome Schneider :Email: typo3dev@ameos.com :Info 3: http://www.ameos.com :Info 4: .. _FORMidable-by-example: FORMidable by example ===================== Extension Key: **ameos\_doc\_formidable\_byex** Copyright 2000-2007, Jerome Schneider, This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml The content of this document is related to TYPO3 \- a GNU/GPL CMS/Framework available from www.typo3.com .. _Table-of-Contents: Table of Contents ----------------- **FORMidable by example 1** **Introduction 2** **How does it works ? 7** Integration of FORMidable in my plugin 7 Quick FORMidable:XML syntax 7 **XML REF 8** Renderlets 8 Validators 22 Control 25 Datahandlers 26 Renderers 29 Events / server events 31 Modifiers, xml pre-compilation, xml inclusion 34 Value / default value management 35 Actionlets 36 FORMidable CORE programming 37 Using debug functionalities 38 How do I ... ? 39 .. _Introduction: Introduction ------------ .. _generated: ((generated)) ^^^^^^^^^^^^^ .. _So-what-s-that-sheet: So what's that sheet ? """""""""""""""""""""" This document presents the FORMidable API (ext: ameos\_formidable) FORMidable is an API for TYPO3 Front End used to create applications where business-logic is separated from the design and from the PHP- code. It's configured in XML. So basically, you create a plugin, create an XML configuration file, call the FORMidable in your plugin giving XML file path as parameter and the API executes what you configured. And you're done. It heavily relies on default behaviors so the conf can be really short. But you can also customize every single feature if you need tailor made application. .. _What-you-can-do-with-FORMidable: What you can do with FORMidable """"""""""""""""""""""""""""""" Mainly automated forms for your website. But what is an application, concretely ? Well: Flexible design, textfields, formfields, and much more Links, buttons, composite formfields, events to interact with the user Data management (create, update, delete ), data browsing, data searching, ... .. _Ok-i-get-it-Yet-another-Form-manager: Ok i get it. Yet another Form manager. """""""""""""""""""""""""""""""""""""" The point is that every web application is based on this stuff. FORMidable can (loves) handle this for (with) you. .. _Screenshots-please: Screenshots, please: """""""""""""""""""" .. _Simple-creation-form: Simple creation form ~~~~~~~~~~~~~~~~~~~~ ( here, fe\_user account creation) |img-1| .. _Simple-form-edition-mode: Simple form, edition mode ~~~~~~~~~~~~~~~~~~~~~~~~~ |img-2| .. _Highly-customized-forms-and-search-forms: Highly customized forms and search forms ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |img-3| .. _Search-list-of-matching-records: Search + list of matching records ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |img-4| .. _Details-of-a-record: Details of a record ~~~~~~~~~~~~~~~~~~~ |img-5| .. _Anything-else-with-links-buttons-images-textfields: Anything else with links, buttons, images, textfields, ... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |img-6| .. _How-does-it-works: How does it works ? ------------------- An application is entirely described in an XML file. This conf defines a lot of subsections, to configure all the elements that make your application work. Namely: - renderlets: objects that will be displayed in your application ( text field, listbox, link, image, button, ... ) - validators: objects checking if the data returned by a renderlet is valid, or not ( required, email, unique in db, ... ) - renderer: one per application ; will process the HTML provided by renderlets ( dev layout, templated layout, ... ) - datahandler: one per application; will execute something with produced data ( insert in base, send mail, search in database, ... ) - actionlets: objects that will be executed when datahandler finishes it's job ( redirect to a page, send an email to someone, generate a report, ... ) As said before, FORMidable needs XML as a configuration. Let's see what's inside this XML. .. _Integration-of-FORMidable-in-my-plugin: Integration of FORMidable in my plugin ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To use FORMidable in your code, you have to create a FORMidable object and to initialize it with some arguments: $this (always) : this parameter will be used to keep the reference to your plugin inside FORMidable path to your xml file uid of the record to edit, (optional, only if you want FORMidable to edit this record) :: $this->oForm = t3lib_div::makeInstance("tx_ameosformidable"); $this->oForm->init( $this, t3lib_extmgm::extPath($this->extKey) . "xml/form1.xml", 25 // uid of the record to edit ( if edition needed ;) ); And then you have to get the generated **HTML** by calling the **render()** method of this object. :: $sHtml = $this->oForm->render(); And you're done ! .. _Quick-FORMidable-XML-syntax: Quick FORMidable:XML syntax ^^^^^^^^^^^^^^^^^^^^^^^^^^^ A typical XML looks like this :: Create/edit an FE user
true true fe_users uid There are always 3 main sections in the XML ( 4 with the root ) ; Each one of these 3 sections is required. **meta** : global informations about the whole applications **control** : holds the configuration for the datahandler (required), renderer (required) and actionlets (optional) **elements** : section containing the renderlets Each tag defining any **renderlet / validator / renderer / datahandler / actionlet** has to be declared as a part of the corresponding namespace ( renderlet:LISTBOX ; datahandler:DB ; renderer:TEMPLATE ; ... ). The second part of those tags, after the colon, defines the **type** of this tag, inside the namespace. Each tag **must** be defined in lowercase, except for types of objects inside namespaces ( renderlet: **LISTBOX** , datahandler: **RAW** , ... ). What is called a **boolean** in the following XML REF is a string “ **true** ” or “ **false** ”, lowercased. What is called **userobj** is a tag that defines either: - a callback to a PHP function inside an object - a section on PHP code to execute inside a CDATA tag, returning something or not - a section of TypoScript inside a CDATA tag. Userobj are optional in most of the cases ; they give the ability to the developper to feed it's application with dynamically generated values rather than static XML ones. .. _XML-REF: XML REF ------- .. _Renderlets: Renderlets ^^^^^^^^^^ .. _renderlet: renderlet:\* """""""""""" This conf applies to all renderlets. Some renderlets might redefine default values for these properties, though. .. ### BEGIN~OF~TABLE ### .. _name: **/name** ~~~~~~~~~ .. container:: table-row Property **/name** Data type string [a-zA-Z0-9\_-] Description Name and id of the field in the form. Name of the corresponding column in the database, also. If none given, an anonymous name will be automatically generated. You **have** to give a name if you want to be able to place the HTML produced by this renderlet into an HTML template ( if you don't know the name, you can't use its tag in the template ) Default random anonymous Advice **Always** give a name unless YNWYD. .. _label: **/label** ~~~~~~~~~~ .. container:: table-row Property **/label** Data type string, Description Label of the field which will be displayed in your application You can give here also a locallang formated string for localization, like **LLL:EXT** :........ **See /displaylabels** Default empty string Advice Always try to use **LLL:EXT** localized strings .. _readonly: **/readonly** ~~~~~~~~~~~~~ .. container:: table-row Property **/readonly** Data type boolean, Description Whether or not to allow modifications on this field. If true, default behavior is to display the human-readable value of this renderlet. Default false Advice .. _renderonly: **/renderonly** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/renderonly** Data type boolean, Description Whether or not to consider data produced by this formfield in the datahandler. More specifically, means should FORMidable insert / update this field in the DB if used with datahandler:DB, or filter results on this column/value when used for searching records with the datahandler:LISTER. Default false Advice Useful when the renderlet value is not meant to be inserted in the database, for instance a formfield used only to build the interface. .. _type: **/type** ~~~~~~~~~ .. container:: table-row Property **/type** Data type string Description This property is a **system** property. It's automatically set to the type of the renderlet declared in the tag, where here type would be set to XYZ. You don't have to declare it, but if you need to, you can modify it at runtime using modifiers. **See modifiers, xml pre-compilation.** Default renderlet type inside the namespace, lowercased Advice .. _custom: **/custom** ~~~~~~~~~~~ .. container:: table-row Property **/custom** Data type string, Description This property is a placeholder where you can place anything you want to be inserted in the HTML of the renderlet. Typically, this will be inserted in the HTML tag of the renderlet; for instance, class=”red”will be, for a renderlet:TEXT HTML, used like this: TS Description This tag allows user to give a TS template that will be used to generate the graphical layout of this renderlet. The TS template can use an automatically generated **params** property that will holds all the distinct HTML parts of this renderlet :: | 10 = TEXT 10.value < params.input 10.wrap =
|
} ]]> **See multichannel-template for more informations about what's available in the params property.** Default empty Advice REALLY powerful if you need tailor-made graph layout for your application. .. _activelistable: **/activelistable** ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/activelistable** Data type boolean, Description If true and if used with datahandler:LISTER, the renderlet will be displayed as a fully functional form field in the list. If false and used with datahandler:LISTER, the renderlet will be displayed as a human-readable readonly value in the list. Default false Advice Set to true on renderlet LINK, BUTTON, ... if you want them to be displayed as active links or button in your list ; .. _data: **/data** ~~~~~~~~~ .. container:: table-row Property **/data** Data type XML subconf Description This tag is the placeholder of all configuration that deals with available data, defaultvalue of the renderlet, available items for listboxes, checkboxes groups, ... Default empty Advice .. _data-defaultvalue: **/** data **/defaultvalue** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** data **/defaultvalue** Data type string, Description Defines the default value for this renderlet. If set, it will be used only when the form has not been already submitted ( first display ) **and** when in creation mode ( not edition mode ) **See value / default value management** Default empty Advice .. _data-value: **/** data **/value** ~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** data **/value** Data type string, Description Defines the value for this renderlet. If set, the renderlet will allways use what's returned by **/data/value** as a value, no matter what the user give in the form field Default empty Advice .. _data-items: **/** data **/items** ~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** data **/items** Data type XML subconf Description Placeholder for the collection of items that will be used by the renderlet. Items are typically the items of a listbox, radiobuttons group or checkboxes group. You can dynamically give an array of items to the renderlet using a **** tag defined at / **data/userobj** . If userobjed, returned value must be an array structured like: :: Array( Array(“caption” => “Item 1”, “value” => “1”), Array(“caption” => “Item 2”, “value” => “2”), Array(“caption” => “Item 3”, “value” => “3”), ) See **/data/items/item** Default empty Advice Makes sense only when the renderlet has to deal with a collection of items .. _data-items-item: **/** data/items **/item** ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** data/items **/item** Data type XML subconf Description Placeholder for an item in the collection See **/data/items/item/caption** and **/data/items/item/value** Default Advice .. _data-items-item-caption: **/** data/items/item **/caption** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** data/items/item **/caption** Data type string, Description Defines the caption of this item. Can be a LLL:EXT locallang string. Default empty string Advice .. _data-items-item-value: **/** data/items/item **/value** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** data/items/item **/value** Data type string, Description Defines the value of this item. Default empty string Advice .. _search: **/search** ~~~~~~~~~~~ .. container:: table-row Property **/search** Data type XML subconf Description Useful only when used with datahandler:LISTER Placeholder for configuring a specific way for the LISTER to search inside the database for this value. Default search is: if value not empty: rdt\_name LIKE '%rdt\_value%' Default empty Advice .. _search-overridesql: **/** search **/overridesql** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search **/overridesql** Data type string, Description Redefines the portion of SQL given by this renderlet to the datahandler:LISTER to override the default LIKE search Example: You would like the search results to be filtered on some criteria if our checkbox renderlet is checked in the searchform ; do something like this: :: empty .. _search-mode: **/** search **/mode** ~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search **/mode** Data type string Description One of **startswith** , **googlelike** **startswith** : search only records within this column starting with **value** **googlelike** : search words like **value** records with **AND** logic and full string if surrounded by quotes **“** Default empty Advice Use the renderlet:CHOOSER with this to have a nice alphabetical-hash selector .. _search-onfields: **/** search **/onfields** ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search **/onfields** Data type string Description Comma-separated list of columns to search on in the database Default empty Advice .. _onclick: **/onclick,** ~~~~~~~~~~~~~ .. container:: table-row Property **/onclick,** **/onmouseover,** **/on...** Data type string, Description Client & Server Events handling. **See section “Events” for more informations** Default empty Advice .. _validators: **/validators** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/validators** Data type XML subconf Description Placeholder for the collection of validators for this renderlet. See the section Validators for more informations Default Advice .. ###### END~OF~TABLE ###### .. _Examples: Examples: """"""""" *Note: screenshots of these examples are made using renderer:STANDARD* .. _Renderlet-TEXT: Renderlet:TEXT ~~~~~~~~~~~~~~ **Plain renderlet:** :: favcolor Which is equivalent to (always prefer this one ;) : :: This renders as: |img-7| **Renderlet with defaultvalue :** :: Renders as: |img-8| **Renderlet with defaultvalue, custom & wrap:** :: style=”background-color: yellow; border: 4px orange dashed;” This will be place before my textbox
|
And this, after. Thank you Mr. Wrap !
]]> Renders as: |img-9| **Using userobj for defaultvalue and label:** :: style=”background-color: yellow; border: 4px orange dashed” This will be place before my textbox
|
And this, after. Thank you Mr. Wrap !
]]> Renders as: |img-10| **Using recombine:** Note: Recombine unactivates the wrap ; so we dont use wrap here, only TS template We give here only the **** tag for this example. To get the full example XML for this renderlet, replace the **** tag in the previous example with this **** tag. ::
|
) 20 = TEXT 20.value < params.label 20.wrap (
The label of this renderlet is: |
Can you figure out the possibilities ?
) 30 = TEXT 30.value < params.help 30.wrap (
This is an array of the available HTML-channels properties for a TEXT renderlet.
| See Documentation at Multichannel Templates for more informations
) } 10.wrap (
Everything inside this pink box is the render of the renderlet:TEXT
|
) ]]> Renders as: |img-11| .. _renderlet-TEXT: renderlet:TEXT """""""""""""" No special conf. **See renderlet:\*** .. _renderlet-TEXTAREA: renderlet:TEXTAREA """""""""""""""""" No special conf. **See renderlet:\*** Renders as: |img-12| .. _renderlet-PASSWORD: renderlet:PASSWORD """""""""""""""""" No special conf. **See renderlet:\*** Renders as: |img-13| .. _renderlet-DATE: renderlet:DATE """""""""""""" All configuration specific to this renderlet is found in / **data/datetime/** This renderlet is designed to handle timestamps. It takes timestamp as an input, and returns timestamp as a value, plus human readable date as an HTML output. .. ### BEGIN~OF~TABLE ### .. _data-datetime-format: **/** data **/** datetime **/format** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** data **/** datetime **/format** Data type strftime() string Description Strftime like string used to customize the display of the date. **See http://www.php.net/strftime** Default required Advice .. _data-datetime-locale: /data/datetime/ **locale** ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property /data/datetime/ **locale** Data type LOCALE string Description Locale code string to localize the date display **See http://www.php.net/setlocale** Default system LOCALE Advice .. _data-datetime-displaytime: /data/datetime **/displaytime/** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property /data/datetime **/displaytime/** Data type boolean Description Whether or not to display the time selector in the js-calendar. Default false Advice .. ###### END~OF~TABLE ###### .. _Examples: Examples: ~~~~~~~~~ **Plain renderlet:DATE** XML: :: Renders as: |img-14| **Renderlet:DATE with time selector, userobj'd defaultvalue and custom property** XML: :: style='width: 200px;' Renders as: .. _img-15-renderlet-FILE: |img-15| renderlet:FILE """"""""""""""""""""""" .. ### BEGIN~OF~TABLE ### .. _data-targetdir: **/** data **/targetdir** ~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** data **/targetdir** Data type string Description path to the directory where files will be uploaded, relative to the root path of the site; Typically: **/typo3temp/tx\_myext\_pi1/** Default required Advice .. ###### END~OF~TABLE ###### Note: uploaded file will be stored in the **/data/targetdir/** directory. If filename already exists, it will be automatically renamed, suffixed with \_(number) (look at the examples) .. _Examples: Examples: ~~~~~~~~~ **Plain renderlet:FILE** XML: :: Renders as: |img-16| Here, this file has been uploaded 8 times in the same folder, so it was suffixed \_7. The link points to the file. .. _renderlet-LISTBOX-CHECKBOX-RADIOBUTTON: renderlet:LISTBOX, CHECKBOX, RADIOBUTTON """""""""""""""""""""""""""""""""""""""" Like CHECKBOX AND RADIOBUTTON, this renderlet uses a collection of items to do the job. .. ### BEGIN~OF~TABLE ### .. _data-items: **/** data **/items** ~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** data **/items** Data type XML subconf Description **See renderlet:\*/data/items** Default required Advice **See renderlet:\*/data/items** .. ###### END~OF~TABLE ###### renderlet:CHECKBOX returns a list of selected items values comma- separated as data. .. _Examples: Examples ~~~~~~~~ **Plain renderlet:LISTBOX** XML: :: Renders as: |img-17| **renderlet:LISTBOX using defaultvalue and userobj'd list of items** XML: :: $sPre . $sPost, "value" => strtolower($sPre . $sPost), ); } return $aItems; ]]> Renders as: |img-18| .. _renderlet-RADIOBUTTON: renderlet:RADIOBUTTON """"""""""""""""""""" **See renderlet:LISTBOX.** .. _renderlet-CHECKBOX: renderlet:CHECKBOX """""""""""""""""" **See renderlet:LISTBOX** renderlet:CHECKBOX acts as a group of checkboxes. If you want a single checkbox, see renderlet:CHECKSINGLE. renderlet:CHECKBOX can handle a list of multiple selected values, comma-separated. .. _Examples: Examples ~~~~~~~~ Same example as for renderlet:LISTBOX, except that now defaultvalue points to several items. XML: :: $sPre . $sPost, "value" => strtolower($sPre . $sPost), ); } return $aItems; ]]> Renders as: |img-19| .. _renderlet-CHECKSINGLE: renderlet:CHECKSINGLE """"""""""""""""""""" No special conf. **See renderlet:\*** renderlet:CHECKSINGLE automatically returns 1 if the checkbox is checked, 0 if not. .. _renderlet-CHOOSER: renderlet:CHOOSER """"""""""""""""" Renders as a list of push-button links. Selected value is returned by the renderlet. Submits automatically on change event. .. ### BEGIN~OF~TABLE ### .. _wrapitem: **/wrapitem** ~~~~~~~~~~~~~ .. container:: table-row Property **/wrapitem** Data type wrap string Description Wrap property for items ( except selected item when / **wrapselected** given ) Default \| Advice .. _wrapselected: **/wrapselected** ~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/wrapselected** Data type wrao string Description Wrap property for selected item Default / **wrapitem** Advice .. _separator: **/separator** ~~~~~~~~~~~~~~ .. container:: table-row Property **/separator** Data type string Description String used for separating each items of the list Default **|** ( equals to pipe ) Advice .. ###### END~OF~TABLE ###### .. _Examples: Examples ~~~~~~~~ **Plain renderlet:chooser** XML: :: |]]> |]]> Renders as: .. _img-20-renderlet-LINK: |img-20| renderlet:LINK """"""""""""""""""""""" Displays as a link. Can also return URL only.Useful for creating links with events handling. ( **See events section** ).NOTE: for being displayed in a list managed by datahandler:LISTER, has to be set as **/activelistable** (= true). **See renderlet:\*/activelistable** for more informations. .. ### BEGIN~OF~TABLE ### .. _url: **/url** ~~~~~~~~ .. container:: table-row Property **/url** Data type string, Description Url to be used in the link. If not given,and if the renderlet value ( **see /data/defaultvalue & /data/value** ) is an URL, then the renderlet value will be used for / **url** Default `javascript:void(0 `_ ); Advice .. _urlonly: **/urlonly** ~~~~~~~~~~~~ .. container:: table-row Property **/urlonly** Data type boolean, Description Whether or not to return only the URL Default **false** Advice .. _label: **/label** ~~~~~~~~~~ .. container:: table-row Property **/label** Data type string, Description If given, will be used as the caption of the link. If not, value will be used. Default **empty** Advice .. _custom: **/custom** ~~~~~~~~~~~ .. container:: table-row Property **/custom** Data type string, Description Use /custom to insert **target** if you need to Default **empty** Advice .. _readonly: **/readonly** ~~~~~~~~~~~~~ .. container:: table-row Property **/readonly** Data type boolean Description A renderlet:LINK is always readonly Default **true** (cannot be changed) Advice .. _renderonly: **/renderonly** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/renderonly** Data type boolean Description As its value can't change, a renderlet:LINK cannot be saved in database. It can hold a value but only for programming commodities. Default **true** (cannot be changed) Advice .. ###### END~OF~TABLE ###### .. _Examples: Examples ~~~~~~~~ **Plain renderlet:LINK** XML: :: Renders as: |img-21| **Renderlet link with userobj and no label** XML: :: _oParent->pi_getPageLink( $GLOBALS["TSFE"]->id, "", array( "someparameter" => 1 ) ) ); ]]> Notes: in a PHP , **$this** always points to the FORMidable object, and **$this->\_oParent** always points to the plugin calling FORMidable. **See FORMidable CORE programming** for more informations. Renders as: .. _img-22: |img-22| """""""" .. _renderlet-BUTTON: renderlet:BUTTON """""""""""""""" A button useful for handling events. **See events section for more information.** .. ### BEGIN~OF~TABLE ### .. _renderonly: **/renderonly** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/renderonly** Data type boolean Description Always true Default **true** Advice .. _readonly: **/readonly** ~~~~~~~~~~~~~ .. container:: table-row Property **/readonly** Data type boolean Description Always true Default **true** Advice .. _activelistable: **/activelistable** ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/activelistable** Data type boolean, Description Redefines default value as true ( different of renderlet:\* ) Default **true** Advice We want a button to be listable by default .. ###### END~OF~TABLE ###### .. _renderlet-IMAGE: renderlet:IMAGE """"""""""""""" Used for displaying image in your application. What else ? ;) .. ### BEGIN~OF~TABLE ### .. _path: **/path** ~~~~~~~~~ .. container:: table-row Property **/path** Data type string, Description Path to the image; **relative to path site; without starting slash** Or an evaluated path like **EXT:my\_ext/images/image.gif** Default **required** Advice .. _imageconf: **/imageconf** ~~~~~~~~~~~~~~ .. container:: table-row Property **/imageconf** Data type TS Description Typoscript used to reprocess image before displaying. See examples. Some effects are available in FORMidable base pack. They are defined in EXT:ameos\_formidable/ext\_typoscript\_setup.txt Default **empty** Advice .. ###### END~OF~TABLE ###### .. _Examples: Examples: ~~~~~~~~~ **Plain renderlet:IMAGE** XML: :: EXT:ameos_testform/res/atari.jpg Renders as: |img-23| **renderlet:IMAGE with imageconf (basepack's shaded effect) and width 100px max** XML: :: EXT:ameos_testform/res/atari.jpg Renders as: |img-24| **renderlet:IMAGE with imageconf (basepack's rounded effect) and width 100px max** XML: :: EXT:ameos_testform/res/atari.jpg Renders as: .. _img-25-renderlet-SUBMIT: |img-25| renderlet:SUBMIT """"""""""""""""""""""""" Renders as a submit button .. ### BEGIN~OF~TABLE ### .. _mode: **/mode** ~~~~~~~~~ .. container:: table-row Property **/mode** Data type string, one of **submit** , **refresh** , **draft** , **test** Description See events section for more informations Default **submit** Advice .. ###### END~OF~TABLE ###### .. _Validators: Validators ^^^^^^^^^^ A **validator** is an object that will check the validity of a data produced by a renderlet against specified criteria. They are declared inside a **renderlet** configuration, in an xml tag named **** , which is a placeholder for **one or several** **** . Each validator has a type declared inside the **validator** namespace. Ex: **validator:DB** , a validator of type DB that checks conditions inside database ; **validator:NUM** , checking numerical constraints on data; ... A validator returns TRUE if data is OK, FALSE in the other case. **NOTE:** Each validator returns TRUE if the data is empty, except the **validator:STANDARD/required** , returning FALSE if the data is empty. This allows to reject data only if given. If validator returns FALSE, it also produce an error message corresponding to what's given in subsection **** of the validator. You can use plain messages or localized LLL:EXT: ... locallang strings if needed. **Example:** *Note: screenshots of these examples are made using renderer:STANDARD* :: In this example, user has to enter it's email address; FORMidable will check if email is given, then if valid, then if not already in database for unicity. Renders: |img-26| After submitting: |img-27| Let's give some weird data: |img-28| **The datahandler will not process data until everything is valid in the form.** Displaying errors like this is the way renderer:STANDARD does by default. To have nicer, customized error messages, use renderer:TEMPLATE ( **see renderer:TEMPLATE** ;). .. _validator-STANDARD: validator:STANDARD """""""""""""""""" This validator does the usual data-checks. .. ### BEGIN~OF~TABLE ### .. _required: **/required** ~~~~~~~~~~~~~ .. container:: table-row Property **/required** Data type Description Checks that data is not empty Default **empty** Advice .. _authentified: **/authentified** ~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/authentified** Data type Description Checks that fe-user is authentified Default **empty** Advice .. _maxsize-value: **/maxsize/value** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/maxsize/value** Data type **integer** Description Checks that data length is < to **value** For text-like renderlets, checks the char length. For listbox/checkbox/radiobutton fields, checks the number of checked items. Default **empty** Advice .. _sameas-value: **/sameas/value** ~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/sameas/value** Data type **string** Description Value has to be the name of an other renderlet. Checks that the value for this renderlet is the same that the value for the given renderlet. Default **empty** Advice Useful when checking password confirmation .. _email: **/email** ~~~~~~~~~~ .. container:: table-row Property **/email** Data type Description Checks that data is a valid email address Default Advice .. _userobj: **/userobj** ~~~~~~~~~~~~ .. container:: table-row Property **/userobj** Data type **** Description Executes the userobj for checking data. If you can't do it using hardcoded valitadors, use this validator. The userobj has to return TRUE if valid, FALSE if not. See example below Default Advice .. ###### END~OF~TABLE ###### .. _Examples: Examples ~~~~~~~~ **validator:STANDARD/userobj** This example demonstrates how to perform custom validation on data: XML: :: Renders as: |img-29| .. _validator-DB: validator:DB """""""""""" Checks DB related conditions. To be used only with datahandler:DB .. ### BEGIN~OF~TABLE ### .. _unique: **/unique** ~~~~~~~~~~~ .. container:: table-row Property **/unique** Data type Description Checks that data is unique inside the table for this column. Default **empty** Advice .. ###### END~OF~TABLE ###### .. _validator-FILE: validator:FILE """""""""""""" Checks FILE related conditions. Useful for checking file after upload. **NOTE: WARNING: if file is rejected by any of validator:FILE, it will be deleted by FORMidable.** **USE only for user-uploaded files. Not meant to test files existing on the server. They would be deleted.** .. ### BEGIN~OF~TABLE ### .. _extension-value: **/extension/value** ~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/extension/value** Data type **string csv** Description Checks that file extension matches one of the list. Takes comma-separated list of file extensions to be matched. Default **empty** Advice .. _filesize-value: **/filesize/value** ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/filesize/value** Data type **integer** Description Checks that filesize is below or equal to given filesize. Filesize in Bytes. Default **empty** Advice .. ###### END~OF~TABLE ###### .. _validator-NUM: validator:NUM """"""""""""" Checks numeric related conditions. .. ### BEGIN~OF~TABLE ### .. _islower-value: **/islower/value** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/islower/value** Data type **integer** Description Checks that data is a number lower than given number. Default **empty** Advice .. _ishigher-value: **/ishigher/value** ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/ishigher/value** Data type **integer** Description Checks that data is a number higher than given number. Default **empty** Advice .. _isbetween-value: **/isbetween/value** ~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/isbetween/value** Data type **string csv** Description Checks that data is a number between given lower and upper bound, comma-separated. Default Advice .. ###### END~OF~TABLE ###### .. _validator-PREG: validator:PREG """""""""""""" Checks validity of data against regex pattern. (See `http://www.php.net/regex `_ ). **Credit for this validator goes to Jérémy Lecour ( jeremy.lecour(a)nurungrandsud(dt)com )** .. ### BEGIN~OF~TABLE ### .. _pattern-value: **/pattern/value** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/pattern/value** Data type **string regex** Description Checks data validity against regex. If pattern prefixed with !, then condition is reversed. Default **empty** Advice .. ###### END~OF~TABLE ###### .. _Control: Control ^^^^^^^ The **** section of the XML is just a placeholder for the **datahandler** , the **renderer** and optionally **actionlets** . See **datahandler** , **renderer** and **actionlets** . .. _Datahandlers: Datahandlers ^^^^^^^^^^^^ Datahandler's job is to **do something** with the data produced by your application. Quite cool, huh ? datahandler will be executed only when form is submitted and all validators are GO. There are several datahandlers available. .. _datahandler-DB: datahandler:DB """""""""""""" This is the most used datahandler. Designed to insert / update records into the given table. This datahandler works by default in **CREATION** mode. This means that it will **insert** form-data into the given table. To make it work in **EDITION** mode, when instanciating FORMidable, give the uid of the record you need to edit as a parameter. Like this: :: $this->oForm = t3lib_div::makeInstance("tx_ameosformidable"); $this->oForm->init( $this, t3lib_extmgm::extPath($this->extKey) . "xml/form.xml", 25 // uid of the record to edit ); (See **Integration of FORMidable in my plugin** for more informations about this) .. ### BEGIN~OF~TABLE ### .. _tablename: **/tablename** ~~~~~~~~~~~~~~ .. container:: table-row Property **/tablename** Data type **string** Description Name of the DB table to work on. Default **required** Advice .. _keyname: **/keyname** ~~~~~~~~~~~~ .. container:: table-row Property **/keyname** Data type **string** Description Name of the primary key in the given table. Default **required** Advice .. _process-beforeinsertion: **/process/beforeinsertion** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/process/beforeinsertion** Data type **** Description Define a userobj here if you want to alter the data that are to be inserted / updated into the database. Takes an array of values as an input, returns an array of values as an output. **See example below.** Default **empty** Advice Useful when you want to add system fields to your table row, like **pid, crdate** , ... If you want to cancel the modification of the data in DB, return an **empty array()** here .. ###### END~OF~TABLE ###### .. _Examples: Examples ~~~~~~~~ **Simple datahandler:DB working on fe\_users table** XML: :: fe_users uid **datahandler:DB working on fe\_users tables, adding pid and crdate to the record using /process/beforeinsertion** XML: :: fe_users uid .. _datahandler-RAW: datahandler:RAW """"""""""""""" The job of **datahandler:RAW** is to give produced data to another data processor (typically a method of your plugin). Useful if you want to use formidable as an interface manager, but still process data yourselves. .. ### BEGIN~OF~TABLE ### .. _callback: **/callback** ~~~~~~~~~~~~~ .. container:: table-row Property **/callback** Data type **** Description Userobj to be executed to process form-data. Reminder: you can access to your plugin using: **$this->\_oParent** in the PHP code of the userobj Default **required** Advice .. ###### END~OF~TABLE ###### .. _datahandler-LISTER: datahandler:LISTER """""""""""""""""" The job of **datahandler:LISTER** is to display a list of records selected in a table AND (optionally) to apply search filters to this selection to turn your form into a searchform. The idea is to use the form generated by FORMidable as a searchform. Of course the searchform is to be used only when needed, because you can also just list the data of a table without search. .. ### BEGIN~OF~TABLE ### .. _tablename: **/tablename** ~~~~~~~~~~~~~~ .. container:: table-row Property **/tablename** Data type **string** Description The name of the table to work on Default **required** Advice .. _keyname: **/keyname** ~~~~~~~~~~~~ .. container:: table-row Property **/keyname** Data type **string** Description Name of the primary key of this table Default **required** Advice .. _template: **/template** ~~~~~~~~~~~~~ .. container:: table-row Property **/template** Data type **XML subconf** Description Placeholder for the template configuration of the list Default **empty** Advice Optional; if none given, the LISTER will try to build a default template for displaying records .. _template-path: /template/ **path** ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property /template/ **path** Data type **string,** **** Description The path to the HTML template file Default **required** Advice EXT:my\_ext/template.html .. _template-subpart: **/** template **/subpart** ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** template **/subpart** Data type **string,** **** Description The subpart of this template to work on. Default **required** Advice Something like ###MY\_LIST### .. _template-customtags: **/** template **/customtags** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** template **/customtags** Data type **XML subconf** Description Placeholder for custom tags that will be added to each row of the list. Collection of **** Default **empty** Advice .. _template-customtags-tag: **/** template **/** customtags **/tag** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** template **/** customtags **/tag** Data type **XML subconf** Description An item that will describe something to add to each row of the list Default **empty** Advice .. _template-customtags-tag-name: /template/customtags/tag/ **name** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property /template/customtags/tag/ **name** Data type **string** Description Name of the tag that will be searched and substituted in every line of the list Default **required** Advice .. _template-customtags-tag-value: /template/customtags/tag/ **value** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property /template/customtags/tag/ **value** Data type **string,** **** Description The value that will be inserted in the template for each line. **See example below** Default **required** Advice .. _search: **/search** ~~~~~~~~~~~ .. container:: table-row Property **/search** Data type **XML subconf** Description Placeholder for configuring all the aspects of the search within records. Default **empty** Advice .. _search-atstartup: **/** search **/atstartup** ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search **/atstartup** Data type **boolean,** **** Description Whether or not to display list at first display of the application. If false, list will be displayed only after first submit. Default **true** Advice .. _search-keepinsession: **/** search **/keepinsession** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search **/keepinsession** Data type **boolean,** **** Description Whether or not to keep list of uids matching search criteria (if any) in session for further usage. Default **false** Advice **See FORMidable CORE API programming** .. _search-sql: **/** search/ **sql** ~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/ **sql** Data type **XML subconf** Description Placeholder for modifying / overriding the SQL query executed to fetch records. Default **empty** Advice .. _search-sql-query: **/** search/sql **/query** ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/sql **/query** Data type **string,** **** Description SQL query that will be used to fetch records from the database Default **empty** Advice Use it with a to build custom query if needed **See FORMidable CORE API programming** .. _search-sql-wheres: **/** search/sql **/wheres** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/sql **/wheres** Data type **XML subconf** Description Placeholder for defining SQL conditions that will be added to the one that FORMidable will automatically build for fetching records. Default **empty** Advice .. _search-sql-wheres-beginbrace: **/** search/sql/wheres **/beginbrace** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/sql/wheres **/beginbrace** Data type **XML tag** Description Adds a “(“ to the SQL query. Define it like this: **** Default **empty** Advice .. _search-sql-wheres-beginbrace: **/** search/sql/wheres **/beginbrace** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/sql/wheres **/beginbrace** Data type **XML tag** Description Default **empty** Advice .. _search-sql-wheres-endbrace: /search/sql/wheres **/endbrace** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property /search/sql/wheres **/endbrace** Data type **XML tag** Description Adds a “)“ to the SQL query. Define it like this: **** Default **empty** Advice .. _search-sql-wheres-where: **/** search/sql/wheres/ **where** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/sql/wheres/ **where** Data type **XML subconf** Description Default **empty** Advice .. _search-sql-wheres-where-term: **/** search/sql/wheres/where **/term** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/sql/wheres/where **/term** Data type **string** Description Column to apply the additional where Default **required** Advice .. _search-sql-wheres-where-comparison: **/** search/sql/wheres/where **/comparison** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/sql/wheres/where **/comparison** Data type **string** Description Type of comparison that will be executed between this term and its value. One of: **IN** , **NOT IN** , **=** , **<** , **>** , **<=** , **>=** , **!=** Default **required** Advice You don't need to care about quotes or braces here, FORMidable will automatically add what your conf needs to be SQL valid. .. _search-sql-wheres-where-value: **/** search/sql/wheres/where **/value** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/sql/wheres/where **/value** Data type **string,** **** Description The value this term will be compared to. Default **required** Advice .. _search-sql-wheres-logic: **/** search/sql/wheres/ **logic** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** search/sql/wheres/ **logic** Data type **string** Description One of: **AND** , **OR** Default Advice .. _process: **/process** ~~~~~~~~~~~~ .. container:: table-row Property **/process** Data type **XML subconf** Description Placeholder for data processing directives Default **empty** Advice .. _process-beforesearch: **/** process **/beforesearch** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** process **/beforesearch** Data type **** Description Takes an array of values to search as an input, returns the modified array of values. Default **empty** Advice **See datahandler:DB/process/beforeinsertion** .. _process-duringlisterraw: **/** process **/duringlisterraw** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** process **/duringlisterraw** Data type **** Description Process **raw database values** for each row that are to be displayed in the list. Takes an array of values to search as an input, returns the modified array of values. Default **empty** Advice **See datahandler:DB/process/beforeinsertion** .. _process-duringlister: **/** process **/duringlister** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** process **/duringlister** Data type **** Description Process **human readable values** for each row that are to be displayed in the list. Takes an array of values to search as an input, returns the modified array of values. Default **empty** Advice **See datahandler:DB/process/beforeinsertion** .. _pager: **/pager** ~~~~~~~~~~ .. container:: table-row Property **/pager** Data type **XML subconf** Description Placeholder for all the configuration that deals with dispatching data across several pages. Default **empty** Advice .. _pager-sort: **/** pager **/sort/** ~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** pager **/sort/** Data type **XML subconf** Description Placeholder for sorting configuration Default **empty** Advice .. _pager-sort-field: **/** pager/sort **/field** ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** pager/sort **/field** Data type **string** Description Default table column on which data will be sorted at first display. Default **/keyname** Advice .. _pager-sort-dir: **/** pager/sort **/dir** ~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** pager/sort **/dir** Data type **string** Description Default direction on which data will be sorted at first display. One of: **ASC** , **DESC** Default **DESC** Advice .. _pager-rows: /pager **/rows** ~~~~~~~~~~~~~~~~ .. container:: table-row Property /pager **/rows** Data type **XML subconf** Description Placeholder for configuration Default **empty** Advice .. _pager-rows-perpage: **/** pager/rows **/perpage** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** pager/rows **/perpage** Data type **number,** **** Description Number of records to display per page Default **5** Advice .. _pager-rows-maximum: **/** pager/rows **/maximum** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** pager/rows **/maximum** Data type **number,** **** Description Maximum number of records to fetch Default **empty** Advice .. _pager-rows-toomany: **/** pager/rows **/toomany** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** pager/rows **/toomany** Data type **string,** **** Description String that will be displayed if the number of records fetch is greater than **/pager/rows/maximum** ( if defined ). If this property is not defined, the LISTER will just limit it's display to the **/pager/rows/maximum** ( if defined ). If used in a userobj, params are given telling how much records have been counted ( **numrows** ), and how many records can be handled at max( **maximum** ). **See getting parameter into userobj** for more informations. Default **empty** Advice .. _pager-rows-active: **/** pager/rows **/active** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** pager/rows **/active** Data type **string** Description Subpart handler in the list template to be used for displaying active line ( if the LISTER is combined with another form using datahandler:DB for editing records found in the list ). Something like **###ROWACT###** Default **empty** Advice .. _pager-rows-alternate: **/** pager/rows **/alternate** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** pager/rows **/alternate** Data type **string csv** Description Comma-separated string of template subpart handlers to be used alternatively to display all the lines of the list. Something like **###ROW1###,###ROW2###** Default **required if LISTER used with template** Advice .. _pager-rows-window: **/** pager/rows **/window** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** pager/rows **/window** Data type **number** Description Number of pages to display in the pager for navigating thru pages Default Advice .. _callback: **/callback** ~~~~~~~~~~~~~ .. container:: table-row Property **/callback** Data type **** Description **** that will be called to give the produced list HTML to your plugin. typically something like: :: $aParams = array_pop(func_get_args()); $this->_oParent->sListHTML = $aParams["HTML"]; // $this->_oParent allways point to your plugin // this way the HTML for the list is stored // in a member var of your plugin for further usage We do this because the main **render()** method of FORMidable that you call in your plugin returns only the HTML generated for the form; **NOTE:** render() method returns the HTML if the renderer of this application did not returned anything, which is the case when you use **renderer:VOID** ; in that case ( when you don't want a searchform and the list, but just the list ) you don't have to provide this **/callback** as **render()** method will return the list HTML. See renderer:VOID for more informations about how to do searchform- less lists. .. ###### END~OF~TABLE ###### **See demo extensions for concrete examples of the LISTER** .. _Renderers: Renderers ^^^^^^^^^ Renderers are the glue that sticks all the HTML generated parts together. Let's snort some renderers. .. _renderer-VOID: renderer:VOID """"""""""""" The simplest renderer of all. It does nothing with the generated HTML. Useful when you want to display a LIST using a lister without displaying any searchform. No configuration for this one. .. _renderer-STANDARD: renderer:STANDARD """"""""""""""""" The renderer used at development time. It takes the HTML parts generated by renderlets and validators, and display them separated by line breaks wrapped in **

** HTML tags. No configuration. .. _renderer-TEMPLATE: renderer:TEMPLATE """"""""""""""""" The most powerful renderer available for FORMidable. Takes a template file as an input and inserts HTML parts by substituting stuff like **{my\_marker}** with the corresponding HTML. Tags are formatted like this: **{my\_renderlet\_name}** Each renderlet renders it's full layout ; the produced HTML will be accessible using the syntax **{my\_renderlet\_name}** . But there is more to a renderlet output than meets the eye. See Multichannel-template to have more information about this. .. ### BEGIN~OF~TABLE ### .. _template: **/template** ~~~~~~~~~~~~~ .. container:: table-row Property **/template** Data type **XML subconf** Description Placeholder for the template configuration of the list Default **required** Advice .. _template-path: /template/ **path** ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property /template/ **path** Data type **string,** **** Description The path to the HTML template file Default **required** Advice EXT:my\_ext/template.html .. _template-subpart: **/** template **/subpart** ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** template **/subpart** Data type **string,** **** Description The subpart of this template to work on. Default **required** Advice Something like ###MY\_FORM### .. _template-errortag: **/** template **/errortag** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/** template **/errortag** Data type **string** Description The tag that will be susbtituted to insert errors into template. Something like this: :: myerrortag Note: FORMidable sets automatically a **cssdisplay** channel to this tag, which will contain **block** if there were errors in the data user gived, or **none** in the other case. Set to **none** at first display.This way you can display or not the container of the errors easily if needed, doing something like this: ::

Some fields have not been correctly completed:

{errors}
This way the **div** and it's content will be displayed only if there were errors. See multichannel-template for more informations about this kind of feature. .. ###### END~OF~TABLE ###### .. _Multichannel-template: Multichannel-template """"""""""""""""""""" Each renderlet renders it's full layout. It's available in the template using this marker syntax **{my\_renderlet\_name}** . But each renderlet has also a lot of other informations to give about it's job than just the compiled HTML. So Multichannel-template is a way to access these informations in your template using a simple dotted notation is your template marker. **Example: I would like to display the label of my renderlet in a red span after the field itselves** You would do something like this, in your HTML template: :: {my_renderlet_name.input}
{my_renderlet_name.label} There are plenty of these HTML bonuses inside each one of the renderlets. To know exactly what's available on a renderlet, use the **.help** channel of this renderlet in your template. Like this: :: {my_renderlet_name.input}
{my_renderlet_name.label} Available properties form my renderlet: {my_renderlet_name.help} **This way you can totally reshape the layout of a renderlet within your template.** **See also /renderlet:\*/recombine** for a TS approach on using these channels. .. _Events-server-events: Events / server events ^^^^^^^^^^^^^^^^^^^^^^ Every renderlet in FORMidable implements an event-management layer. It allows the user to interact with your FORMidable application far beyond the traditional uses of a form. There are 2 types of events : .. _Javascript-events-client-events: Javascript events ( client events ) """"""""""""""""""""""""""""""""""" These events are wrappers for the Javascript events of your web browser. Available events are: .. ### BEGIN~OF~TABLE ### .. _onactivate: **/onactivate** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/onactivate** Description Fires when the object is set as the active element. .. _onafterupdate: **/onafterupdate** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onafterupdate** Description Fires on a databound object after successfully updating the associated data in the data source object. .. _onbeforeactivate: **/onbeforeactivate** ~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onbeforeactivate** Description Fires immediately before the object is set as the active element. .. _onbeforecut: **/onbeforecut** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onbeforecut** Description Fires on the source object before the selection is deleted from the document. .. _onbeforedeactivate: **/onbeforedeactivate** ~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onbeforedeactivate** Description Fires before the activeElement is changed from the current object to another object in the parent document. .. _onbeforeeditfocus: **/onbeforeeditfocus** ~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onbeforeeditfocus** Description Fires before an object contained in an editable element enters a UI- activated state or when an editable container object is control selected. .. _onbeforepaste: **/onbeforepaste** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onbeforepaste** Description Fires on the target object before the selection is pasted from the system clipboard to the document. .. _onbeforeupdate: **/onbeforeupdate** ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onbeforeupdate** Description Fires on a databound object before updating the associated data in the data source object. .. _onblur: **/onblur** ~~~~~~~~~~~ .. container:: table-row Property **/onblur** Description Fires when the object loses the input focus. .. _onchange: **/onchange** ~~~~~~~~~~~~~ .. container:: table-row Property **/onchange** Description Fires when the contents of the object or selection have changed. .. _onclick: **/onclick** ~~~~~~~~~~~~ .. container:: table-row Property **/onclick** Description Fires when the user clicks the left mouse button on the object. .. _oncontextmenu: **/oncontextmenu** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/oncontextmenu** Description Fires when the user clicks the right mouse button in the client area, opening the context menu. .. _oncontrolselect: **/oncontrolselect** ~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/oncontrolselect** Description Fires when the user is about to make a control selection of the object. .. _oncut: **/oncut** ~~~~~~~~~~ .. container:: table-row Property **/oncut** Description Fires on the source element when the selection is removed from the document and added to the system clipboard. .. _ondblclick: **/ondblclick** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/ondblclick** Description Fires when the user double-clicks the object. .. _ondeactivate: **/ondeactivate** ~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/ondeactivate** Description Fires when the activeElement is changed from the current object to another object in the parent document. .. _ondrag: **/ondrag** ~~~~~~~~~~~ .. container:: table-row Property **/ondrag** Description Fires on the source object continuously during a drag operation. .. _ondragend: **/ondragend** ~~~~~~~~~~~~~~ .. container:: table-row Property **/ondragend** Description Fires on the source object when the user releases the mouse at the close of a drag operation. .. _ondragenter: **/ondragenter** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/ondragenter** Description Fires on the target element when the user drags the object to a valid drop target. .. _ondragleave: **/ondragleave** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/ondragleave** Description Fires on the target object when the user moves the mouse out of a valid drop target during a drag operation. .. _ondragover: **/ondragover** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/ondragover** Description Fires on the target element continuously while the user drags the object over a valid drop target. .. _ondragstart: **/ondragstart** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/ondragstart** Description Fires on the source object when the user starts to drag a text selection or selected object. .. _ondrop: **/ondrop** ~~~~~~~~~~~ .. container:: table-row Property **/ondrop** Description Fires on the target object when the mouse button is released during a drag-and-drop operation. .. _onerrorupdate: **/onerrorupdate** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onerrorupdate** Description Fires on a databound object when an error occurs while updating the associated data in the data source object. .. _onfilterchange: **/onfilterchange** ~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onfilterchange** Description Fires when a visual filter changes state or completes a transition. .. _onfocus: **/onfocus** ~~~~~~~~~~~~ .. container:: table-row Property **/onfocus** Description Fires when the object receives focus. .. _onfocusin: **/onfocusin** ~~~~~~~~~~~~~~ .. container:: table-row Property **/onfocusin** Description Fires for an element just prior to setting focus on that element. .. _onfocusout: **/onfocusout** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/onfocusout** Description Fires for the current element with focus immediately after moving focus to another element. .. _onhelp: **/onhelp** ~~~~~~~~~~~ .. container:: table-row Property **/onhelp** Description Fires when the user presses the F1 key while the browser is the active window. .. _onkeydown: **/onkeydown** ~~~~~~~~~~~~~~ .. container:: table-row Property **/onkeydown** Description Fires when the user presses a key. .. _onkeypress: **/onkeypress** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/onkeypress** Description Fires when the user presses an alphanumeric key. .. _onkeyup: **/onkeyup** ~~~~~~~~~~~~ .. container:: table-row Property **/onkeyup** Description Fires when the user releases a key. .. _onlosecapture: **/onlosecapture** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onlosecapture** Description Fires when the object loses the mouse capture. .. _onmousedown: **/onmousedown** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onmousedown** Description Fires when the user clicks the object with either mouse button. .. _onmouseenter: **/onmouseenter** ~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onmouseenter** Description Fires when the user moves the mouse pointer into the object. .. _onmouseleave: **/onmouseleave** ~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onmouseleave** Description Fires when the user moves the mouse pointer outside the boundaries of the object. .. _onmousemove: **/onmousemove** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onmousemove** Description Fires when the user moves the mouse over the object. .. _onmouseout: **/onmouseout** ~~~~~~~~~~~~~~~ .. container:: table-row Property **/onmouseout** Description Fires when the user moves the mouse pointer outside the boundaries of the object. .. _onmouseover: **/onmouseover** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onmouseover** Description Fires when the user moves the mouse pointer into the object. .. _onmouseup: **/onmouseup** ~~~~~~~~~~~~~~ .. container:: table-row Property **/onmouseup** Description Fires when the user releases a mouse button while the mouse is over the object. .. _onmousewheel: **/onmousewheel** ~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onmousewheel** Description Fires when the wheel button is rotated. .. _onmove: **/onmove** ~~~~~~~~~~~ .. container:: table-row Property **/onmove** Description Fires when the object moves. .. _onmoveend: **/onmoveend** ~~~~~~~~~~~~~~ .. container:: table-row Property **/onmoveend** Description Fires when the object stops moving. .. _onmovestart: **/onmovestart** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onmovestart** Description Fires when the object starts to move. .. _onpaste: **/onpaste** ~~~~~~~~~~~~ .. container:: table-row Property **/onpaste** Description Fires on the target object when the user pastes data from the system clipboard to the document. .. _onpropertychange: **/onpropertychange** ~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onpropertychange** Description Fires when a property changes on the object. .. _onreadystatechange: **/onreadystatechange** ~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onreadystatechange** Description Fires when the state of the object has changed. .. _onresize: **/onresize** ~~~~~~~~~~~~~ .. container:: table-row Property **/onresize** Description Fires when the size of the object is about to change. .. _onresizeend: **/onresizeend** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onresizeend** Description Fires when the user finishes changing the dimensions of the object in a control selection. .. _onresizestart: **/onresizestart** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onresizestart** Description Fires when the user begins to change the dimensions of the object in a control selection. .. _onselect: **/onselect** ~~~~~~~~~~~~~ .. container:: table-row Property **/onselect** Description Fires when the current selection changes. .. _onselectstart: **/onselectstart** ~~~~~~~~~~~~~~~~~~ .. container:: table-row Property **/onselectstart** Description Fires when the object is being selected. .. _ontimeerror: **/ontimeerror** ~~~~~~~~~~~~~~~~ .. container:: table-row Property **/ontimeerror** Description Fires whenever a time-specific error occurs, usually as a result of setting a property to an invalid value. .. ###### END~OF~TABLE ###### .. _Examples: Examples: ~~~~~~~~~ **renderlet:TEXT with onfocus and onblur events** :: **renderlet:TEXT with multiline onfocus event** :: **renderlet:BUTTON with userobj'd onclick event** :: .. _PHP-events-server-events: PHP events (server events) """""""""""""""""""""""""" A server event is a section of PHP code that will be executed only if the user triggers the corresponding event on the renderlet. There is a listener of server event for each properties of the event list of section **Javascript events** . .. _Examples: Examples ~~~~~~~~ **renderlet:BUTTON with onclick server event** :: When pressed, the web page refreshes and executes the userobj attached to the triggered event. .. _Modifiers-xml-pre-compilation-xml-inclusion: Modifiers, xml pre-compilation, xml inclusion ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _TO-DO: TO DO """"" .. _Value-default-value-management: Value / default value management ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _TO-DO: TO DO """"" .. _Actionlets: Actionlets ^^^^^^^^^^ .. _TO-DO: TO DO """"" .. _FORMidable-CORE-programming: FORMidable CORE programming ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _TO-DO: TO DO """"" .. _Using-debug-functionalities: Using debug functionalities ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _TO-DO: TO DO """"" .. _How-do-I: How do I ... ? ^^^^^^^^^^^^^^ .. _TO-DO: TO DO """"" |img-30| FORMidable by example - 39 **`Typo3 Ameos `_** .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 355 .. :id: Image1 .. :name: Image1 .. :width: 443 .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :height: 451 .. :id: Image2 .. :name: Image2 .. :width: 446 .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 129 .. :id: Image3 .. :name: Image3 .. :width: 450 .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :height: 600 .. :id: Image4 .. :name: Image4 .. :width: 459 .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :height: 523 .. :id: Image5 .. :name: Image5 .. :width: 458 .. |img-6| image:: img-6.png .. :align: left .. :border: 0 .. :height: 584 .. :id: Image6 .. :name: Image6 .. :width: 446 .. |img-7| image:: img-7.png .. :align: left .. :border: 0 .. :height: 55 .. :id: Image7 .. :name: Image7 .. :width: 163 .. |img-8| image:: img-8.png .. :align: left .. :border: 0 .. :height: 62 .. :id: Image8 .. :name: Image8 .. :width: 179 .. |img-9| image:: img-9.png .. :align: left .. :border: 0 .. :height: 115 .. :id: Image9 .. :name: Image9 .. :width: 373 .. |img-10| image:: img-10.png .. :align: left .. :border: 0 .. :height: 115 .. :id: Image10 .. :name: Image10 .. :width: 373 .. |img-11| image:: img-11.png .. :align: left .. :border: 0 .. :height: 210 .. :id: Image11 .. :name: Image11 .. :width: 669 .. |img-12| image:: img-12.png .. :align: left .. :border: 0 .. :height: 66 .. :id: Image18 .. :name: Image18 .. :width: 214 .. |img-13| image:: img-13.png .. :align: left .. :border: 0 .. :height: 66 .. :id: Image19 .. :name: Image19 .. :width: 214 .. |img-14| image:: img-14.png .. :align: left .. :border: 0 .. :height: 205 .. :id: Image12 .. :name: Image12 .. :width: 400 .. |img-15| image:: img-15.png .. :align: left .. :border: 0 .. :height: 234 .. :id: Image13 .. :name: Image13 .. :width: 469 .. |img-16| image:: img-16.png .. :align: left .. :border: 0 .. :height: 71 .. :id: Image14 .. :name: Image14 .. :width: 277 .. |img-17| image:: img-17.png .. :align: left .. :border: 0 .. :height: 118 .. :id: Image16 .. :name: Image16 .. :width: 138 .. |img-18| image:: img-18.png .. :align: left .. :border: 0 .. :height: 206 .. :id: Image15 .. :name: Image15 .. :width: 137 .. |img-19| image:: img-19.png .. :align: left .. :border: 0 .. :height: 185 .. :id: Image17 .. :name: Image17 .. :width: 127 .. |img-20| image:: img-20.png .. :align: left .. :border: 0 .. :height: 66 .. :id: Image20 .. :name: Image20 .. :width: 214 .. |img-21| image:: img-21.png .. :align: left .. :border: 0 .. :height: 33 .. :id: Image21 .. :name: Image21 .. :width: 214 .. |img-22| image:: img-22.png .. :align: left .. :border: 0 .. :height: 42 .. :id: Image22 .. :name: Image22 .. :width: 410 .. |img-23| image:: img-23.png .. :align: left .. :border: 0 .. :height: 325 .. :id: Image23 .. :name: Image23 .. :width: 295 .. |img-24| image:: img-24.png .. :align: left .. :border: 0 .. :height: 176 .. :id: Image24 .. :name: Image24 .. :width: 163 .. |img-25| image:: img-25.png .. :align: left .. :border: 0 .. :height: 130 .. :id: Image25 .. :name: Image25 .. :width: 122 .. |img-26| image:: img-26.png .. :align: left .. :border: 0 .. :height: 55 .. :id: Image26 .. :name: Image26 .. :width: 182 .. |img-27| image:: img-27.png .. :align: left .. :border: 0 .. :height: 106 .. :id: Image27 .. :name: Image27 .. :width: 318 .. |img-28| image:: img-28.png .. :align: left .. :border: 0 .. :height: 102 .. :id: Image28 .. :name: Image28 .. :width: 291 .. |img-29| image:: img-29.png .. :align: left .. :border: 0 .. :height: 102 .. :id: Image29 .. :name: Image29 .. :width: 291 .. |img-30| image:: img-30.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102