Plugin Settings

Fetching Plugin Data

my $plugin = MT->component("MyPlugin");
my $my_setting = $plugin->get_config_hash('my_setting','system');

Fetching a Blog-Level Setting

Retrieving a blog-specific setting is very similar, and requires only one additional piece of information: the ID of the blog for which this setting applies:

my $plugin = MT->component("MyPlugin");
my $scope = "blog:" . $blog_id;
my $my_setting = $plugin->get_config_value('my_setting',$scope);

And finally, you can fetch all of the values associated with your plugin's preferences at once by using the get_config_hash method like so:

my $plugin = MT->component("MyPlugin");
my $scope = "blog:" . $blog_id;
my $config = $plugin->get_config_hash($scope);
my $my_setting = $config->{'my_setting'};

Using Configuration Assistant

Even with Movable Type's capable API for letting developers define their own custom user interfaces for collecting plugin preferences from their user's, there exists a far easier method by way of a plugin prototype called "Config Assistant." Config Assistant is useful because it reduces all of the work associated with collecting and accessing plugin configuration data to editing a config file.

To illustrate let's take a second look at the example explained in gory detail previously that surfaced a single text field called "My Setting." To accomplish that task you needed to:

1. Register the setting in your config.yaml.
2. Register a template for rendering your settings form.
3. Create a template to display your setting form elements.

That entire process can be reduced to the following config.yaml file:

name: Example Plugin for Movable Type
id: Example
description: This plugin is an example plugin for Movable Type.
settings:
  my_setting:
    default: Byrne
    scope: blog
blog_config_template: '<mt:PluginConfigForm id="Example">'
plugin_config:
    Example:
        fieldset_1:
            my_setting:
                type: text
                label: "My Setting"
                hint: "Enter anything here."
                tag: 'MySetting'

After all that, this is what Config Assistant will output for your plugin's settings UI:

Config Assistant Registry Settings

Config Assistant is driven 100% by configuration data you place in your plugin's config.yaml. In addition to defining a new data structure for use within your config.yaml, Config Assistant makes use of the following registry keys as well:

• settings - you still need to register the values that will be stored in the database.
• blog_config_template and system_config_template - you also need to provide templates to properly display the form defined by the plugin_config registry data structure.

The new registry data structure parsed exclusively by Config Assistant is associated with the registry key plugin_config. This element has a single child element, corresponding to the plugin's id for which you are defining configuration options. It is this element which will contain each of your plugin's configuration options and input elements, grouped by fieldset. Let's look at an example that stubs out one possible plugin_config data structure:

plugin_config:
  MyPluginID:
    ServerInfo:
      server_host: *snip*
      server_port: *snip*
    PluginOptions: 
      use_https: *snip*
      http_auth_username: *snip*
      http_auth_password: *snip*

The sample above defines two field sets:

• ServerInfo
• PluginOptions

Each of these field sets will be encapsulated by the HTML element from which they get their name:

<fieldset id="ServerInfo">
  <!-- form elements go here -->
</fieldset>
<fieldset id="PluginOptions">
  <!-- form elements go here -->
</fieldset>

Field sets like this provide the benefit of visually grouping related configuration options together. They have no bearing on the functionality of your plugin.

Within each of these field sets, Config Assistant will render their associated form input elements, or "fields."

Each field then supports the following registry properties:

• type - the type of the field. Supported values are: text, textarea, select, checkbox.

• label - the label to display to the left of the input element

• hint - the hint text to display below the input element

• tag - the template tag that will access the value held by the corresponding input element

• values - valid only for fields of type "select" - this contains a comma delimitted list of values to present in the pull down menu

• rows - valid only for fields of type "textarea" - this corresponds to the number of rows of text displayed for the text area input element

Finally, in order for Config Assistant to properly surface the form under your plugin's settings area, you will need to define a blog configuration template using the blog_config_template registry property like so:

blog_config_template: '<mt:PluginConfigForm id="MyPluginID">'

Auto-Generated Template Tags

Each plugin configuration field can define a template tag by which a designer or developer can access its value. If a tag name terminates in a question mark then the system will interpret the tag as a block element. Here are two example configs:

feedburner_id:
    type: text
    label: "Feedburner ID"
    hint: "This is the name of your Feedburner feed."
    tag: 'FeedburnerID'
use_feedburner:
    type: checkbox
    label: "Use Feedburner?"
    tag: 'IfFeedburner?'

And here are corresponding template tags that make use of these configuration options:

<mt:IfFeedburner>
  My feedburner id is <mt:FeedburnerID>.
<mt:Else>
  Feedburner is disabled!
</mt:IfFeedburner>