Custom Custom Field Types

Custom Fields are feature available exclusively in Movable Type Pro. Custom Fields allow an entry, page, category, folder or user to be extended with additional data elements that a user can edit from within the Movable Type application. Movable Type provides the most common form elements or “custom field types” right out of the box, such as:

• single line text field
• multi-line large text area
• radio buttons
• pull-down menus
• etc.

A custom field type governs what the input element looks like on the edit page or edit entry screen for example, and what is stored as the value for that custom field in the database.

Sometimes the choices available are not adequate, and a developer would like to define a new form element or custom field type. For example, suppose you want to allow authors to select a different sidebar (or “widget set”) from a pull down menu for each entry and/or page? Such an option doesn’t exist by default.

The following example will show how to create a custom “Custom Field Type” that a user can use to associate with a page or entry. The custom field could then allow them to select from a pull down menu the widget set that they would like to have associated with the current entry or page. Here is an example config.yaml file for this plugin:

name: Example Plugin for Movable Type
id: Example
description: This plugin is an example plugin for Movable Type.
version: 1.0
customfield_types:
    widget_set_type:
        label: 'Widget Set'
        field_html: $Example::Example::Plugin::field_html
        no_default: 1
        order: 500
        column_def: 'string(255)'

Registry Properties

• label - the display name of the custom field type. This is what will appear in the pull down menu associated with the custom field type on the create custom field screen.
• field_html - The HTML and template code that will be used to render the custom field on the edit page/entry screen. This can reference a handler that can return the HTML as well.
• field_html_params - this is a reference to a handler that can manipulate the input parameters associated with the current object and screen inside the application.
• no_default - a boolean value (1 or 0) associated with whether the field should be forced into having a default value associated with it.
• options_field - The HTML to be used on the edit custom field screen to allow the custom field to have associated with it any additional configuration options.
• options_delimiter - when specified, the value of this property will be used to split the options string into an array of multiple values that can be looped over in your field_html handler.
• order - an integer referring to the placement of the custom field relative to other fields on the edit entry/page screens.
• context - can be given a value of “blog” (default) or “system” and governs whether the custom field is available exclusively at a system level, or is available at a blog level as well.
• column_def - the datatype of the associated custom field type. Permitted data types are:
  • vchar
  • vchar_idx
  • vinteger
  • vinteger_idx
  • vdatetime
  • vdatetime_idx
  • vfloat
  • vfloat_idx
  • vblob
  • vclob

The following is an example Plugin.pm associated with the above example config.yaml. It defines the various handlers associated with each of the possible registry properties.

package Example::Plugin;
use strict;

sub field_html {
    my $app = MT->instance;
    my $blog = $app->blog;

    my $html = q{<select name="<mt:var name="field_name">" 
       id="<mt:var name="field_id">">};

    my $wm = MT::Plugin::WidgetManager::instance();
    my $modulesets = 
        $wm->load_selected_modules($app->blog->id) || {};
    my @names = sort keys %$modulesets;

    $html .= q{<option value="" <mt:if name="field_value" eq="">
       selected="selected"</mt:if>>None Selected</option>};
    foreach my $n (@names) {
        $html .= q{<option<mt:if name="field_value" eq="}.$n.q{">
        selected="selected"</mt:if>>}.$n.q{</option>};
    }
    $html .= '</select>';
    return $html;
}

HTML Field Parameters

Sometimes a custom field needs to access the parameters associated with other fields, or other parameters associated with the edit form rendering the custom field. An example of this might be when a custom field that contains a date/time value needs to default to a date associated with the creation time of the object being edited. The following example shows a trivial example of how a developer can register a handler that can access and/or modify template parameters.

First, the config.yaml:

customfield_types:
    my_cf_type:
        label: 'My Custom Field Type'
        field_html_params: $Example::Example::Plugin::field_html_params
        order: 500

And now, the Plugin.pm file:

sub field_html_params {
    my ($key, $tmpl_key, $tmpl_param) = @_;
    my $app = MT->instance;
    my $blog = $app->blog;
    $tmpl_param->{'param_name'} = "foo";
}

Custom Field Options

Some custom fields may need to accept options beyond the standard set of parameters associated with a custom field. An example of this might be a radio button. A radio button needs to give administrators the ability to define multiple radio button values to choose from.

To give this ability to an admin, a developer needs to register an options_field handler with the custom field. This handler need only return valid HTML with, or with MT template code. Movable Type will then render that code on the edit form for the custom field itself.

The following example pulls from Movable Type itself, and shows how you can define a custom radio button type. First the config.yaml:

customfield_types:
    my_radio:
        label: 'My Radio'
        field_html: $Example::Example::Plugin::field_html
        options_field: $Example::Example::Plugin::options_field
        options_delimiter: ','
        order: 500

You will notice that in this example you will need to define not only the options_field, but also customize the field_html. The HTML returned by the field_html handler needs to be able to loop over each of the values defined and stored in the custom fields options value. When an options_delimiter is also defined, Movable Type will automatically split the options value into an array and make available a template parameter called option_loop that contains each of the values entered by the administrator.

Here is an excerpt from the Plugin.pm file that contains the two handlers needed by this example:

sub options_field {
    return q{
    <div class="textarea-wrapper"><input type="text" name="options" 
       value="<mt:var name="options" escape="html">" id="options" class="full-width" />
    </div>
    <p class="hint">
    Please enter all allowable options for this field as a comma delimited list.
    </p>
    };
}

sub field_html {
      return q{
    <ul class="custom-field-radio-list">
    <mt:loop name="option_loop">
    <mt:if name="option"><li><input type="radio" name="<mt:var name="field_name">"
      value="<mt:var name="option" escape="html">" id="<mt"var name="field_id">_<mt:var
      name="__counter__">"<mt:if name="is_selected"> checked="checked"</mt:if> class="rb"
      /> <label for="<mt:var name="field_id">_<mt:var name="__counter__">"><mt:var
      name="option" escape="html"></label></li></mt:if>
    </mt:loop>
    </ul>
    };
}