Platinum sponsors
As I mentioned above, the dynaflex extension is configurable through an array called DCA. These DCA can beconfigured on various places in your extension or the TYPO3 installation.
The first possibility is to write the DCA directly into the tca.php of your extension. This is was is obsolete and strongly recommended to not do it this way!
The second way to provide a DCA is from within a DCA class. This is described in section “Where to instantiate” earlier in this document. This is the most common way to configure DynaFlex.
A third way is to provide the DCA via TypoScript. If you don't provide a class in the ext_localconf.php file but a simple “TS”, DynaFlex will not try to load a class but fetches the Tsconfig from the current page. DynaFlex tries to load the path “dynaflex.[tablename]”.
The DCA itself consists of an unlimited number of subarrays. Every single one of this arrays stands for modifications on a single element inside of an array. A field inside of a backend form for example.
We (I) call this a single configuration array (SCA).
There is only one special Key in the DCA:
Key | Datatype | Description |
|---|---|---|
workingTable | string | With this option you explicit define on which table you want to work. This is useful if you have a special multi table view like columnsOnly. If you don't set this, the workingTable is detected automatically. |
The SCA contains some meta information of what should be done and an array of modifications. This table is an overview of the keys in the SCA:
Key | Datatype | Description |
|---|---|---|
path | path (string) | The path inside the array that should be modified. See section “Basics > Paths” |
parseXML | boolean | If this is true, the data that is located inside the path will be passed through the xml2array method of TYPO3 before anything is done with the fielddata. If it is false, nothing is done with the data, and it's passed as is to through the rest of the processing. The default value is true. This is needed for some kinds of modification, for example if you want to add simple text in the “showitem” field of the TCA which is not XML at all. |
modifications | array of ->MA | An array of modification arrays. See section “$DCA > Modification Array” |
uid | integer | OBSOLETE! This is not needed anymore! Dynaflex gets this UID from the runtime environment when it is called. |
The modification array (MA) is the array where all the configuration is stored how the array should be modified. This table is an overview of the keys in the MA:
Key | Datatype | Description | Valid for method |
|---|---|---|---|
method | -> method | This string names the method that is used for modifying the current element. | |
type | -> type | A detailed description of the method. (see -> type) | add, move |
condition | -> conditions | DEPRECATED! If you only have a single condition that should be checked, you can use this option. It's recommend to use the key “conditions” instead! | all |
conditions | -> conditions | Defines in witch cases a modification is performed or not. For a detailed description of the possible keys for a condition (see -> conditions). | all |
source | -> source | Defines where the base data, for creating the fields, is fetched from. (see -> source) | add |
source_type | -> source_type | The type of the source. (see -> source_type) | add |
source_config | -> source_config | The configuration how the source is fetched. (see -> source_config) | add |
field_config | array of -> field_config | An array of field configurations. That means that you can configure as much fields as you want, and for every element of the source ALL of this configurations will be performed. For example you can add two fields for every entity inside of an arbitrary table. | add |
sheet_config | -> sheet_config | Configures how a sheet is inserted into the FlexForm | add |
allUserFunc | string | This user function is called when all data was fetched. The data that was fetched is passed to the user function. Dynaflex expects an array with configurations that fit the definition of “field_config” as result from the userfunction. | add (types: fields) |
path | path (string) | The path inside the FlexForm XML structure where the fields should be added. | add |
inside | path (string) | The path inside the FlexForm, where the routines for adding staticXML are working in. For a simple FlexForm this would be: ROOT/el If you want insert staticXML inside of an existing sheet (which can be created by modification before this one!) the path could be something like: sheets/mySheet/ROOT/el | add (types: staticXML) |
beforeAll | integer | If this is set, the data is inserted before all other elements inside the path that was configured by “inside”. | add (types: staticXML) |
after | string | The name of the element, after which the data should be inserted. The frame in which this is performed (FlexForm or single sheet) has to be configured by “inside”. | add (types: staticXML) |
data | string | The XML data that insert if the type is staticXML | add (types: staticXML) |
label | ->getLabel | Defines the label for an inserted sheet. | add (types: sheet, sheets) |
name | string | Defines the name for an inserted sheet. | add (types: sheet) |
element | string | The name of the element (field) for which an action should be performed. | remove |
elements | array | If you want to perform more than one modification for a single condition you can use this key to collect all modifications here. This is just for performance issues because the condition is only checked one time. | all |
config | array | Normal field configuration like it's used in TCA and -> field_config -> config. If it used for type “append” this array looks like: $config = array ( text => 'my text to append' ); | add (types: field, append) |
table | string | Identifies a section inside the TYPO3_CONF_VARS array. | move (types: extraFields) |
Type of method that is used for modification
Type | Description |
|---|---|
add | Instructs the dynaflex extension to add something somewhere. |
move | Moves an element from one position to another.Since version 0.2.0 it also can move fields inside of the showitem section of the TCA. |
remove | Removes (deletes) an element from the array |
function_call | Calls a user defined method. The dynaflex extension passes the uid of the dataset the class is processing. (If it is set in the SCA) and the complete data of the field the class is processing. (The field is defined in the SCA and is normally an array with a FlexForm data structure.) The format how the function has to be defined is the same than in the TCA (see user defined fields). It's something like: tx_myext_myclass->myUserFunction It's up to you, that the class file is included as soon as the function is instantiated and the method is called. |
The type defines what method should be performed exactly. This table is an overview of the possible types for every method (Currently only types for method “add” are implemented!):
Type | Description | Method |
|---|---|---|
staticXML | Inserts a static XML at a specific position inside the source. The position can be configured by MA->beforeAll and MA->after. The data that inserted is fetched from MA->data. | add |
sheet | Inserts a new sheet inside of an FlexForm. The label is fetched from MA->label and the name from MA->name. | add |
sheets | Inserts a number of sheets depending on source_config. | |
field | Adds a single field. It's really simple. All you have to configure is MA->config and MA->label. | add |
fields | Adds more fields. This can be used to create fields in dependency to database contents. See:
| add |
extraFields | If the type “extraFields” is set with method “move”. Dynaflex will fetch a list of fieldnames from the TYPO3_CONF_VARS array a parses them to modify the showitems section in the TCA. | move |
append | Appends some text after the content that is defined in DCA->path. An exampe for this can be adding additional tab dividers to a FlexForm. Such a configuration could look like: $DCA = array ( array ( 'path' => 'tx_myext/types/0/showitem', 'parseXML' => false, 'modifications' => array ( array ( 'method' => 'add', 'type' => 'append', 'config' => array ( 'text' => ',--div--;divider 1,myField;;;;1-1-1', ), ), ), ), ); | add |
The condition decides if a modification should be performed or not.
Key | Datatype | Description |
|---|---|---|
if | ->if | the kind of condition that is checked. |
source | string | This defines what should be used as base for the condition. Possible values are:
|
table | string (SQL) | The table where the compare value is selected from. |
select | string (SQL) | The fields that are selected for comparison. For some kinds of “if”, this have to be a SINGLE field in the table. |
where | string (SQL) | The condition for selection. You can use the marker “###uid###” here wich is substituted with the UID of the current content element. |
cefield | string | Defines the field from which data is fetched if source is “cce”. |
isXML | boolean | If this is true, the result from the database is handled as XML. That means, that the result is converted into an array. Otherwise the data is handled as it is. |
path | path (string) | If isXML is true and the data value for the comparison is fetched from this path inside of the array that was converted from the XML. Important! This path is something different than the flexform structure. If you fetch data from a flexform data field you'll get a flexform data-structure which is pretty different. A path could look like this for example: data/sheet_0/lDEF/df_field_0/vDEF |
compareTo | mixed | This is the value the value from the database is compared to or a regular expression. This key is used for the “if” types:
|
You have to configure when a condition is true or false. Normally you fetch some data from a database and compare the result of that query with a fixed value. How this comparison is done, is decided by if.
Type | Description |
|---|---|
hasValues | Returns true if the select query returns anything. |
isLess | Returns true if the result from the database is less than the “compareTo” value. This only works, if the result of the database is an integer!!! |
isEqual | Returns true if the result from the database equals the “compareTo” value. This should work with strings and integers. |
notEqual | Returns true if the result does NOT equal the “compareTo” value. |
isGreater | Returns true if the result from the database is bigger than the “compareTo” value. This only works, if the result of the database is an integer!!! |
regex | Returns true if the regular expression in “compareTo” matches. This can be useful if you want to check for a substring for example. |
If you're adding fields, you have various possibilities what is used as base for creating that fields. This table gives you an overview about the possible sources for creating the fields.
Type | Description |
|---|---|
db | The data is fetched from the database. The detailed configuration how the data database query is built configured by “source_config”. (see -> source_config) |
conditions | The data is the same as that result that is fetched from the database that was needed to check the condition. Make sure, that you have a proper configured condition! (see -> condition) |
field | The data is fetched from any field inside the form. It doesn't matter if the field is defined in the TCA and has it's own field in the database or if the field is defined inside a flexform datastructure. (see -> source_config) |
* | A free text. In most cases this should be a comma separated list. (see -> source_type) |
With the source_type you can configure how the basedata for creating the fields is pre-processed. This is needed to make sure that the routines for creating fields are getting the right data format.
Type | Description |
|---|---|
csl | Comma Separated List. Mostly used if the value of -> source is a manual entered text. (see -> source) |
int | Treats the source data as integer and converts into a integer. |
db_row | This is needed if you fetch more than a single value as source and fetch the data from a condition. It takes the data and creates a one dimensional array from it. |
entry_count | The data is used as they come in. This is the default, so you don't have to set “source_type” if you want to use this type. |
Configuration, how the data is fetched from a source. This depends on the type of source (Key “source” in MA). This table is an overview of the keys that can be used in this configuration:
Key | Datatype | Description | usable for source |
|---|---|---|---|
table | string (SQL) | The table where the data is fetched from. If this is not set, the data will be fetched directly from the current dataset. This is also the case if the configured table is the same as the table, DynaFlex is working on. | db, field |
select | string (SQL) | The select statement. Which fields should be fetched from the table. | db |
where | string (SQL) | The condition for selecting the datasets. | db |
db_field | string | The field inside the db if you want to use a field outside of flexforms. | field |
path | path (string) | The path to the field inside of the flexform structure. Without fieldname! | field |
xml_field | string | The name of the field inside the flexform structure. Only needed if path is set | field |
The field_config describes what kind of field should be created.
In the keys “name” and “label” some replacements will be performed
Key | Datatype | Description |
|---|---|---|
path | path (string) | The path inside the FlexForm where the new field should be placed in. If no sheets are defined, the normal path would be “ROOT/el”. |
name | string | The name of the field. This has to be unique on the FlexForm. If you have a source defined you can use some markers in the name string that will be replaced before the form is rendered. There two static markers ###FINDEX### which is replaced with the index of the fieldconfig starting with 0. If you have defined more than one field in the field_config (add => fields) the ###FINDEX### is the same for each field. The other static marker is the ###DATA### marker. This thing is replaced if you have a field as source. E.g. If you create a number of fields depending on a value of a field, the ###DATA### marker is replaced with that value. If the source data is a dataset from the database. ###DATA### will also be replaced with the same value as ###FINDEX### The two static markers are implemented since version 1.2.0!!! Additionally to this this two static markers you can set each field of the source data as marker. For example if you have tt_address datasets as source, you can use markers like ###uid###, ###name###, ###city### and so on. Please keep in mind, that you should use any other fields than the uid as identifier for your fields. |
label | ->getLabel | The label of the field. This can be a simple string, or a reference to locallang element. It's the same as the field label in the TCA. For information which markers can be used here, see above in the description for “name”. |
config | -> TCA[“config”] | The configuration of the field. It's the same as in TCA and described in the Core APIs! |
singleUserFunc | string | Calls a user function for every dataset that is provided by the source. As arguments, dynaflex passes two arrays:
The user function has to return a field_config with “path”, “name”, “label” and “config”! |
Key | Datatype | Description |
|---|---|---|
name | string | The name of the sheet that will be created. The index of the sheet (beginning with 0) is added to the name. Example: iIf the name is “sheet” the name of the sheet in the resulting flexform will be “sheet_X” where X is the index of the sheet. |
label | string | The label of the sheet. You can use the marker ###SINDEX### which is replaced with the index of the sheet starting with 0. The markers are replaced before the value is passed to TYPO3. So if you have a reference to a language file, look for correct indexes in that locallang file. |
fields | Array of -> field_config | An array of fields that will be created on that sheet. See “field_config” for the config of the fields. |
modifications | Array of MA | For each sheet you can tell DynaFlex to process a subset of modifications. |
If you create fields you have to set a label for them. In most cases it should be enough to reference a locallang value but in some cases you might need more.
A label definition can be a simple string or an array. Before the label is inserted into the TCA it's allways parsed for some markers (see -> markers). For example to make labels independet from each other through appending the uid or whatever.
There are two special markers that are always available!
###ce_uid### - Is replaced with the UID of the current content element
###ce_pid### - Is replaced with the UID of the page the content element is placed on
The most simple type of label is a string. You can add static text or a reference to a locallang value as I said before. The second possibility is to fetch the label from the database. To do so, you have to define the label as an array. Inside of the array you have to define some things that dynaflex knows where to fetch the label from.
Key | Datatype | Description |
|---|---|---|
table | string | The table where the label should be fetched from. |
field | string | The field that contains the value for the label. |
where | string | the where clause for fetching the data. Here you can add some markers that will replaced before executing the query. |
It's importand to recognize, that the query will allways be limited to one! This is hardcoded in dynaflex because it makes no sense to get more than one row from the database. ;-)
