Composr Tutorial: The form field filter system

Composr provides a powerful feature for filtering the user input data given through various forms in Composr without having to change the PHP code. The feature can also influence the default values displayed within form fields.

The webmaster can apply this feature via an XML config file that defines the filters.

By the end of this tutorial you will understand the enormous power this can give you.

The config file structure

Editing the XML

(Click to enlarge)

The config file is data/xml_config/fields.xml and should be overridden to data_custom/xml_config/fields.xml. You will see there are some default settings in that file, which are designed to be fairly innocuous examples. You can review the default settings as examples.

Composr has a special built-in editor just to edit this file so you don't have to manually go to the file to make the changes. This is available from:
Admin Zone > Setup > Field filters

The XML file contains the following types of XML tags:

• fieldRestrictions tag
• qualify tags
• filter tags
• various restriction tags

The root XML tag for the config file is fieldRestrictions. Otherwise, the config file mostly consists of restriction tags. Restriction tags (explained further down) can be placed directly beneath fieldRestrictions, but they may also be placed under the special qualify and filter tags. Furthermore, qualify and filter tags can be placed underneath themselves and each other to provide nestings of arbitrary complexity.

The qualify and filter tags

The qualify tag is used to limit the context under which restriction tags may apply. Without the qualify tag, the restrictions would always apply.
The tag may take these attributes (all optional, but they may also be used together):

• pages, a comma-separated list of strings (with wildcard support) indicating the page on which the contained restrictions apply
• types, a comma-separated list of strings (with wildcard support) indicating the types (i.e. the URL type parameter) on which the contained restrictions apply
• fields, a comma-separated list of strings (with wildcard support) indicating the names of parameters on which the contained restrictions apply

The filter tag again is used to limit the situations under which restriction tags may apply, but it filters based on membership rather than context. The tag may take these attributes (all optional, but they may also be used together):

• notStaff, if this is set to '1' then the contained restrictions will only apply to non-staff (if you leave it out it will apply to all)
• groups, a comma-separated list of usergroup ID numbers to which the contained restrictions will apply (if you leave it out it will apply to all)
• members, a comma-separated list of member ID numbers to which the contained restrictions will apply (if you leave it out it will apply to all)

Restriction tags

The following restriction tags are for manipulating form results:

• minLength, give an error if the field value does not meet the minimum length. This is useful to prevent people posting poorly completed entries.
• maxLength, give an error if the field value does not meet the maximum length.
• possibilitySet, give an error if the field value does not match the contained wildcard expression. If you apply the secretive attribute with a value of '1' then the user will not be told what the possible values are, which is useful if you are trying to implement a password (e.g. you can only send me a PT if you use the word "abracadabra" in it).
• disallowedSubstring, provide an error if the field value contains a match for the contained wildcard expression. This is useful as a blocking word-filter. Unlike the main Composr word filter, you have full qualification and filter support, so it is selectively applied as you require.
• disallowedWord, as above but will only match whole words.
• shun, provide an error if the field value equals the contained wildcard expression. This is different from disallowedsubstring simply because it shuns complete matches against the field value rather than substrings.
• pattern, provide an error if the given regular expression does not pass

We also have some designed just for image fields:

• minwidth, give an error if the width is too narrow.
• maxwidth, give an error if the width is too wide.
• minheight, give an error if the height is too short.
• maxheight, give an error if the height is too tall.
• minaspectratio, give an error if the image is too tall for its width. Aspect ratio can be given as a decimal number (e.g. 1.3333333), or as a ratio (e.g. 4:3).
• maxaspectratio, give an error if the image is too wide for its height. Aspect ratio can be given as a decimal number (e.g. 1.3333333), or as a ratio (e.g. 4:3).
• maxfilesize, give an error if the file is too big. You can use a number in bytes, or use the KB or MB suffixes (e.g. 10MB).
• forcelossless, give an error if a lossy file format (JPEG) is used. We cannot detect if a WebP image is lossy or not, so we'll assume it is lossless.
• forceraster, give an error is a vector file format (SVG) is used.
• forcevector, give an error if a non-vector file format is used.
• forcefileextension, give an error if one of the comma-separated file extensions is not used (e.g. png,jpg,jpeg,jpe).

There is a commented example showing how these can be used to meet Facebook Open Graph image restrictions for representative images in the news addon.

You may give each of these restriction tags an error attribute, which will be used for the case when they trigger. If you do not provide a message a default will be used based upon the restriction involved.

The following restriction tags are for both manipulating form results and also default form field values:

• replace, replace the value of the attribute from in the field value with the contents of the tag. This is useful if for example you renamed your product and you wanted people to stop using the old product name on your website. If you don't supply a from attribute it replaces everything (see our default news titles example below).
• removeShout, filter out shouting in the field value (ENTIRELY UPPER CASE FIELD VALUES). This is useful for making a forum appear more civil.
• sentenceCase, make the field value sentence case.
• titleCase, make the field value Title Case.
• deepClean, apply the deep clean process on the field value. Clean common ugly patterns out, such as leading white-space, all-caps, or paste-from-Word problems. This is a potentially disruptive operation, so only use it on data that has been entered by n00bs.
• append, append something to the field value. This is useful if you want submissions from non-staff to be flagged with a disclaimer message.
• prepend, prepend something to the field value.

Example: removing shouting from news

The default fields.xml has a mix of different examples. Here's one simple standalone example that would remove the shouting from news posts:

With this example posting TEST in a news post title/body would result in it getting changed to Test.

As you can see the qualify tag defines:

• the cms_news page in the pages attribute
• the screen type that corresponds to a new news post that has just been submitted (_add)
• the particular form field names to apply the filter to

Using qualify tags we can therefore focus our filters sharply.

Example: default news titles

Here's one simple standalone example that would set the default title for all news posts to "Default title":

It works by applying itself to the type of the main form (add) rather than the type of where forms are submitted to (_add).

Wildcard expressions

Wildcard expressions support * (match any string) and _ (match one character) as wildcards, with backslash escaping (e.g. \* matches a literal * rather than works as a wildcard).

Extension (advanced)

The form field filter system is ripe for extension by programmers. It would not be hard for a programmer to add new filter attributes. For example, a filter could be added to allow filtering based on day of the week, or geographic location. We'd love to see innovative Composr modifications written around this kind of functionality (e.g. a modification to "only allow people to submit a quiz on Halloween from an iPhone").

See also

• Filtering using Selectcode syntax

Feedback

Have a suggestion? Report an issue on the tracker.