Parameters

General parameters

These parameters are processed by FormLister core class. Controllers can change parameters purposes.

Settings

controller

Sets the class extending \FormLister\Core to process data.

Possible values - class name. If it has no namespace, then namespace is assumed to be \FormLister. So Form means \FormLister\Form. Default value - Form.

dir

Folder where controller class is located.

Default value - assets/snippets/FormLister/core/controller/

formid

The name of the form, required parameter.

Form needs to have a hidden field named "formid" and its value has to be the same as parameter value. The form means to be sent, if there is a key named "formid" in the $_REQUEST array and its value is equal to the parameter value.

formMethod

Determines the source of request data:

• post - $_POST array;
• get - $_GET array;
• request - $_REQUEST array;
• anonymous function or class method name - the result of its call.

Possible values - post, get, request, anonymous function or class method name.

Default value - post.

disableSubmit

Disables form submission, if the parameter value is set to 1.

Possible value - 1, 0.

Default value - 0.

config

Loads parameters from json file.

Possible values - filename:folder, several values are separated by the semicolon.

Example

myparams:core - loads parameters from assets/snippets/FormLister/config/core/myparams.json file; myparams - loads parameters from assets/snippets/FormLister/config/custom/myparams.json file; myparams:/assets/myfolder - loads parameters from assets/myfolder/myparams.json file.

Default value - none.

api

The way of output.

Possible values:

• 0: html only (default);
• 1: array with form data;
• 2: array with form data and html.
• 3: pure FormLister object;

apiFormat

Output format for mode 1 or mode 2.

Possible value - json or array.

Defaut value - json.

debug

Enables debug mode. Debug data is sent to MODX events log.

Possible values - 0, 1.

Default value - 0.

saveObject

Saves FormLister object to placeholder, so other snippets can use it. The object is saved only if form processing is finished successfully.

Possible values - placeholder name.

Default value - none.

removeGpc

Restores data sanitized by MODX as it contains {{, [[ and so on. MODX tags will be sanitized in output.

Default value - 0, 1 or field names comma separated.

Default value - 0.

Data sources

defaultsSources

Allows to load data from external sources, to pre-fill form fields, for example. External data are loaded only before initial form output and ignored after form is sent. This behaviour can be changed with "keepDefaults" parameter.

Possible values: sources, semicolon separated. The order of loading data matches the sources order in parameter.

The source can be set as "name:key:prefix". A prefix with a dot is added to field name, if set - for example, config.sitename. If a prefix is ended with an underscore (), then an underscore will be used instead of a dot - that allows to avoid dot to underscore conversion made by PHP (https://www.php.net/manual/en/language.variables.external.php).

Possible sources:

• array: json or php array, its values are defined by the parameter named "defaults";
• param:parameter name:prefix - the same as the "array" source but you can specify any snippet parameter, not only "defaults";
• session:array keys, comma separated:prefix - loads data from $_SESSION according to the given keys, the values can be arrays;
• plh:keys, comma separated:prefix - loads data from $modx->placeholders property according to the given keys, the values can be arrays;
• cookie:keys, comma separated:префикс - loads data from the $_COOKIE array according to the given keys, the values can be json-arrays;
• config:prefix- loads data from MODX configuration;
• MODxAPI class name:key:prefix - a key is the argument of edit() method, the class has to be loaded before snippet call;
• document:prefix - loads current document data from modResource model. It needs no key;
• user:key:prefix - load authorized user data from modUsers model. User type is provided by key value (web or mgr).

Default value - array.

defaults

Data for the "array" source.

Possible values: json or php array.

keepDefaults

Allows to load external data after the form is sent. If fields list is specified, then only these fields will be loaded.

Possible values: 1, 0; field names, comma separated.

Default value - 0.

allowEmptyFields

Allows to set fields with empty values.

Possible values - 0 or 1.

Default value - 1.

Form Controls

formControls

The list of fields hold by form controls (selects, checkboxes, radio buttons). It needs to determine their state.

Possible values - field names, comma separated.

Default value - none.

emptyFormControls

This parameter allows to solve the problem of unchecked checkboxes, as they are excluded from fields array during form submission: if there's no needed element in the $_REQUEST array, then it's set according to this parameter. The problem is actual mostly for MODxAPI classes usage, because MODxAPI requires to list changed fields in fromArray() method. But it's possible to use it in common forms to set the value of unchecked checkbox in templates.

Possible values - an array:

&emptyFormControls=`{
    "mycheckbox" : "No",
    "published" : 0
}`

fieldAliases

Allows to set field aliases. For exemplae, "foo" field has "bar" alias:

$FormLister->setField("foo", 10);
$FormLister->getField("bar"); //10
$FormLister->setField("bar", 20);
$FormLister->getField("foo"); //20
$FormLister->unsetField("foo");
$FormLister->getField("foo"); //Nothig
$FormLister->getField("bar"); //Nothing (but "bar" field stays untouched when function call is unsetField("foo", false)); 

Possible values - an array:

&fieldAliases=`{
    "field name":"alias",
    "field name":"alias"
}

Default value - none.

Data Processing

prepare, prepareProcess, prepareAfterProcess

It's similar to the "prepare" parameter of DocLister.

Snippets defined in the "prepare" parameter are run after form data loaded, "prepareProcess" - after validation is passed successfully, "prepareAfterProcess" - after form processing is finished. Controller object is available in prepare-snippets via $FormLister variable, while $data array contains the values of form fields. Additional $name variable allows to determine the parameter initiated snippet call; so you can use one snippet for all cases. Use controller methods (setField, setFields etc.) to change form data in prepare-snippets, or return data to change as an array.

Possible values - snippet names, anonymous functions, static methods of loaded classes.

Default value - none.

Filtering

filterer

Class name to filter data. Is has to be loaded before snippet call.

Default value - \FormLister\Filters.

filters

Filtering rules array.

Default value - none.

Validation

validator

Class name to validate data. Is has to be loaded before snippet call.

Default value - \FormLister\Validator.

rules

Validation rules array.

Default value - none.

fileValidator

Class name to validate files. This class has to be loaded before snippet call.

Default value - \FormLister\FileValidator

fileRules

Files validation rules array.

Default value - none.

Templates

formTpl

Form template. It needs to have the required field named "formid" with the same value as "formid" parameter's one.

Possible values - template name, according to DocLister templating rules.

Default value - none.

arraySplitter

The separator to convert arrays to strings.

Default value - semicolon.

{field}.arraySplitter

The separator to convert arrays to strings, but for particular {field}. Example: groups.arraySplitter - the separator for the field named "groups".

If not set, then the "arraySplitter" parameter is used.

errorTpl

Template for validation messages.

Possible values - template name, according to DocLister templating rules.

Default value:

@CODE:<div class="error">[+message+]</div>

requiredClass, errorClass

Class name for empty required fields and wrong filled fields.

Default value - required and error accordingly.

{field}.requiredClass, {field}.errorClass

Allows to set classes mentioned above for particular fields.

If not set, then "requiredClass", "errorClass" parameters are used.

messagesTpl

Template for controller messages. It outputs message groups (messages, required, error).

Possible values - template name, according to DocLister templating rules.

Default value:

@CODE:<div class="form-messages">[+messages+]</div>

messagesOuterTpl

Wrapper template for controller message groups.

Possible values - template name, according to DocLister templating rules.

Default value -

@CODE: [+messages+]

messagesRequiredOuterTpl

Wrapper template for the "required" message group.

Possible values - template name, according to DocLister templating rules.

Default value:

@CODE: [+messages+]

messagesErrorOuterTpl

Wrapper template for the "error" message group.

Possible values - template name, according to DocLister templating rules.

Default value:

@CODE: [+messages+]

messagesSplitter, messagesRequiredSplitter, messagesErrorSplitter

Messages separator in groups.

Possible values - string.

Default value:

<br>

removeEmptyPlaceholders

Removes placeholders without values from templates.

Possible values - 0 or 1.

Default value - 1.

parseDocumentSource

Enables MODX-parser for output post-processing.

Possible values - 0 or 1.

Default value - 0.

rewriteUrls

Allows to parse links in templates if the "parseDocumentSource" parameter is off.

Possible values - 0 or 1.

Default value - 0.

skipPrerender

Allows to skip some form fields processing (sanitizing values, converting arrays to strings, error messages rendering). Set to 1, if you do not use MODX templates.

Possible values - 0 or 1.

Default value - 0.

prerenderErrors

Allows to process form errors if "skipPrerender" parameter is on. The results are saved to placeholders.

Possible values - 0 or 1.

Default value - 0.

templatePath, templateExtension

Sets template files folder and template files extension. These parameters are needed to use with EvoTwig plugin.

Default value - none.

Redirect after finish

redirectTo

Target page id to redirect if form is processed successfully. There's no redirect in api-mode, but absolute url for target page is saved in form data as "redirectTo" field.

Instead of target page id, you can specify an array with additional options:

&redirectTo=`{
    "page":10,
    "query":{
        "foo":"bar"
    },
    "header":"HTTP/1.1 307 Temporary Redirect"
}`

The "page" key is the target page id, the "query" array contains get-parameters to pass, the "header" key can be used to set redirect header.

Possible values - number or array.

Default value - none.