{{place_holders}}

Form Reform interprets {{place_holders}} in many situations including

These are a general purpose mechanism and different {{place_holders}} will make sense in different situations. You can also make use of {{place_holders}} to fill text in custom form handlers and extend the categories and keys provided by {{place_holders}}.

Index

Extending {{place_holders}}

The data made available to form handlers through {{place_holders}} can be extended by:

  • Using the Extend Form Data handler in a submit pipeline.
  • Using the Extend With Text Item handler in a submit pipeline.
  • Custom form handlers.
  • Extensions for Form Reform such as Form Reform UTM.
  • Integration with other packages such as Snapshot.
  • Third party extensions to Form Reform.

General help for {{place_holders}}

Many pipeline handlers can use {{place_holders}} to be filled with system or entered form values. See the help for individual pipeline handlers for details.

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.

Math

The math category enables/disables evaluation of mathematical expressions:
  • start - marks start of a mathematical expression.
  • end - marks start of a mathematical expression.
Use {{math:start}} ... enclosed expression is evaluated ... {{math:end}}. Any {{place_holders}} in the expression are evaluated before the expression is evaluated. Expressions may contain {{data_values}}, most mathematical operators and php numeric functions. Expressions are evaluated by an interpreting engine and do not use php eval() or other insecure functions.
Examples:
  • The area of a circle radius {{form:my_radius_number}} is {{math:start}} pi() * {{form:my_radius_number}} ^ 2 {{math:end}}
  • The hypotenuse for triangle {{A}},{{B}} is {{math:start}} sqrt({{A}} ^ 2 + {{B}} ^ 2){{math:end}}

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.
  • The area of a circle radius {{form:my_radius_number}} is {{math:start}} pi() * {{form:my_radius_number}} ^ 2 {{math:end}}
  • The hypotenuse for triangle {{A}},{{B}} is {{math:start}} sqrt({{A}} ^ 2 + {{B}} ^ 2){{math:end}}
  • {{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.

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 Macros

Extends Form Reform with form handler macros. Provides a new dashboard page at System & Settings > Form Reform > Form Reform Macros to manage macros, and form handlers to run macros.

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.