FormIt.Examples.Custom Hook

Often, a form submission should include various logging information such as the visitor's IP address or date the form was submitted. You could print this information as hidden fields in your form, but in this example, we'll show you how to add those values via a custom hook.

We'll base this off of a generic contact form as outlined in the Contact Page example.

Snippet Tag¶

The only thing we need to add to the basic call here is a new hook: we've added a hook named customhook

[[!FormIt?
   &hooks=`spam,customhook,email,redirect`
   &emailTpl=`MyEmailChunk`
   &emailTo=`[email protected]`
   &redirectTo=`123`
   &validate=`name:required,
      email:email:required,
      subject:required,
      text:required:stripTags,
]]

Note that the order in which customhook appears in the &hooks parameter is important. Hooks are executed in the order they are listed.

customhook Snippet¶

The name of the hook corresponds to the name of a Snippet. So we create a Snippet named customhook. It's useful when writing a custom hook to do some testing first, to make sure it is firing. Since the custom hook is only supposed to return either a true or false value, it's not easy to print out debugging information. Instead, we can write something to the MODX log using the $modx->log() function.

Remember you must return true if you want to consider your form validated! Here's our sample code for our new customhook Snippet:

Testing¶

The first thing you'll want to do when writing a custom hook is test it to make sure it is executing.

<?php
$modx->log(xPDO::LOG_LEVEL_ERROR,'Testing my custom hook.');
return true;  //<-- if you omit this or return false, your form won't validate

Save your Snippet, and try submitting your form. Check the MODX system log (Reports --> Error Log) to ensure that your Snippet fired. You should see something like this in the logs:

[2011-10-24 11:23:20] (ERROR @ /index.php) Testing my custom hook.

Setting Values¶

One common thing for custom hooks to do is to calculate new field values – this emulates having a hidden field on the form. For example, your customhook Snippet can set a datestamp for when the form was submitted.

<?php
$datestamp = date('Y-m-d H:i:s');
$hook->setValue('datestamp_submitted', $datestamp);
return true;

Once you have saved this, you can update your MyEmailChunk chunk to include the new information, e.g.

MyEmailChunk:

[[+name]] ([[+email]]) <br/>

Date Submitted: [[+datestamp_submitted]]<br/>

For this to work, the customhook hook must be listed before email in the &hooks parameter in your FormIt call. The order in which snippets appear in the &hooks parameter determines the order of execution. If the email hook would be executed before the custom hook, then the datestamp_submitted placeholder in the chunk would stay empty.

Reading Values¶

Another common thing for custom hooks to do is to read the submitted information and do something with it, e.g. write data to the database. Values can be read individually using $hook->getValue(), e.g.:

$email = $hook->getValue('email');

Or all values can be read at once using $hook->getValues():

$formFields = $hook->getValues();
$email = $formFields['email'];