General Parameters

This is a user-contributed Extra. If you find issues or would like more info or help, please contact the author.

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

Settings

Property Description
controller

Sets the class to process data.

Possible values - php-file name without extension which contains controller class.

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

Possible values - post, get or request.

Default value - post.

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;
  • 1: json array with form data;
  • 2: json array with form data and html.
apiFormat

Output format.

Possible value - json or array.

Defaut value - json.

debug

Enables debug mode. Debug data is sent to Evo 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 Evo as it contains {{, [[ and so on. Evo tags will be sanitized in output.

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

Default value - 0.

Data sources

Property Description
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 prefix". Prefix is added to field name, if set - for example, config.site_name.

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 key:prefix - loads data from $_SESSION[array key];
  • plh:keys, comma separated:prefix - loads data from $modx->placeholders property;
  • aplh:placeholder name:prefix - loads data from an array stored in placeholder;
  • config:prefix- loads data from Evo configuration;
  • cookie:keys, comma separated:префикс - loads data from the $_COOKIE array;
  • MODxAPI class name 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 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

Property Description
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
}`

Data Processing

Property Description
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.

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

Default value - none.

Validation

Property Description
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.

Templates

Property Description
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 Evo templates.

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

Property Description
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.

Suggest an edit to this page.