HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS, which is now in beta. ocPortal 9 will be superseded by Composr 10.

Head over to compo.sr for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.


ocPortal Tutorial: The form field filter system

Written by Chris Graham, ocProducts
ocPortal provides an advanced feature for manipulating forms and the results of forms using filters without having to change the PHP code. By the end of this tutorial you will understand the enormous power this can give you.
This features are intended for power-users, using an XML config file for defining the filters.

The form field filter system can influence both form results, and the default values displayed within form fields.


The config file structure

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

The root XML tag for the config file is 'fieldRestrictions'. Otherwise, the config file mostly consists of restriction tags. Restriction tags (explained later) 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 3 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 3 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 supported 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 ocPortal 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

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 supported for 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.
  • '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.
  • '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.

Extension

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 ocPortal 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