Form Behaviour - Form State

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.

The Behaviour tab

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.

Form State

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.

Hide when

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.

Do not render when

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.

Disable when

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. 

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.
Hide Disable Do not render When

Maintaining data across form states

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.

Initial Value

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.

Incremental Save

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.

Setting form State

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.

Message implies state

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.

Next Form State

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.

Plan your Steps and States

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.

Form States and other blocks

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.

General help for Form State Classes

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.

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.