Form behaviour in various form states is the mechanism by which form inputs are hidden after a successful form submission and for building multi-step forms.
Most Form Reform blocks have a Behaviour tab in the block edit dialogue with sections for Form State and Visibility Rules.
Form State (this page) provides a list of the states a form can be in and what the block does in those states. The actual list is derived from the alert classes available for messages and a numeric list of steps from 1..5 (the number of states is configurable).
Visibility Rules are applied in browser as form values change and are for use on a much smaller scale. A form control can be toggled between shown+enabled and hidden+disabled according to these rules. For example, show this form control when another control has a value of "Yes". See Visibility Rules.
This page is about Form State. For most form control block types, Form State can be found at the top of the Behaviour tab of the block edit dialogue.
With Hide when checked, the block will be rendered as normal, but will be hidden from display. This can be convenient for propagating already entered form values between form steps, but will leave the inputs in the page and hence vulnerable to hacking, so is best not used if you don't want an unscrupulous user to mess with the data.
With Do not render when checked, the form block's view is not rendered on the page in this state. The data is not on the page, so can't be hacked. But it is also not part of the form at this point, so you need to adopt an alternative mechanism such as Hide when or Save to session if the data needs to be passed forwards to a subsequent step.
The Hide when and Do not render when options are usually enough for multi-step forms. However, they run into limitations when used with a multi step AJAX form. In an AJAX form, all the controls need to be rendered, even if not used in a specific state. Hence we have Disable when. The input is rendered, but disabled so it can't be used and is not submitted from the checked form states. In the Validation handler of the submit processing pipeline, a disabled input is not validated.
| Hide | Disable | Do not render | When |
|---|---|---|---|
If you have experience of working with Concrete CMS edit dialogues and dashboard pages, you will likely have noticed that the data you entered is often persisted when a form is refreshed following submission or after an error is shown.
Form Reform takes this further. A form input can have an Initial Value that rather than just being sticky with the immediate page or dialogue request, can be persisted over a much wider scope.
This can be used to help maintain form data across states when an input is hidden, or to do the opposite and ensure a field is not maintained when you don't want it.
This is such a big thing we have a whole page about Initial Value.
When a form is saved, the save handler can be configured to extend a previous submission. Hence each part of a multi-step form can be saved in sequence, building up the overall data. Then when the last part is saved the entire data can then be retrieved.
The form handler pipeline can also use a Merge from Store handler to merge data from a previously saved store. It doesn't even need to be the same store you are saving to. So you could build data through the various states of a form by Save to Session store, then merge the data and save to the database with Save to Default.
With this strategy, it doesn't matter if a form input is Do no render when or Disable when in a specific state. The partial form data can be held and accumulated in the session until the handler pipeline for the final state retrieves the data from the session to make the completed form submission.
State is not like a strict state machine. Each form state is an on/off flag. So a form can exist in all states or it can exist in only one states.
When a page is first rendered, the state is preset as Step 1.
States for the various alert values are automatically set by the Message form handler. When a form handler pipeline returns one or more messages, the form states for the alert levels of those messages is set for the form.
The Next Form State form handler can explicitly set form state and will override any state implied by a Message form handler.
If you are in a single step form that simply shows a success or error Message, you likely will not need to explicitly set the Next Form State. The state implied by the Message is all you will need.
For a multi step form, you can use Next Form State to progress between steps in the form.
The general purpose states Step 1 to Step 5 do not need to be used in sequence. You can simply use them as flags to manage how your multi-step form is shown.
No states need to be used alone. This is not a state machine. Remember that each state is an on/off flag.
If you need more than 5 general purpose form steps, the number can be configured in application/config/ at jl_form_reform.visibility_states.max_form_steps.
One of the great things about Form Reform is that you can mix other block types into your forms. You can integrate blocks with form reform by assigning form state classes using block design or area design.
Forms can be in one or more of the following states. Forms begin in Step 1. Each state has an associated class that can be used to hide blocks when a form is in that state. These states are built into Form Reform blocks and can be added to other blocks using block design.
The general format is:
jl_form_reform_[form_name]_hide_when_[state].
The most likely requirement for other blocks used with form controls is to Hide when a Success message is shown.
| Class | Hide When |
|---|---|
| jl_form_reform__form_reform_hide_when_success | Success message is shown |
| jl_form_reform__form_reform_hide_when_warning | Warning message is shown |
| jl_form_reform__form_reform_hide_when_danger | Danger / Error message is shown |
| jl_form_reform__form_reform_hide_when_primary | Primary message is shown |
| jl_form_reform__form_reform_hide_when_secondary | Secondary message is shown |
| jl_form_reform__form_reform_hide_when_info | Info message is shown |
| jl_form_reform__form_reform_hide_when_light | Light message is shown |
| jl_form_reform__form_reform_hide_when_dark | Dark message is shown |
| jl_form_reform__form_reform_hide_when_1 | On form step 1 |
| jl_form_reform__form_reform_hide_when_2 | On form step 2 |
| jl_form_reform__form_reform_hide_when_3 | On form step 3 |
| jl_form_reform__form_reform_hide_when_4 | On form step 4 |
| jl_form_reform__form_reform_hide_when_5 | On form step 5 |
| jl_form_reform__form_reform_hide_when_user_is_guest | User is Guest |
| jl_form_reform__form_reform_hide_when_user_is_registered | User is Registered |
Form states are specific to a theme, so on this site they show states specific to Atomik. The states adapt automatically to Bootstrap 3,4,5, Atomik and derived themes. They may also adapt automatically to other themes. Where they do not, a theme can be adapted by implementing the interface /JtF/FormReform/FormState/AlertLevelInterface in the theme's PageTheme class.
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.
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.
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.
Express is the built in object data system built in to Concrete CMS. Form Reform is way more powerful for forms. Express supports basic object relationships, but is not robust.
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.
Provides blocks and dashboard utilities to List, display, summarize, generate reports and analyze form submissions from Form Reform. Additionally supports integration with Universal Content Puller.
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 handlers for querying Microsoft Dynamics, forwarding and updating form data to Microsoft Dynamics.
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.
Save submitted forms to Express objects and user attributes. Add and remove users from groups.
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 provides data picking input blocks for Form Reform. Create pickers and selectors from tables or JSON data sources including HTML tables, Calendars, Page Lists, Universal Content Puller and previously submitted form results.
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.
A growing suite of resources to assist those developing blocks, handlers and more complex forms for Form Reform.
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.