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.


The form field filter system

Login / Search

 [ Join | More ]
 
Posted
Rating:
#40750 (In Topic #9090)
Avatar

There is one big new feature in ocPortal 4 designed for power users that we haven't really talked about, except in passing. I've just written up the tutorial for it, and I thought I'd share because I think it is a pretty darned cool thing  :cool:

(I should be clear about this being a feature for power-users. It's intentionally buried deep within the guts of the system and I don't want anyone to feel they need to understand or use this to make a site in ocPortal)

The form field filter system

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

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


Become a fan of ocPortal on Facebook or add me as a friend. Add me on on Twitter.
Was I helpful?
  • If not, please let us know how we can do better (please try and propose any bigger ideas in such a way that they are fundable and scalable).
  • If so, please let others know about ocPortal whenever you see the opportunity.
  • If my reply is too Vulcan or expressed too much in business-strategy terms, and not particularly personal, I apologise. As a company & project maintainer, time is very limited to me, so usually when I write a reply I try and make it generic advice to all readers. I'm also naturally a joined-up thinker, so I always express my thoughts in combined business and technical terms. I recognise not everyone likes that, don't let my Vulcan-thinking stop you enjoying ocPortal on fun personal projects.
  • If my response can inspire a community tutorial, that's a great way of giving back to the project as a user.
Back to the top
 
Posted
Rating:
#40751
Avatar

Community saint

**drool***

So many new OCP toys, so little time.

Thanx for typing that up Chris! I'm going to take a peak at it this weekend and see what fun we can have.

"no violence, no hate, no pain, no enemies
just peace, unity, tolerance and love" - The Beloved

OCP V7 | Advocating monetary reform - FreeOurMoney

Need OCP friendly hosting? Look no further:
Web Hosting, Reseller Hosting, and Dedicated Servers w/cPanel - Elief! - Official hosting partner for ocPortal.
Back to the top
 
1 guests and 0 members have just viewed this: None
Control functions:

Quick reply   Contract

Your name:
Your message: