Integrating a Template into MODX part 5

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.

TipTip: 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.

Template Variables Tab

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.

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.

Form Customization Profile

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

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.

Create New Set
TipTip: 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

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.

Set Information and Fields Tab

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.

modx-page-settings-left

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.

modx-page-settings-right

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.

modx-page-settings-right-box-left

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).

modx-page-settings-right-box-right

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

modx-resource-content

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).

modx-resource-main-left

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).

modx-resource-main-right

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.

Regions Tab

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.

Template Variables Tab

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).

Set Information and Fields Tab

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.

Updated Region for Template Variables

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.

Right Click on the 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.

Change Action field to Update Resource and Enable the Active Checkbox

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.

Content Area with Form Customization

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.

Apply Form Customization to a Specific 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.

Export Set

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.

27 Aug
2012

Author Benjamin Marte Category Tutorials Comments (5)

Comments (5)

  1. Susan Ottwell:
    Aug 28, 2012 at 01:07 AM

    And this just goes to show the true value of the flexible nature of MODx (especially Revo). For years one of the more common requests has been to be able to move TVs to their own tab, because users found it confusing to have the TV fields below the content field! So you can adjust the Manager, at least for resource editing, to suit yourself or your clients whatever your preference may be.

  2. Crssp ty:
    Nov 05, 2012 at 10:56 AM

    Hi Ben, an plans on continuing your site project tutorial series?
    It's hard finding any MODX 'college' tutorials for learning.
    The main MODX site never produced much, after more than a year in existence now :(
    Great stuff here, I've just been slow soaking it in.
    -ty

  3. Wouter:
    Mar 21, 2013 at 07:19 AM

    I must say I am truly impressed.

    I've been a Modx Evo user for a couple of years, and I'm very pleased to see how far Modx has come. I've followed along with your tutorial using a Modx Cloud lab account.

    Your tutorial is also of high quality. I've always found it difficult to wrap my head around certain concepts of ModX, and you explain them very well.

    Thank you for this great series.

  4. Erwin:
    Apr 01, 2013 at 04:18 PM

    Finally some Modx tutorials which explain the "why" not the "how". Great and thank you!
    I hope you supply us with more.

  5. Omar:
    Aug 05, 2013 at 11:19 PM

    Remarkable stuff. Thanks a lot. Please do more tutorials such as how to remove the MODX logo and name on the manager login page.

    Many thanks


Leave a Comment

This thread has been closed from taking new comments.

Scroll to top