FormBuilder: Processor Action module

A FormBuilder plugin module interface that enables you to easily hook into any step of form rendering or processing.

FormBuilderProcessorAction modules can be selected and enabled from any FormBuider form’s “Actions” tab. Once enabled, they have various methods that will be called automatically by FormBuilder at the appropriate time during form rendering, processing or administration. These methods are outlined further down.

The Stripe Payments Processor is an example of a FormBuilderProcessorAction module.

Creating an action module

To create a FormBuilderProcessorAction module, create a class named FormBuilderProcessorHello, optionally replacing “Hello” with the name of your action. The class should extend the FormBuilderProcessorAction class located in /site/modules/FormBuilder/.

Your module class should implement one or more of the defined methods further down in the method reference, as needed, to accomplish whatever your action module is intended to do.

These defined methods can also be used to add hooks anywhere in FormBuilder. So if you don’t see a specific method that you need, then any of the predefined methods can also be used to add hooks to any part of the process. The most commonly implemented methods are actionReady() and formReady().

Your module should be placed in the file FormBuilderProcessorHello.module.php in the directory /site/modules/FormBuilderProcessorHello/ (optionally replacing “Hello” with the name of your action).

Below is an example of the code for a FormBuilderProcessorHello module:

// FormBuilder Processor Action: Hello World
// Displays a "hello world" or custom message above any rendered form
// that has this action selected on its “Actions” tab

class FormBuilderProcessorHello extends FormBuilderProcessorAction {

  // define any config settings for this module
  public function __construct() {
    parent::__construct();
    $this->set('hello_text', 'Hello world'); // set default value
  }

  // Called when form ready to be rendered
  // Display a hello world message above rendered form
  public function renderReady() {
    $text = $this->sanitizer->entities($this->hello_text);
    $this->form()->prependMarkup .= "<p>$text</p>";
  }

  // Get configuration settings (allow changing the Hello World text)
  public function getConfigInputfields(InputfieldWrapper $inputfields) {
    parent::getConfigInputfields($inputfields);
    $f = $inputfields->InputfieldText;
    $f->attr('name', 'hello_text');
    $f->label = 'Hello world text';
    $f->val($this->hello_text);
    $inputfields->add($f);
  }
}

You should also create a FormBuilderProcessorHello.info.php file in the same directory that returns information about your module:

$info = [
 'title' => 'Hello world action example',
 'version' => 1,
 'summary' => 'Example of a FormBuilderProcessor custom action',
 'icon' => 'smile-o',
 'requires' => 'FormBuilder>=0.4.5',
];

Test it out! In your admin, do a Modules > Refresh and then install your module. Edit a form and click the “Actions” tab. Check the box for your “Hello World” action. It will open a text input where you can configure the Hello message. Save, and then Preview your form.

Taking it further

Now let’s take the module a little bit further, adding an action in the admin where form entries are listed. We’ll add a “Hello” button that can be applied to any existing form entry. In this example, it will say "hello" to any checked entries. Silly I know, but hopefully hints at what might be possible. This would be added to the class from our previous code example above.

  // List entries in admin
  // Adds a 'hello world' action button for entries admin checks boxes for
  public function adminListEntries() {
    $this->addHookAfter('ProcessFormBuilderEntries::getAllowedActions', function($e) {
      $actions = $e->return; // array
      $actions[] = [
        'name' => 'hello-world',
        'label' => $this->hello_text,
        'icon' => 'smile-o'
      ];
      $e->return = $actions;
    });
    $this->addHookAfter('ProcessFormBuilderEntries::processActionForEntry', function($e) {
      if($e->return) return; // true return value means it was already handled
      $action = $e->arguments(0); // array
      $entry = $e->arguments(1); // array
      if($action['name'] === 'hello-world') {
        $this->message("$this->hello_text for entry $entry[id]!");
        $e->return = true; // indicate we handled it
      }
    });
  }

Click any linked item for full usage details and examples. Hookable methods are indicated with the icon. In addition to those shown below, the FormBuilderProcessorAction class also inherits all the methods and properties of: WireData and Wire.

• Implementation
• Tools
• Config
• Properties

Additional methods and properties

In addition to the methods and properties above, FormBuilderProcessorAction also inherits the methods and properties of these classes:

• WireData
• Wire