Torro Forms // Using Element Types API

Our Element Types API can be used to register your own custom element types so that you can handle user input in other ways, beyond what the plugin offers out-of-the-box.

To get started, you need to create a new class for your element type. This class has to extend the Torro_Element_Type class. This class will take care of preparing the element data for rendering in the frontend and validating user input for that element type. It can also handle settings fields in the admin and customization of the admin UI if that is necessary for the element type.

Regarding output of the element type field in the frontend, Torro Forms provides a flexible template hierarchy you can use. So if you need to customize how your element type is displayed in the frontend, you need to add a template file for your element type.

This page contains the technical documentation for the Torro Forms Element Types API and is written for developers. If you're not a developer you may want to review the Form Elements.

Default class example

class My_Element_Type extends Torro_Element_Type {
  /**
   * This method is the absolute minimum required to implement.
   * It contains the general specification of the element type.
   */
  protected function init() {
    $this->name = 'myelementtype';
    $this->title = __( 'My element type', 'my-textdomain' );
    $this->description = __( 'This is my element type', 'my-textdomain' );
    $this->icon_url = 'my-icon-url.png';
  }

  /**
   * This method can be used to add additional data that can be used
   * by the frontend template. All keys in the $data array will be available
   * as individual variables in the template.
   *
   * Checkout the Torro_Element_Type base class to see what is available
   * by default. Make sure to always call the parent method (see below).
   */
  public function to_json( $element ) {
    $data = parent::to_json( $element );
    
    $data['my_custom_value'] = 'some-value';

    return $data;
  }

  /**
   * This method can be used to add settings fields in the admin area.
   * The values of these settings can then be passed to the frontend template
   * by using the above to_json() method.
   *
   * There are two special fields which are automatically handled by
   * Torro Forms: 'description' (see below) and 'required'. If you add one of these
   * fields, they will be automatically passed to the template, so you don't
   * need to take care of it manually.
   */
  protected function settings_fields() {
    $this->settings_fields = array(
      'description' => array(
        'title'     => __( 'Description', 'my-textdomain' ),
        'type'      => 'textarea',
        'description' => __( 'The description will be shown after the element.', 'my-textdomain' ),
        'default'   => ''
      ),
    );
  }

  /**
   * This method should be used to validate user input for the
   * element type. It must either return the validated input value
   * or a Torro_Error object if something went wrong during validation.
   */
  public function validate( $input, $element ) {
    // Do your validation code here
    return $input;
  }
}

Registering the element type

    torro()->element_types()->register( 'My_Element_Type' );

Default template example

/**
 * Template: element-type-myelementtype.php
 *
 * Available data: $element_id, $type, $id, $name, $classes, $description, $required, $answers, $response, $extra_attr, $my_custom_value
 */

// This template file must have the name element-type-{{NAME_OF_YOUR_ELEMENT_TYPE}}.php

?>
<input type="<?php echo esc_attr( $type ); ?>" id="<?php echo esc_attr( $id ); ?>" name="<?php echo esc_attr( $name ); ?>" class="<?php echo esc_attr( implode( ' ', $classes ) ); ?>" value="<?php echo esc_attr( $response ); ?>"<?php echo $extra_attr; ?> aria-describedby="<?php echo esc_attr( $id ); ?>-description <?php echo esc_attr( $id ); ?>-errors">
<span><?php echo $my_custom_value; ?></span>

Registering your template directory

// You should only register your template location once for your extension.

function myextension_register_template_directory( $template_locations ) {
    // The key is the priority of the template location. Use something higher than 20.
    // The value must be the path to your extension's template directory.
    $locations[70] = plugin_dir_path( __FILE__ ) . 'templates/';
    
    return $locations;
}
add_filter( 'torro_template_locations', 'myextension_register_template_directory' );

Example

 

For a good example of how the Element Types API works, checkout the Torro Forms Plugin Boilerplate. It contains two additional element types: a simple date selector field and an iframe (a non-input element type) - thus it gives an overview of how you can handle different kinds of element types.

Checkout the class and template for the date field, and if you're interested in non-input element types, the class and template for the iframe are a good example as well.

How to add your code

To add your code, we have created your the function torro_load(). Put in your function to the parameters and it will be loaded in the right way.

function your_torro_functionality(){
    require_once 'my-element-type.php';

// Also take care of the other functionality here,
// like registering the template location. } function my_plugin() { if ( ! function_exists( 'torro_load' ) ) { return; // Torro Forms is not active } torro_load( 'your_torro_functionality' ); } add_action( 'plugins_loaded', 'my_plugin' );
Fork me on GitHub