Form Handler Plugins

[ Form Reform ]

Form Handler Plugins

Form Reform can use a range of handler plugins to configure form processing.

Functionality can be extended by adding plugin classes for additional Form Handlers. Form Handler plugins are simple classes that provide the functionality to perform a single form handling action. They should inherit from FormHandlersPluginBase. Details are provided by comments in the code.

Plugins can be added by placing the plugin classes at packages/anyPackageName/src/FormReform/FormHandlers/Plugins/PluginName or application/src/FormReform/FormHandlers/Plugins/PluginName. Plugins can also be similarly placed beneath the plugin type's namespace declared in a package controller's AutoloaderRegistries.

[ Form Reform ]

Address Geocode

Lookup the Latitude/Longitude for an address string.

Geocoding begins by assembling an address string using {{place_holders}} from form data and other sources. The address string is then sent to the Google Geocode API and the returned data made available to following handlers as {{geocode:key}} data values such as {{geocode:latitude}} and {{geocode:longitude}}.

Geocoding is only as accurate as the address string provided. A partial address string or ambiguous address string may result in multiple places being returned or none being returned. Reliable results are indicated by a {{geocode:place_count}} of 1.

When the address string is incomplete or the Google geocode API cannot return data, an error will be returned. If this is important to form processing, geocoding should be followed by On Success / On Error handlers.

Keys provided for geocoded data. Accuracy and provision depends on data from Google.

  • all - serialized json for all data.
  • all_formatted - serialized json for all data, with line breaks.
  • latitude - latitude.
  • longitude - longitude.
  • lookup_address - address submitted to google.
  • place_id - place ID code.
  • place_count - a count of the results returned, ideally this should be 1.
  • street_number - Street Number
  • route - Route / Road
  • address1 - Address 1
  • address2 - Address 2
  • town - Town / City
  • sc - State code
  • state - State
  • postal_code - Postal code / Zip
  • postal_code_prefix - Postal code prefix
  • postal_code_suffix - Postal code suffix
  • cc - Country code
  • country - Country
  • formatted - Formatted Addr
A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Clear Data Category

Clear a {{place_holder}} category that has been added dynamically.

Form handlers and other extensions may declare and populate {{place_holder}} categories in order to make data available to Form Reform form handlers and blocks.

A specified category will be cleared from this handler onwards. If the category does not exist or has not been populated, this handler has no effect.

Only dynamically added categories can be cleared. Built in categories such as "form", "user" and "date" cannot be cleared.

[ Form Reform ]

Clear Errors

Clear all errors so far.

Empties the list of accumulated errors

[ Form Reform ]

Clear Quarantine Files

Files held in quarantine are cleared without import to the File Manager.

Form inputs that utilize Snapshot tools initially place files in a quarantine folder. This handler clears all files associated with a form or files associated with a specified input from quarantine.

  • Clear quarantined files for all Snapshot form inputs
  • Clear quarantined files for a specific form input

[ Form Reform ]

Comment

Insert a comment.

Make a comment or note within the pipeline. This handler has no effect on pipeline processing.

[ Form Reform ]

Condition Else

Denotes alternative condition processing.

The handlers ConditionIf, ConditionElseIf, ConditionElse and ConditionEnd manage a single level of conditional processing in form handling.

The general process should be :

  • ConditionIf
  • ConditionElseIf [optional, repeatable]
  • ConditionElse [optional]
  • ConditionEnd
If you are wondering about the actual names used, it is to ensure class names within the handlers do not conflict with php reserved words.

[ Form Reform ]

Condition Else If

Denotes conditional alternative condition processing.

The handlers ConditionIf, ConditionElseIf, ConditionElse and ConditionEnd manage a single level of conditional processing in form handling.

The general process should be :

  • ConditionIf
  • ConditionElseIf [optional, repeatable]
  • ConditionElse [optional]
  • ConditionEnd
If you are wondering about the actual names used, it is to make sure class names within the handlers do not conflict with php reserved words.

Item A is compared with Item B and may contain {{place_holders}}.

Comparison operations available are:
  • Comparisons
    • < LT
    • <= LE
    • = EQ
    • != NE
    • >= GE
    • > GT
  • Numeric length
    • < LT # characters
    • <= LE # characters
    • = EQ # characters
    • != NE # characters
    • >= GE # characters
    • > GT # characters
  • Length comparisons
    • < LT string lengths
    • <= LE string lengths
    • = EQ string lengths
    • != NE string lengths
    • >= GE string lengths
    • > GT string lengths
  • Patterns
    • Text contains
    • Match, with *? wildcards
  • Special
    • Is empty
    • Is not empty
  • Fixed
    • True always
    • False always
Within each, the comparison can be:
  • Case sensitive
  • Case invariant
  • Numeric
Where multiple comparisons are made, they can be combined logically by AND or OR.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Condition End

Denotes end of condition processing.

The handlers ConditionIf, ConditionElseIf, ConditionElse and ConditionEnd manage a single level of conditional processing in form handling.

The general process should be :

  • ConditionIf
  • ConditionElseIf [optional, repeatable]
  • ConditionElse [optional]
  • ConditionEnd
If you are wondering about the actual names used, it is to make sure class names within the handlers do not conflict with php reserved words.

[ Form Reform ]

Condition If

Check a condition and either proceed or move forwards to an alternative.

The handlers ConditionIf, ConditionElseIf, ConditionElse and ConditionEnd manage a single level of conditional processing in form handling.

The general process should be :

  • ConditionIf
  • ConditionElseIf [optional, repeatable]
  • ConditionElse [optional]
  • ConditionEnd
If you are wondering about the actual names used, it is to make sure class names within the handlers do not conflict with php reserved words.

Item A is compared with Item B and may contain {{place_holders}}.

Comparison operations available are:
  • Comparisons
    • < LT
    • <= LE
    • = EQ
    • != NE
    • >= GE
    • > GT
  • Numeric length
    • < LT # characters
    • <= LE # characters
    • = EQ # characters
    • != NE # characters
    • >= GE # characters
    • > GT # characters
  • Length comparisons
    • < LT string lengths
    • <= LE string lengths
    • = EQ string lengths
    • != NE string lengths
    • >= GE string lengths
    • > GT string lengths
  • Patterns
    • Text contains
    • Match, with *? wildcards
  • Special
    • Is empty
    • Is not empty
  • Fixed
    • True always
    • False always
Within each, the comparison can be:
  • Case sensitive
  • Case invariant
  • Numeric
Where multiple comparisons are made, they can be combined logically by AND or OR.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

End

Ends processing of the pipeline.

Ends processing at this step. No further handler pipeline steps will be executed. Any pending actions from handlers such as showing messages or redirecting pages will be completed.

[ Form Reform ]

Extend Form Data

Extend or modify the submitted form data with additional names/values.

Form handlers interfacing to external systems may also record response data from those systems as additional data for the form response.

Attach one or more parameters as name => value pairs as additional data to the form response or any other placeholder category. Names and values may both use {{place_holders}} to be filled with system or entered form values.

Only the form category will be saved with the form data. Other categories are for subsequent use in the current pipeline.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Extend From List

Build a list from form data, text and other values. Then concatenate that list into a new item of data.

Each item in the list may contain {{place_holders}}. These are filtered to remove empty values and concatenated about a configurable snippet to provide a new item of data.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Extend From Table

Extend or modify the submitted form data by matching a lookup table.

Attach or replace a parameter name => value as additional data to the form response or any other placeholder category. The new value is determined by the first match found in the lookup table. The Match Source, When Matched value and Return Value may all use {{place_holders}} to be filled with system or entered form values.

Where simple logic is required to map an existing value into a new value, a lookup table can be considerably more efficient and easier to work with than an if/elseif/else chain of handlers.

This handler provides two levels of conditional processing. The first level determines if this handler evaluates any further. The second level attempts to match the Match Source against a list of When Matched values and returns the Return Value for the first successful match.

Only the form category will be saved with the form data. Other categories are for subsequent use in the current pipeline.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Extend With Text Item

Build a text or rich text item to extend form data.

Build boilerplate for a text item, fill the boilerplate with form and site parameters and populate the form response or any other placeholder category with that text. Names and text may both use {{place_holders}} to be filled with system or entered form values.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Fail

Immediately fails silently.

Sometimes rather than ending with a helpful validation error message or completing the form handling pipeline, you may just want a form submission to disappear into a black hole with no response whatsoever. For example, when spam is detected (The Spam Detect handler has options to fail silently built in, so does not require this.)

[ Form Reform ]

Fire Event

Dispatches a ConcreteCMS event.

The event on_form_reform_event is dispatched with optional parameters submission_data and errors. Event listeners may read and/or modify these parameters.

The event name defaults to event and is dispatched as on_form_reform_event. The special event name test is handled by the package to (where configured) add some test data to the form submission and inject a test error message.

[ Form Reform ]

Import Quarantine Files

Files held in quarantine are released and imported to the File Manager.

Form inputs that utilize Snapshot tools initially place files in a quarantine folder. This handler releases all files associated with a form or files associated with a specified input from quarantine and makes the files available as {{place_holders}} to subsequent form handlers.

  • Release quarantined files for all Snapshot form inputs
  • Release quarantined files for a specific form input

In a multi step form, files can be kept in quaratine across multiple steps until released.

  • Release quarantined files only for the current form step
  • Release quarantined files for any form step

When files are released from quarantine, the associated input_name is updated with the imported file and further {{place_holders}} are populated.

The webcam category provides further categories with further information about an imported file.
  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

[ Form Reform ]

Iterate Data

Iterate over a multi-value item of data.

The handlers IterateData and IterateDataEnd manage iteration over each item in multi-value item of data.

The general process should be:

  • IterateData
  • » One or more handlers acting on the {{iteration:value}} within the iterated data
  • IterateDataEnd
The iteration category also provides metadata about the iteration:
  • value - the value of the individual item within the multi-value item of data.
  • index - the current index into the multi-value item of data.
  • iteration - the current iteration within the multi-value item of data.
  • size - the total number of items to iterate in the multi-value item of data.
Further multi-value data items can be associated and will then will be indexed to align with the item iterated over. Within an iteration, the Iteration key will make the associated item value available as {{iteration:key}}

IterateData / IterateDataEnd handlers cannot be nested and must not be interleaved with other Iteration or Condition handlers.

[ Form Reform ]

Iterate Data End

Denotes end of iteration over a multi-value item of data.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group.

The general process should be:

  • IterateData
  • » One or more handlers acting on the {{iteration:value}} within the in the iterated data
  • IterateDataEnd

[ Form Reform ]

Iterate Repeatable Group

Iterate over items in a repeatable group.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group.

The general process should be :

  • IterateRepeatableGroup
  • » One or more handlers acting on the {{group_item:key}} in the group
  • IterateRepeatableGroupEnd
Between repeatable group handlers we have some locally scoped {{place_holder}} categories specific to that iteration.
A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}


The group category provides metadata about the repeatable group and iteration through it:
  • name - the Group Name the current repeatable item is within.
  • index - the current index into the items in the repeatable group.
  • iteration - the current iteration of the repeatable group.
  • size - the total number of repetitions of the group .

[ Form Reform ]

Iterate Repeatable Group End

Denotes end of iteration over a repeatable group.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group.

The general process should be :

  • IterateRepeatableGroup
  • » One or more handlers acting on the {{group_item:key}} in the group
  • IterateRepeatableGroupEnd

[ Form Reform ]

Log Errors

Log errors so far.

Logs the current list of errors. If no errors, behaviour is configurable to do nothing or to log a 'No Errors' message.

[ Form Reform ]

Log Handler Results

Log the currently recorded handler results.

Logs the current pipeline handler results to the Form Reform channel. Use this as a diagnostic when you don't want the full logging options.

[ Form Reform ]

Log Pipeline

Log the current pipeline.

Logs the configured form Handler Pipeline to the Form Reform channel. Use this as a diagnostic when you don't want the full logging options.

[ Form Reform ]

Log Submission

Log all submitted data.

Logs all submitted data to the Form Reform log channel. Raw data is logged prior to any data extraction.

[ Form Reform ]

Log Submission Data

Log data extracted from form fields.

Log only the data extracted by the form field blocks through their extractSubmissionData() methods.

[ Form Reform ]

Magic Tabs Jump

Navigate tabs in Magic Tabs.

Primarily used with AJAX submissions when the form is within Magic Tabs. This is similar to the action of a Magic Tabs Jump block. The tab navigation is made on return from the AJAX submission. Outside of an AJAX submission, this handler has no effect.

GoTo a tab requires a target. For other actions you can usually leave the target blank. To identify a specific tab you can provide any of:

  • An #id for the tab.
  • The label of the tab.

[ Form Reform ]

Merge From Cookie Store

Merge form previously saved to cookie with form data.

Data extracted from form fields is merged with form data previously saved to visitor/user cookie data. Existing data from the cookie or submitted data can take priority.

  • Submitted form data takes priority
  • Previously saved data takes priority
Find an existing response by matching one or more criteria of the response.
  • Find previous for the form name and current page
  • Find previous for the form name and any page.
A form could have been saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

Merge cookie data to build a multi stage form through cookie data before the final stage saves to a more permanent store.

[ Form Reform ]

Merge From Default Store

Merge form previously saved to default store store with form data.

Data extracted from form fields is merged with form data previously saved to the default data store. Existing data from the default or submitted data can take priority.

  • Submitted form data takes priority
  • Previously saved data takes priority
Find an existing response by matching one or more criteria of the response. Items marked * cannot be used alone. They can only be used in association with un-marked criteria.
  • Match user session
  • Match CMS user ID (for logged in user)
  • Match user IP address (*)
  • Only submissions from the current page (*)
A form could have been saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

[ Form Reform ]

Merge From Session Store

Merge form previously saved to session with form data.

Data extracted from form fields is merged with form data previously saved to visitor/user session data. Existing data from the session or submitted data can take priority.

  • Submitted form data takes priority
  • Previously saved data takes priority
Find an existing response by matching one or more criteria of the response.
  • Find previous for the form name and current page
  • Find previous for the form name and any page.
A form could have been saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

Merge session data to build a multi stage form through session data before the final stage saves to a more permanent store.

[ Form Reform ]

Message

Create a form response message to be displayed to the user.

Build boilerplate for a response message, fill the boilerplate with form and site parameters and select a level to emphasize the message display. All text fields can use {{place_holders}} to be filled with system or entered form values.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Next Form State

Designate the next form state.

A form control can be hidden, disabled or not rendered for various form states, for example, when a success message is shown or during one or more parts of a multi-step form. All forms begin in Step 1. The next state(s) can also be set automatically by a Message. States are accumulated through the executed handler pipeline steps.

[ Form Reform ]

None

A null handler.

Do absolutely nothing.

[ Form Reform ]

On Error

Denotes error processing.

On Error and On Success should always be used in together to denote processing for errors and processing for no errors. Either may be used first.

The general process should be one of:

  • Validation
  • On Error
  • [one or more error handling steps]
  • On Success
  • [steps for success]
Or alternatively, handle success first:
  • Validation
  • On Success
  • [steps for success]
  • On Error
  • [one or more error handling steps]
In either case, if the first handler executes, processing will continue to the other handler and processing will then end. If the first handler does not execute, processing up to the other handler will be skipped and the other handler will continue processing.

Handlers can be used repeatedly. For example:
  • Validation
  • On Success
  • [steps for success]
  • On Success
  • [more steps for success]
  • On Success
  • [yet more steps for success]
  • On Error
  • [one or more error handling steps]
Each On Success would continue processing if there are no errors at that point, but jump forward directly to the single On Error if an error is reported at any stage. A similar pattern can be used the other way round.

[ Form Reform ]

On Success

Denotes success processing (no errors).

On Error and On Success should always be used in together to denote processing for errors and processing for no errors. Either may be used first.

The general process should be one of:

  • Validation
  • On Error
  • [one or more error handling steps]
  • On Success
  • [steps for success]
Or alternatively, handle success first:
  • Validation
  • On Success
  • [steps for success]
  • On Error
  • [one or more error handling steps]
In either case, if the first handler executes, processing will continue to the other handler and processing will then end. If the first handler does not execute, processing up to the other handler will be skipped and the other handler will continue processing.

Handlers can be used repeatedly. For example:
  • Validation
  • On Success
  • [steps for success]
  • On Success
  • [more steps for success]
  • On Success
  • [yet more steps for success]
  • On Error
  • [one or more error handling steps]
Each On Success would continue processing if there are no errors at that point, but jump forward directly to the single On Error if an error is reported at any stage. A similar pattern can be used the other way round.

[ Form Reform ]

Redirect

Redirect to a page or URL.

When the pipeline completes or is ended, the browser will be redirected to the configured page or URL. An optional condition may be configured to control redirection.

Redirect options are:

  • To site page
  • To the current page
  • To URL
  • To site page by ID from form input
  • To site page by path from form input
  • To URL from form input
  • To URL built from text with {{place_holders}}
  • None - equivalent of not adding this handler
A redirect may optionally have query parameters attached and these may be specified using plain text and {{place_holders}}. Names and values may both use {{place_holders}} to be filled with system or entered form values.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.


Do not rely on the Cookie Store when using Redirect.

[ Form Reform ]

Save to CSV

Save form submission to a CSV file.

Pick a Folder from the file manager and Form Reform will create and update a new CSV file for form results in that folder. The file will be named after the form name or an alias.

A form can be saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

The file will be named after the form name or alias followed by configurable text and {{PlaceHolders}}. {{PlaceHolders}} should be used with caution to avoid accidentally creating a profusion of files.

The CSV column headings are set when the file is created by the first form submission. If you subsequently change the form input fields, the CSV columns could become skewed. In such cases you should either change the form name / alias and begin a new CSV or manually edit the existing CSV to match the new form. Similar care must be taken if adding data to a previously uploaded CSV.

Form items may optionally be redacted from the data that is saved. For example, to remove a password from the saved data. Redacted items are listed by input_name.

[ Form Reform ]

Save to Cookie

Save form submission to browser cookie.

Data extracted from form fields is saved as a browser cookie. The primary reason for saving to a cookie is to enable values to be recovered and inserted into the same or other forms. Cookie data is available in the user's browser, so should not be relied upon for any critical data as it can easily be viewed and even hacked.

A form can be saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

A form submission may optionally update an existing response by matching one or more criteria of the response.

  • Always record a new entry
  • Update previous for the form name and current page
  • Update previous for the form name.
When updating, existing form data can either be replaced or extended. Extending data can be useful for multi-part forms.
  • Replace a previous submission
  • Extend a previous submission
  • Fill in gaps in this submission from previous
Duration of the cookie store is configurable through application/config. The current duration is 365 days. When a user is completing multiple forms, to keep the cookie data from growing, old submissions may be cleared from the cookie.

  • None, old submissions last as long as the cookie
  • Remove old for the form name and current page
  • Remove old for the form name.
Form items may optionally be redacted from the data that is saved. For example, to remove a password from the saved data. Redacted items are listed by input_name.

Do not rely on Save to Cookie when the form processing redirects to another page.

[ Form Reform ]

Save to Default

Save form submission to the default table.

Saves data extracted from form fields to the default table FormReformDefault. Form data is serialised as JSON.

A form can be saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

A form submission may optionally update an existing response by matching one or more criteria of the response. Items marked * cannot be used alone. They can only be used in association with un-marked criteria.

  • Match user session
  • Match CMS user ID (for logged in user)
  • Match user IP address (*)
  • Only submissions from the current page (*)
When updating, existing form data can either be replaced or extended. Extending data can be useful for multi-part forms.
  • Replace a previous submission
  • Extend a previous submission
  • Fill in gaps in this submission from previous
Form items may optionally be redacted from the data that is saved. For example, to remove a password from the saved data. Redacted items are listed by input_name.

[ Form Reform ]

Save to File

Save each form submission to an individual file.

Pick a Folder from the file manager and Form Reform will create a new file for each saved form submission in that folder.

A form can be saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

The file will be named after the form name or alias followed by configurable text and {{PlaceHolders}}.

File format is also selectable. You may need to add specific extensions in Allowed File Types for some formats.

Form items may optionally be redacted from the data that is saved. For example, to remove a password from the saved data. Redacted items are listed by input_name.

[ Form Reform ]

Save to Session

Save form submission to session data.

Data extracted from form fields is saved to the visitor/user session data. This is transient data that lasts for the duration of the Concrete CMS session. The primary reason for saving to a session is to enable values to be recovered and inserted into the same or other forms.

A form can be saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

A form submission may optionally update an existing response by matching one or more criteria of the response.

  • Always record a new entry
  • Update previous for the form name and current page
  • Update previous for the form name.
When updating, existing form data can either be replaced or extended. Extending data can be useful for multi-part forms.
  • Replace a previous submission
  • Extend a previous submission
  • Fill in gaps in this submission from previous
When a user is completing multiple forms, to keep the data from growing, old submissions may be cleared.

  • None, old submissions last as long as the session
  • Remove old for the form name and current page
  • Remove old for the form name.
Form items may optionally be redacted from the data that is saved. For example, to remove a password from the saved data. Redacted items are listed by input_name.

[ Form Reform ]

Send Email

Send an email.

Build boilerplate for an email, fill the boilerplate with form and site parameters. Send it to a configurable location. All text fields can use {{place_holders}} to be filled with system or entered form values. An optional condition may be configured to control sending email.

An email address can be entered as an actual name@address.com, as a user ID, as a {{place_holder}} or any combination.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Set Error

Set an error, for example to force an On Error.

Set a plain text error and/or a rich text error. Text may use {{place_holders}} to fill data.

Forcing an error can be useful to facilitate testing the form handler pipeline. Setting an error can also be used within a ConditionIf ... ConditionEnd set of handlers where the condition tests for an an error condition as a consequence of multiple input values.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Set Error Conditional

Sets an error depending on the result of condition evaluation.

Provides a single handler solution to setting an error based on a set of condition rules. An error can be set if the condition is met or if the condition is not met.

Item A is compared with Item B and may contain {{place_holders}}. Comparison operations available are:

  • Comparisons
    • < LT
    • <= LE
    • = EQ
    • != NE
    • >= GE
    • > GT
  • Numeric length
    • < LT # characters
    • <= LE # characters
    • = EQ # characters
    • != NE # characters
    • >= GE # characters
    • > GT # characters
  • Length comparisons
    • < LT string lengths
    • <= LE string lengths
    • = EQ string lengths
    • != NE string lengths
    • >= GE string lengths
    • > GT string lengths
  • Patterns
    • Text contains
    • Match, with *? wildcards
  • Special
    • Is empty
    • Is not empty
  • Fixed
    • True always
    • False always
Within each, the comparison can be:
  • Case sensitive
  • Case invariant
  • Numeric
Where multiple comparisons are made, they can be combined logically by AND or OR.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Sort Form Data

Sort the submitted form data into a configured sequence.

Sometimes it is useful to save form data in a specified sequence. For example, so a CSV can be easily viewed as a spreadsheet.

List one or more form inputs in the required sequence and form data will be sorted into that sequence overall and within any input groups.

Form inputs not listed will be sorted last.

[ Form Reform ]

Spam Detect

Configure multiple spam detection strategies.

Each spam detection strategy can be separately enabled to either fail silently or to provide an error message that can then be managed through the On Error handlder.

  • Do not check.
  • Check and fail silently. The form submission will not be acknowledged.
  • Check and set a general error message, to be handled in the same way as any other validation error.
Checks configurable are:
  • Check for spam using the core Anti-Spam service.
  • Check using the core Banned Words service. Use this with caution on multilingual sites. A banned word in one language could be perfectly acceptable in another language.
  • Check using the core IP Deny list. The IP Deny service maintains a dynamic blacklist and whitelist of IP addresses. If an IP address is not in the whitelist it is checked against the blacklist.
  • Check if the submission contains URLs. URL inputs are exempt from this check.
  • Check if the submission contains <html> tags. Rich Text inputs are exempt from this check.
  • Check if the submission contains <script> tags. This should normally be enabled.
  • Some blocks such as the Honeypot and Captcha also detect spam. Their detection response can be managed by the normal form validation error handling , or by direct integration with this Spam Detect handler.

[ Form Reform ]

Transform Error

When an existing error matches a condition, it can be replaced with an alternative message.

Some form handlers may generate error messages more suited to administrators or developers than site visitors. This Transform Error handler can be used to catch such errors and replace them with an alternate message.

Options allow transformed errors to be logged and for administrators to be exempted from the transform.

The condition to match errors may contain {{place_holders}}. Comparison operations available are:

  • Comparisons
    • < LT
    • <= LE
    • = EQ
    • != NE
    • >= GE
    • > GT
  • Numeric length
    • < LT # characters
    • <= LE # characters
    • = EQ # characters
    • != NE # characters
    • >= GE # characters
    • > GT # characters
  • Length comparisons
    • < LT string lengths
    • <= LE string lengths
    • = EQ string lengths
    • != NE string lengths
    • >= GE string lengths
    • > GT string lengths
  • Patterns
    • Text contains
    • Match, with *? wildcards
  • Special
    • Is empty
    • Is not empty
  • Fixed
    • True always
    • False always
Within each, the comparison can be:
  • Case sensitive
  • Case invariant
  • Numeric
Where multiple comparisons are made, they can be combined logically by AND or OR.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform ]

Validate Input Fields

Validate form input fields.

Validate the form input fields provided by each block in the form. Provides a list of errors as {{errors:list}} if validation fails.

Blocks in the form, including blocks in layouts, containers, stacks and global areas, are listed and the form fields in each block is validated using a validateSubmission() method provided by the block controller. When validation fails, this returns a list of errors.

Following validation, the next step should normally be an On Error handler to manage failed validation and later on an On Success handler for continued form processing.

[ Form Reform ]

Wait

Insert a time delay.

Inserts a time delay. Can be useful for testing interactions. Take care not to exceed php execution limits.

[ Form Reform Dynamics ]

Forward to Dynamics

Forward a form submission to Microsoft Dynamics.

Map data from Form Reform into names and values for Dynamics and forward that data to Dynamics using a POST request.

Outgoing data is prepared as name/value pairs. The values can contain {{place_holders}}. Values left empty will be filled from any form data that matches the name.

Returned data is made available as {{place_holders}} with the categories dynamics and dynamics_post. The dynamics category is accumulated by all Dynamics form handlers while dynamics_post will only contain data for this handler. Keys within these categories are the returned data item names. The special keys all and all_formatted provide the entire response. Examples: {{dynamics_post:XXX}}, {{dynamics_post:all}},

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform Dynamics ]

Get From Dynamics

Query Microsoft Dynamics to retrieve existing records.

Use an email address or other {{place_holders}} from Form Reform to query Dynamics for existing records and make the returned records available to Form Reform. See Query Data Samples for details of Dynamics query parameters.

Query parameters are prepared as name/value pairs. The values can contain {{place_holders}}. Values left empty will be filled from any form data that matches the name.

Returned data is made available as {{place_holders}} with the categories dynamics and dynamics_get. The dynamics category is accumulated by all Dynamics form handlers while dynamics_get will only contain data for this handler. Keys within these categories are the returned data item names. The special keys all and all_formatted provide the entire response. Examples: {{dynamics_get:XXX}}, {{dynamics_get:all}},

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform Dynamics ]

Update to Dynamics

Use a form submission to update an existing record in Microsoft Dynamics.

Given a dynamics record ID, map data from Form Reform into names and values for Dynamics and update that data in Dynamics using a PATCH request.

The record to be updated must first the identified with a record ID. Outgoing data is then prepared as name/value pairs. The values can contain {{place_holders}}. Values left empty will be filled from any form data that matches the name.

A Dynamics record ID will be 36 characters long in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX where X is a hexadecimal digit. This will typically be formed using a {{place_holder}} to insert an ID retrieved by a Get From Dynamics pipeline handler.

Returned data is made available as {{place_holders}} with the categories dynamics and dynamics_patch. The dynamics category is accumulated by all Dynamics form handlers while dynamics_patch will only contain data for this handler. Keys within these categories are the returned data item names. The special keys all and all_formatted provide the entire response. Examples: {{dynamics_patch:XXX}}, {{dynamics_patch:all}},

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Anti-Spammer Master for Form Reform ]

Anti-Spammer Master

Block Form Reform Spam with Anti-Spammer Master.

Anti-Spammer Master can be enabled to either fail silently or to provide an error message that can then be managed through the On Error handlder.

  • Do not check.
  • Check and fail silently. The form submission will not be acknowledged.
  • Check and set a general error message, to be handled in the same way as any other validation error.
Anti-spammer Master works with Form Reform Honeypot block. All other Form Reform spam detection options can also be left in place and won't interfere with Anti-spammer Master. Some will be redundant though.

[ Form Reform Attributes, Express and Users ]

Merge From User Textarea Attribute

Merge form previously saved to a textarea attribute of the current user.

Data extracted from form fields is merged with form data previously saved to a user textarea attribute. Existing data from the attribute or submitted data can take priority.

  • Submitted form data takes priority
  • Previously saved data takes priority
Find an existing response by matching one or more criteria of the response.
  • Find previous for the form name and current page
  • Find previous for the form name and any page.
A form could have been saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

Merge attribute data to build a multi stage form through attribute data before the final stage saves to a more permanent store.

[ Form Reform Attributes, Express and Users ]

Save to Current Page Textarea Attribute

Save form submission to a text area attribute of the current page.

Data extracted from form fields is saved to a textarea attribute of the current page. Form data is serialised as JSON.

A form can be saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

A form submission may optionally update an existing response by matching one or more criteria of the response. Items marked * cannot be used alone. They can only be used in association with un-marked criteria.

  • Match user session
  • Match CMS user ID (for logged in user)
  • Match user IP address (*)
When updating, existing form data can either be replaced or extended. Extending data can be useful for multi-part forms.
  • Replace a previous submission
  • Extend a previous submission
  • Fill in gaps in this submission from previous
The attribute could contain submissions from multiple users and multiple forms. To keep the data from growing too big, old submissions may be cleared. When clearing old submissions, an age cutoff can be set to ensure more recent submissions are not cleared.

  • None, old submissions last forever
  • Remove old for the form name and current user
  • Remove all submissions older than
Form items may optionally be redacted from the data that is saved. For example, to remove a password from the saved data. Redacted items are listed by input_name.

[ Form Reform Attributes, Express and Users ]

Save to Current User

Save form submission to attributes of the current user.

Saves data extracted from form fields to the user's attributes. Each user attribute is mapped from a {{data_value}}.

[ Form Reform Attributes, Express and Users ]

Save to Current User Textarea Attribute

Save form submission to a text area attribute of the current user.

Data extracted from form fields is saved to a textarea attribute of the current user. Form data is serialised as JSON.

A form can be saved to the name configured by the form blocks or to a different (alias) name. This can be convenient when you take advantage of the default name "form_reform" when adding a single form to a page, but would like a more specific name for the saved form data.

A form submission may optionally update an existing response by matching one or more criteria of the response.

  • Always record a new entry
  • Update previous for the form name and current page
  • Update previous for the form name.
When updating, existing form data can either be replaced or extended. Extending data can be useful for multi-part forms.
  • Replace a previous submission
  • Extend a previous submission
  • Fill in gaps in this submission from previous
When a user is completing multiple forms, to keep the data from growing, old submissions may be cleared.

  • None, old submissions last forever
  • Remove old for the form name and current page
  • Remove old for the form name.
Form items may optionally be redacted from the data that is saved. For example, to remove a password from the saved data. Redacted items are listed by input_name.

[ Form Reform Attributes, Express and Users ]

Save to Express

Save form submission to an Express object.

Saves data extracted from form fields to an Express object. Each attribute of an Express object is mapped from a {{data_value}}.

Take care if configuring to update an existing result to constrain the scope of what can be updated.

[ Form Reform Attributes, Express and Users ]

User Groups

Add and remove the current user from user groups.

Removal is handled before adding. The user submitting the form can be removed from and added to existing user groups. The Administrators group is excluded.

[ Form Reform Image Picker ]

Extend From File Properties

Extend or modify the submitted form data with additional names/values populated from file properties.

Forms selecting or uploading images and other files may extend form data with properties and attibutes of those images and files.

Extract properties of a file specified by Source and attach those properties as name => value pairs as additional data to the form response or any other placeholder category. Source, Category and Name/key fields may use {{place_holders}} to be filled with system or entered form values.

Only the form category will be saved with the form data. Other categories are for subsequent use in the current pipeline.

A {{place_holder}} follows the format {{category:key|default}} and is identified by being wrapped in double moustaches {{...}}. Only the key is required. The other parts are optional.
  • category - optional prefix such as form, user, page, visitor, errors which identifies where to find the key. If not specified, the default category is form.
  • key - identifies what to fill, such as a form input_name, a user or page property or attribute.
  • default - an optional default value should the key not be filled. If not specified, an un-filled key will remain.

Form

The form category is data extracted from the form input elements. When a category is not specified, this category is defaulted. Keys are the input names:

  • all - serialized json for all form inputs.
  • all_formatted - serialized json for all form inputs, with line breaks.
  • key - any key matching a form input name returns the value of that input.
  • keypart.keypart - key to index into an array of inputs.

Repeatable Groups

We have multiple ways to work with form data from repeatable groups:

  • {{form:groupname.index.key}} - using dot notation to a index a specific repetition of a repeatable group and the input key from that repetition of the group.
  • {{all_group:groupname.key}} - a category that aggregates all inputs for key across the repeatable group.
  • {{group_item:key}} - a category that provides the key for the current iteration within a group, for use within an Iterate Repeatable Group form handler.
  • {{group:key}} - a category that provides metadata within an Iterate Repeatable Group form handler.
The all_group category is a special way of accessing the form category for repeatable groups of form inputs. Rather than indexing individual group repetitions using {{form:groupname.index.key}} the shorthand {{all_group:groupname.key}} will be filled with a list of all items for the key in the repeatable group.

To work with multiple inputs/keys in the same group, {{all_group:groupname.key1 key2 key3}} will be filled with each individual key.

The handlers IterateRepeatableGroup and IterateRepeatableGroupEnd manage iteration over each item in a repeatable group. The group_item category is data extracted from the form input elements specific to the current iteration within a repeatable group. Keys are the input names:
  • all - serialized json for all form inputs within a group item/iteration.
  • all_formatted - serialized json for all form inputs within a group item/iteration, with line breaks.
  • key - any key matching a form input name within the group item/iteration returns the value of that input.
  • keypart.keypart - key to index into an array of inputs within a group item/iteration.
Within an iteration through a group, transient categories provided by for input blocks such as the Image Picker or Snapshot where inputs for only that iteration are mapped to {{group_[category]:input_name}}

Query

The query category is actual query string data. This may not be the same as the form category, but can also be used when {{place_holders}} are not in a form pileline. Keys are the query key names:

  • all - serialized json for all query keys.
  • all_formatted - serialized json for all form query keys, with line breaks.
  • key - any key matching query key returns the value of that key.
  • keypart.keypart - key to index into an array value parameter

Page

The page category provides information about the submitting page:

  • name - submitting page name.
  • description - submitting page description.
  • url - submitting page url.
  • id - submitting page/collection id.
  • attribute_handle - submitting page attribute value.

Visitor

The visitor category provides information about the visitor and browser:

  • ip - IP address string.
  • country - Country code.
  • continent - Continent code.
  • state - State/Province code (accuracy can vary greatly by country and may not be available for all countries).
  • city - City (accuracy can vary greatly by country and may not be available for all countries).
  • locale - Browser locale.
  • locales - Possible browser locales in decreasing priority.
  • browser - Browser user agent string.

User

The user category provides information about the current user:

  • email - current user email.
  • name - current user name.
  • url - current user profile url.
  • id - current user id.
  • attribute_handle - current user attribute value.

Date Time

The date category, formatted using php DateTime:

  • timestamp - System timestamp, seconds since 1 January 1970.
  • date - Date formatted Y-m-d.
  • time - Time formatted H:i:s.
  • datetime - Date and Time formatted Y-m-d H:i:s.
  • loaded - Page load time as float seconds.microseconds
  • elapsed - Page load to submission elapsed time as float seconds.microseconds
  • format-string - DateTime formatted according to the format-string.

Pipeline

The pipeline category is a list of status data provided by many of the handlers. Keys are a snake_case handle derived from the Plugin Name. Values depend on plugins:

  • all - serialized json for all data available in the pipeline category.
  • all_formatted - serialized json for all data available in the pipeline category, with line breaks.
  • key - matching the handle for a pipeline element returns status data from that element.

Random

The random category generates random values and some related utilities:

  • 10 - any number provides a random string of that length.
  • d10 - d or D followed by any number provides a random number of that length.
  • g10 - g or G followed by a number assigns to one of that number of groups. This is based on ip address, so is constant.
  • ip - a random IP address from 0.0.0.0 to 255.255.255.255. Sometimes useful for testing an API.
  • special_characters - the currently configured string of password special characters ~!@#$%&*()-_+=;?: .

Empty

To distinguish between an unfilled {{place_holder}} and a deliberately empty value, the empty category provides explicitly empty values. All but null can also be provided using the {{category:key|default}} component of a {{place_holder}}:

  • empty or null - an actual null.
  • string - an empty string "".
  • false - a boolean false value.
  • number - an integer 0 value.

Error

The errors category provides error messages reported by form handlers:

  • first - first error.
  • last, error - last error.
  • list, errors - all errors as plain text, one per line.
  • formatted, all_formatted - all errors as formatted html.

Thumbnail, Picture

The thumbnail category prefix creates HTML <img> tags from image files identified by fID, UUID, or path. Use this category by prefixing another category with thumbnail_.

For example, if the form input my_input would normally provide an fID, UUID or File Manager path for an image files as {{form:my_input}}, then {{thumbnail_form:my_input}} will provide an <img> tag for that image file. A further refinement is to insert a size such as {{thumbnail_[size]_form:my_input}} to fit the image into a thumbnail size. The size can be any number by itself, or followed by w, h, or b to fit to width, height or box, or a pair of numbers as WidthxHeight to specify both width and height in pixels. The thumbnail category prefix can be used to preceded any category that returns and image fID, UUID or File Manager path, not just the form category.

If you have a large image and would prefer a picture element, the picture category prefix works in the same way to prefix another category and generate a <picture> element.

If a file is not an image file, the default Concrete CMS icon for the file type will be returned.

Quarantine (Snapshot: Files, Webcam and Screengrab)

The webcam category provides further categories with further information about an imported file.

  • webcam:key - The value provided with the form input, configurable in the input block dialogue.
  • webcam_fid:key - File Manager file ID.
  • webcam_url:key - URL to file, will be direct to filespace.
  • webcam_secure:key - Download URL to file, streamed and hence secure.
  • webcam_download:key - Forced download URL to file, streamed and hence secure.
  • webcam_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The screengrab category provides further categories with further information about an imported file.
  • screengrab:key - The value provided with the form input, configurable in the input block dialogue.
  • screengrab_fid:key - File Manager file ID.
  • screengrab_url:key - URL to file, will be direct to filespace.
  • screengrab_secure:key - Download URL to file, streamed and hence secure.
  • screengrab_download:key - Forced download URL to file, streamed and hence secure.
  • screengrab_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The drag_drop category provides further categories with further information about an imported file.
  • drag_drop:key - The value provided with the form input, configurable in the input block dialogue.
  • drag_drop_fid:key - File Manager file ID.
  • drag_drop_url:key - URL to file, will be direct to filespace.
  • drag_drop_secure:key - Download URL to file, streamed and hence secure.
  • drag_drop_download:key - Forced download URL to file, streamed and hence secure.
  • drag_drop_total:key - Count of files uploaded with the form input.
These categories initially refer to the quarantined file, with the temporary quarantine fID, url and such. Then after the Import Quarantine Files handler has run, these categories refer to the actual imported file.

The quarantine category provides direct access to files in quarantine. These files are transient and hence the quarantine category should only be used where all use is completed before the file is imported from quarantine and within the current handler pipeline.
  • quarantine:key - a form input field uploaded into quarantine returns a (temporary) File Manager file ID.

Image Picker

In the form handler pipeline, the form data placeholder {{form:my_input}} provides the File ID (fID) for the Image Picker input my_input.

This is supplemented by the image_picker category to provide further information about the picked images.

  • image_picker_fid:key - File Manager file ID.
  • image_picker_url:key - URL to file, will be direct to filespace.
  • image_picker_secure:key - Download URL to file, streamed and hence secure.
  • image_picker_download:key - Forced download URL to file, streamed and hence secure.
  • image_picker_total:key - Count of files selected with the form input.

Some examples:

  • {{form:my_input}} - the form category and form field my_input.
  • {{my_input}} - the form field my_input (defaults to the form category).
  • {{user:name}} - the user category and property name , filled with the name of the current user.
  • {{user:name|Guest}} - the user category and property name with a default of Guest.
  • {{random:G3}} - the visitor is assigned to one of 3 groups numbered 1..3 derived from their ip address.
  • {{page:tags}} - the page category and attribute tags.
  • {{thumbnail_200x100_form:my_input|}} - an <img> tag 200 pixels wide x 100 pixels high generated from the form input my_input which defaults to an empty string.
  • {{thumbnail_75h_image_picker_fid:my_input|10}} - an <img> tag 75 pixels high generated from the Image Picker form input my_input which defaults to file ID number 10.
  • {{webcam:my_input|}} - the webcam category as uploaded by the Webcam input my_input with a default value of an empty string.
  • {{screengrab_fid:my_input}} - the File ID (fID) for input my_input in the screengrab category as uploaded using the Screen Capture.
  • {{drag_drop_url:my_input}} - the URL for input my_input in the drag_drop category as uploaded using the Drag & Drop uploader.
  • {{webcam_download:my_input}} - the Force Download URL for input my_input in the webcam category as uploaded using the Webcam.
  • {{image_picker:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_fid:my_input}} - the File ID (fID) for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_url:my_input}} - the URL for selected image file(s) by the Image Picker input named my_input.
  • {{image_picker_download:my_input}} - the Force Download URL for selected file(s) by the Image Picker input named my_input.

[ Form Reform Developer ]

Dump Added Static Handler Categories

Debug resource. Dump out currently added static handler categories.

Form blocks and handlers can provide additional {{data values}} using addStaticCategoryHandler($category, $handler_class) where $handler_class extends DataValueCategoryBase. This handler dumps the currently added category handlers into a response message.

[ Form Reform Developer ]

Dump Form Data

Debug resource. Dump out the form data.

Form blocks and handlers traslate input data from the form submission into {{form:key}} which are then saved with the form. This handler dumps the available {{form:key}} values into a response message.

[ Form Reform Developer ]

Dump Post Data

Debug resource. Dump out the $_POST data.

Form blocks and handlers traslate $_POST data from the form submission into {{data_values}} which are then saved with the form. This handler dumps the $_POST values into a response message.

[ Form Reform Developer ]

Dump Query Data

Debug resource. Dump out the $_GET data.

Form blocks and handlers traslate $_GET data from the form query string into {{data_values}} which are then saved with the form. This handler dumps the $_GET values into a response message.

[ Form Reform Developer ]

Dump Static Data Values

Debug resource. Dump out what is currently in the static values array.

Form blocks and handlers can provide additional {{data values}} using DataValues::addStaticCategory($category, $key_values_list). This handler dumps the currently available values into a response message.

[ Form Reform Developer ]

Log Added Static Handler Categories

Debug resource. Dump currently added static handler categories to the log.

Form blocks and handlers can provide additional {{data values}} using addStaticCategoryHandler($category, $handler_class) where $handler_class extends DataValueCategoryBase. This handler dumps the currently added category handlers to the site log.

[ Form Reform Developer ]

Log Static Data Values

Debug resource. Dump current in the static values array to the log.

Form blocks and handlers can provide additional {{data values}} using DataValues::addStaticCategory($category, $key_values_list). This handler dumps the currently available values to the site log.

[ Form Reform Developer ]

Post Data Review

Debug resource. Review the raw POST data.

Reviews raw POST data and suggests possible issues.

[ Form Reform Developer ]

Validate Form Structure

Validate the structure of a form.

Validate the actual structure of a form. This may generate false positives about intended form structure, in which case the respective checks can be disabled.

Additional Pages

Reform the way you add new input controls

If you need a specialized template or a custom input element, you can design new templates  or new block types for form elements as you would any block type.

Blocks are easy for third party addition or extension. Block templates and are the first thing any Concrete CMS developer learns to code. They are one of the easiest things to code. The underlying mechanisms are well established and reliable.

Reform what you can do with form data

Form handlers are built about the same extensible plugin system as many of my other addons (Universal Content Puller, Omni Gallery, Extreme Clean ...).

The whole system is aimed at easy extension within Form Reform, by third party addons, by agencies and by site building developers.

Handlers can be easily added to do whatever you want with the form data.

Reform where you can save form data

Saving form data with Form Reform is simply a handler in the processing pipeline. You can save to multiple locations or just one location.

If you need to save data elsewhere, such as to a dedicated table, a table provided through another addon, to another database, send it to an API, forward it to another server, or anywhere you can imagine, you can adapt or develop a form handler to do so.

The complexity of the code depends on where you are saving or sending the data, but wrapping that into a form handler plugin for Form Reform is straight forward.

The Form Reform handler plugin system is designed for easy extension.

Form Reform

Reform the way forms are built. Build a form out of blocks. Take control of how form submissions are processed and how the submitted data is stored. Easy to extend. Easy to reconfigure. Tangible data. Easy to add your own integrations.

Form Reform Display

List and display form submissions from Form Reform.

Form Reform UTM

Not just Form Reform and not just UTM! Capture and hold incoming UTM (or other) tags and make the tag values available to Form Reform and/or Conditional Redirect as {{place_holders}}. You don't need Form Reform to use this.

Form Reform Dynamics

Form handlers for querying Microsoft Dynamics, forwarding and updating form data to Microsoft Dynamics.

Snapshot

A suite of advanced image capture and upload tools. Enhanced drag and drop file uploading. Make screengrabs from within Concrete CMS. Capture images directly from device webcams. Edit images before uploading.

Form Reform Attributes, Express and Users

Save submitted forms to Express objects and user attributes. Add and remove users from groups.

Form Reform Image Picker

Form Reform Image Picker provides an image picking input block for Form Reform. The Image Picker Input is preconfigured to connect to most Omni Gallery gallery and slider display widgets, the core gallery block, and thumbnail showing templates for the core page list block. Advanced settings allow the Image Picker Input to be configured to pick images from other galleries and sliders.

Form Reform Data Picker

Form Reform Data Picker provides data picking input blocks for Form Reform. The Table Picker Input is preconfigured to connect to Universal Content Puller table display widgets. Advanced settings allow the Table Picker Input to be configured to pick data from other HTML tables.

Form Reform Developer

A growing suite of resources to assist those developing blocks, handlers and more complex forms for Form Reform.

Learn with a simple form

While you may have plans to implement some much more complex forms using Form Reform, we strongly recommend you start with a simple form such as our contact form example in order to review the basic principles of using Form Reform before you move onto anything bigger.

  1. Start by submitting the form at Getting Started - Your First Form a few times, even making some deliberate mistakes.
  2. Watch our Getting Started with Form Reform video to see how the form is built.
  3. Read through the rest of Getting Started - Your First Form for more details of how this form is built.
  4. Create a test page on your site to build your own version of Getting Started - Your First Form and experiment.
  5. Develop your test page with some of the concepts introduced by our further examples and experiment with some of the other form inputs.