Integrating a Template into MODX part 5

Form Customization

Form Customization allows users to create Rules, which govern how manager pages render their forms in the MODX Revolution Manager.

How Does it Work?

Currently, Form Customization has 3 layers:

Profile -> Sets -> Rules

A Profile is a collection of Sets, and Sets are collections of Rules. Profiles can be restricted to specific User Groups.

A Set is a collection of Rules, and is tied to a certain view. Normally, you would have a Set for the Resource/Create page, and a Set for the Resource/Update page. Sets can also be tied to specific Templates (meaning they load only when the Resource is using that Template). They can also have a 'Constraint' set, which limits the Set's execution to the restriction made in the Constraint.

A Rule is all the variations applied in a Set. Rules are hidden from view in MODX Revolution, but are instead shown as fields on the Set Editing page.

Tip: You can find the full Form Customization documentation on the MODX RTFM site

Now that we know how Form Customization works let's put it in practice.

In our previous tutorial we created some Template Variables (TV) and assigned them to our template, when you create a TV it is displayed in the TV tab in the MODX manager.

With Form Customization we will change it so it displays in the Document tab, this makes MODX easier to use for our users/clients. In order to accomplish this we need to click on Security > Form Customization.

This will bring us to the Form Customization Profile where we can create a new Form Customization Profile for our template, click on Create New Profile then enter a name for our Profile, a Description and make sure you make it Active and click Save.

This will add our newly created profile to the table, right click on the profile and choose Edit.

This will take us to the Create New Set page, where we can create a new Set of Rules so we can apply them to our templates. Click on Create New Set in the Action drop down choose Create Resource (this will apply this Rule Set when creating a new resource) then select which Template you want this Rule Set to apply to, the Constraint Field and Constraint can be left empty they don't need any values for what we want to accomplish, finally click save.

Tip: Constraint Field can be used to only apply a Rule Set when a specific value is met, for example we can have the Constraint Field value be parent and the Constraint value be 2 this will only apply this Rule Set to all resources that are children of a Resource whose ID is 2.

Constraint Fields can be any MODX tag or Template Variable so feel free to get creative and customize the MODX backend for your users without hacking the core.

This will add our Rule Set to the table, now let's adjust what this Rule Set will do to our template. Right click on the Rule Set and click Edit

This will take us to the Set Information and Fields tab which contains all the properties that are visible when creating a new resource. The Action tab is what determines to trigger our Rule Set since we are not putting any restrictions it will always run when a new Resource is created with the Homepage template. The Active tab determines if our Rule Set is enabled or disabled.

The table contains all the sections a new Resource has, the first section modx-page-settings-left has 5 fields these are the fields located on the left of the Settings tab when creating or editing a resource: parent-cmb (Parent Resource), class_key (Resource Type), content_type (Content Disposition) and menuindex (Menu Index). Here we can specify which of these fields we would like to display by checking the Visible checkbox, we can change the Label with which it displays and if necessary specify a Default Value just double click on these fields in order to insert a value.

The modx-page-settings-right section has 3 fields which are the fields located on the right side of the Settings tab: publishedon (Published On), pub_date (Published Date) and unpub_date (Unpublished Date). Again we can specify which to display, change the labels and specify default values.

The modx-page-settings-right-box-left section contains 5 fields these are located in the box in the Settings tab under the Publish/Unpublish selectors: isfolder (Container), searchable (Searchable), richtext (Rich Text), uri_override and uri apply to the (Freeze URI) checkbox.

The modx-page-settings-right-box-right section contains the 3 fields to the right of the modx-page-settings-right-box-left section, these are: cachable (Cachable), sync site (Empty Cache) and deleted (Deleted).

The modx-resource-content section contains one field modx-resource-content (Content) which is where the content area of the resource is displayed.

The modx-resource-main-left section is the content on the left side in Document tab with the following fields: id (the id of the resource on the left tree), pagetitle (Pagetitle), longtitle (Longtitle), description (Description) and introtext (Summary-introtext).

The modx-resource-main-right section is where all the fields on the right of modx-resource-main-left are displayed, these fields are: template (Uses Template), alias (Resource Alias), menutitle (Menu Title), link_attributes (Link Attributes), hidemenu (Hide From Menus) and published (Published).

For all of the above mentioned fields we can choose to show or hide them based on their individual visible value, we can change the label with which they display with and set a default value for them.

The next tab is Regions which allows us to show or hide each of the above mentioned sections instead of hiding each field individually in each section by changing their visible value and we can also change or add a title for each section.

The last tab is Template Variables this is where all our custom TV display, the table contains all of our TV names, the Visible checkbox, Label so we can change the name to something more logical for our users, Default Value, Original Value, Region which is on what part of the manager they render in and Region Rank which lets us choose the order of these in the section they will be rendered.

Now let's proceed to move our TV's to the content area of our resource to do this we need to go to the Set Information and Fields tab, find in what section our Content renders in (modx-resource-content).

Now go to the Template Variables tab and change the Region in which each of our TV's render in by double clicking the value in the Region field and typing in the name of the Region we want the TV to render in (modx-resource-content) and click on Save. You can also specify in what order they should display by inserting a numeric value in the Region Rank fields.

After we save our changes click on Close so we can go back to the Form Customization Profile page so we can duplicate our Set, we need to duplicate our Set because it will only apply to a resource when it's created with the Homepage template. Proceed to right click on our Set and select duplicate, once duplicated right click on our duplicated Set and click Edit.

This brings us to the Form Customization Profile for our duplicated Set now all we need to do is change the Action field to Update Resource and enable the Active checkbox and click Save, now this rule will also run when a resource with the Homepage template is updated.

Now when we go to a resource that is using our Homepage template you can see our TV's are now rendered after the Content area making it easier for our non-technical users to edit each section of the homepage without breaking your layout.

we can also apply this Form Customization and it's Rule Set to specific user groups by going to the User Groups tab in the Form Customization Profile and selecting the user group.

You can also export your Sets by right clicking on them and selecting Export, MODX will generate an XML file that you can import into another MODX install and apply this Set for faster Form Customization creation.

As you can see Form Customization allows you simplify the MODX experience for your clients or users by applying the Form Customization to their specific user group while you have the full MODX experience in your user group.

I hope this tutorial helps you have a better understanding on how Form Customization works and what you can accomplish with it, let me know your thoughts and thanks for reading.