Load Field

public function onLoadCustomField(string $type) : string

Fires while instantiating the requested custom fields type.

Description

Trigger hook to allow external plugins to include new types of custom fields that have been implemented outside of this project.

The plugins MUST include here all the resources needed to the type, otherwise it wouldn't be possible to instantiate the returned classes.

The filter should return the PHP class name related to the requested type.

In case the specified class doesn't exist, an exception will be thrown. The class MUST extend the VAPCustomField abstract class.

Parameters

$type

(string)  The name of the type to include.

Return Value

String. The classname that will be used to instantiate the type object.

Example

The example below adds support for a new "Radio Buttons" input type handler.

/** 
 * Trigger hook to allow external plugins to include new types of custom
 * fields that have been implemented out of this project. Plugins must
 * include here the file holding the class of the field type.
 *
 * @param   string  $type  The requested custom field type.
 *
 * @return  string  The classname of the type object.
 */
public function onLoadCustomField($type)
{
    if ($type === 'radio')
    {
        // include here external resources
        require_once dirname(__FILE__) . DIRECTORY_SEPARATOR . 'radio.php';

        // return class name for the "Radio Buttons" input
        return 'VAPCustomFieldRadio';
    }
}

The class (shell) of the custom field will be built as follows.

class VAPCustomFieldRadio extends VAPCustomField
{
    /**
     * Returns the name of the field type.
     *
     * @return  string
     */
    public function getType()
    {
        return 'Radio Buttons';
    }

    /**
     * Extracts the value of the custom field and applies any
     * sanitizing according to the settings of the field.
     *
     * @param   array  &$args  The array data to fill-in in case of
     *                         specific rules (name, e-mail, etc...).
     *
     * @return  mixed  A scalar value of the custom field.
     */
    protected function extract(&$args)
    {
        // extract through parent first
        $value = parent::extract($args);

        /**
         * @todo do stuff here (if needed)
         */

        return $value;
    }

    /**
     * Validates the field value.
     *
     * @param   mixed    $value  The field raw value.
     *
     * @return  boolean  True if valid, false otherwise.
     */
    protected function validate($value)
    {
        // validate through parent first
        if (!parent::validate($value))
        {
            return false;
        }

        /**
         * @todo apply further restrictions (if needed)
         */

        return true;
    }

    /**
     * Returns the HTML of the field input.
     *
     * @param   array   $data  An array of display data.
     *
     * @return  string  The HTML of the input.
     */
    protected function getInput($data)
    {
        $html = '';

        // iterate all options
        foreach ($data['options'] as $k => $option)
        {
            // register radio button
            $html .= sprintf(
                '<input type="radio" name="%s" id="%s" class="%s" value="%s" %s style="width: auto !important; margin: 0;" />',
                $data['name'],
                $data['id'] . '-' . $k,
                $data['class'],
                $option,
                $option == $data['value'] ? 'checked' : ''
            );

            // register label
            $html .= sprintf(
                '<label for="%s" style="display: inline-block; margin: 0 12px 0 4px;">%s</label>',
                $data['id'] . '-' . $k,
                $option
            );
        }

        return $html;
    }

    /**
     * Returns an array of display data.
     *
     * @param   array   $data  An array of display data.
     *
     * @return  array
     */
    protected function getDisplayData(array $data)
    {
        // invoke parent first
        $data = parent::getDisplayData($data);

        // assume the options are stored into a textarea, one per line
        $text = preg_split("/\R+/", $this->get('choose'));
        // get rid of empty values
        $data['options'] = array_values(array_filter($text));

        return $data;
    }
}

Changelog