Understanding FormIt Hooks

A look at how to use built-in and custom hooks with the FormIt extra


In the previous article, we looked at how to create child resources when a new resource is saved. In this one, we'll take a look at using FormIt hooks.


MODX logo

FormIt Hooks

Using hooks in FormIt can be confusing. First, because there are three separate kinds of hooks. Second, unlike the properties in the FormIt tag (and all other MODX snippet tags), the order of the hooks is important (with one exception). Finally, the names of the three types of hooks is not consistent.

All FormIt hooks are written in PHP code. They can be hooks that are built-in to FormIt, or custom hooks you write yourself (or find somewhere). The custom hooks are usually MODX snippets, though it's possible to use file-based hooks as well.


Types of Hooks

The three types of hooks are preHooks, renderHooks, and postHooks. The postHooks were the only hooks in the original FormIt, so they are just called "hooks" and that's the name of the property you need to use in the FormIt tag. If you use the &postHooks property for them, they won't execute — it has to be &hooks.

The preHooks execute before the form is loaded. They are mainly used to pre-fill form fields with default values, or if the form is being used to update something, the current values. Either way the code of the preHook sets the values of placeholders that are in the form, usually with

$modx->setPlaceholder('placeholder_name', $value);

The renderHooks execute immediately after all preHooks are finished. They can be used to manipulate values on the screen. For example, one form field's default value might be the sum of two other fields, or a field value might depend on the current value of another field. A renderHook might also be used to set the CSS class of a field on the screen based on the value of some other field. In that case, you'd use a placeholder for that class name like this:

<span class="[[+span_class_name]]">Something</span>

Your renderHook code would set the span_class_name placeholder:

$modx->setPlaceholder('span_class_name', $className);

Built-in Hooks

Here's are the hooks that are currently installed with FormIt:

  • email — Send content of form as an email
  • redirect — redirect the user to some page after a successful submission
  • spam — attempt to block spammers from using the form
  • recaptcha — use reCaptcha as a spam deterrent
  • math — use a math problem challenge to prevent spam
  • autoresponder — send an automatic email response to the user
  • saveform — save selected form fields to the database
  • formitloadsavedform (preHook) — retrieve saved form data

Custom Hooks

Custom Hooks are simply snippets or files containing PHP code that does whatever you want. The only restriction is that your custom hook must return true on success and false on failure. If your snippet is called 'validate', you'd simply add that name to one of the hooks properties in the FormIt tag:

&hooks=`validate`

Custom hooks can be used as hooks, preHooks, or renderHooks. For hooks, which occur after the form has been submitted, the code of the hook will have access to the data submitted in the form. Say you have this HTML code in your form:


<p>First name: <input type="text" name="fname"></p>

In your code, you'd get the value entered for that field like this:

$hook->getValue('fname');

Ordering Hooks

When the FormIt snippet runs, any preHooks (&hooks) will execute first. Then, any renderHooks (&renderHooks) will execute. Finally, the hooks (&hooks will execute. This order will be followed regardless of where you place the properties in the snippet tag, though it's a good idea to put them in that order in the tag to remind you of when they will execute.

The hooks within each property, on the other hand, are chained. With one exception, they execute in the order they appear in the property. If a hook fails (i.e., returns false) the hooks after it will not execute.

Consider this case:

&hooks=`spam,email`

If the submitted form fails to pass whatever spam tests are used, the spam hook will return false and the email hook will not execute. No email will be sent.

What if we reverse the hooks?

&hooks=`email,spam`

Now the email will be sent before the spam hook even executes. It won't matter if the user has passed or failed the spam challenge, the email will already have been sent.


The Exception

The one exception to the order of execution of the hooks listed in the &hooks property is the redirect hook. It will always execute at the end of the sequence, after all other hooks have been successful.


More Information

The various hooks each respond to their own set of properties, which are usually placed in the FormIt snippet tag. Any custom hooks can also use properties sent in the tag if they are written to do so.

For more information about how to use the various built-in hooks, see the FormIt Docs.

Coming Up

In the next article, we'll begin a series of articles on software testing and test-driven development (TDD).



For more information on how to use MODX to create a web site, see my web site Bob's Guides, or better yet, buy my book: MODX: The Official Guide.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)



Comments (0)


Please login to comment.

  (Login)