Formalicious is a new form builder for MODX. Built by Sterc, it's available from modmore - and on sale until Monday! As a form builder, the end user building the form is not expected to write any HTML, instead they use the interface to create steps and build the form.

In this tutorial I'll show you how to build custom field types in Formalicious, in particular building select fields that are filled dynamically with a snippet.

Step 1: Create the Field Type

First things first! After you've installed Formalicious, go to Extras > Formalicious and click on the Admin panel button in the top right. In the admin panel you can manage the form categories as well as the field types, which is what we want to do.

On the Field Types tab, click on Create field type and fill in the form.

In this example, we'll build a resource select field which will list resources under a certain parent. So we name it Resource Select, and we set the chunk template to customResourceSelectTpl, which we will create after this.

Even though we're building a select field, we're leaving the checkbox for values and the chunk for values empty. This is because we will manage values dynamically, instead of through the form builder.

Save the field type. Next, we'll build the chunk.

Step 2: Create the customResourceSelectTpl Chunk

Every field type in Formalicious has a chunk that it uses for rendering the form. So we need one for our custom field as well.

In the previous step when we created the field type, we said it had a chunk with name customResourceSelectTpl, so let's a create a chunk named customResourceSelectTpl now.

The chunk will need to account for validation and field-level options like the title, so we're using a lot of placeholders. Here's the contents of the chunk.

<div class="row">
    <div class="form-group col-xs-12">
        <label for="field_[[!+id]]">[[!+title]]:</label>
        <select name="field_[[!+id]]" id="field_[[!+id]]" class="form-control">
            [[!getResourceSelectOptions? &selected=`[[!+fi.field_[[+id]]]]`]]
        </select>
        [[!+fi.error.field_[[+id]]]]
    </div>
</div>

Formalicious uses field names in the format "field_{id}", so we need to look at those values.

The magic happens in the getResourceSelectOptions snippet. We pass it the currently selected value (if any), and the snippet will retrieve the available resources.

Of course you can use a completely different chunk. Perhaps you use Foundation instead of Bootstrap, or you want to add some additional information to the field type. All of that can be done in this chunk.

Step 3: Creating the getResourceSelectOptions snippet

Finally we've made it to the critical part: the snippet. In step 2 we called the snippet getResourceSelectOptions, so let's create it.

In the snippet we'll use the xPDO methods newQuery and getCollection together with the xPDOQuery methods to find the right resources. Then we'll iterate over them to create a set of <option>s that can be returned into the markup.

Here's what it looks like:

<?php
// Make sure selected is an integer, representing the resource ID
$current = (int)$modx->getOption('selected', $scriptProperties, 0);

// Create an xPDOQuery instance for resources so we can filter our results
$c = $modx->newQuery('modResource');
// Only show resources that have not been deleted, which are also under resource 2
$c->where(array(
    'deleted' => false,
    'parent' => 2
));
// Sort them by pagetitle
$c->sortby('pagetitle', 'ASC');

// Create an array to hold the output
$output = array();

// Gotta get 'm all!
$resources = $modx->getCollection('modResource', $c);
foreach ($resources as $resource) {

  $selected = $current == $resource->get('id') ? 'selected="selected' : '';
  $output[] = '<option value="' . $resource->get('id') . '" ' . $selected . '>' . $resource->get('pagetitle') . '</option>';
}

return implode('', $output);

Step 4: Add to form

With all pieces in place, you're now ready to add the field type to a form. Go to Extras > Formalicious and edit (or create) your form, and find your custom field type in the form. That's all!

The same process can of course be used to create different types of fields.


Formalicious is on sale until Monday (May 1st)! Grab a license at 50% off and start building forms with Formalicious. Learn more at modmore.com.