The Config Assistant plugin is a powerful platform plugin which significantly
reduces the work necessary to create and deploy Melody/Movable Type plugins
and themes.

The plugin streamlines the plugin/theme development process by extending the
grammar of each plugin's YAML-based configuration file (config.yaml) to
allow for new and powerful features which previously required a significant
amount of Perl and/or template markup code.

It also makes plugin and theme deployment as easy as dropping a single folder
into the addons or plugins directory eliminating the extra steps previously
foisted upon end users to deploy a plugin/theme's static content.

Config Assistant provides a number of new features to developers, designers
and admins

It significantly reduces the work involved in creating user-facing config
settings forms for themes and plugins and creating template tags to access
those values from the templates.

Reduces the number of steps needed for theme/plugin installation and upgrade
by automatically copying static files into the proper place in the
mt-static folder

It provides a way for plugin/theme designers to specify desired values for
related blog preferences and plugin settings and for users to automatically
apply them. (Previously handled by the AutoPrefs plugin.)

The latest version of the plugin can be downloaded from the its Github
repo which is now part of the Open Melody user account. Packaged
downloads are also available if you prefer.

Installation follows the standard plugin installation procedures
EXCEPT that the ConfigAssistant.plugin directory must be installed
into the addons directory and not the plugins directory. If you do
not have an addons directory, you can simply create one in the root of your MT
directory ($MT_HOME/addons).

If for whatever reason you do install this plugin into your plugins folder
as is common with other plugins, Movable Type may produce inexplicable errors.
So please be careful and mindful to follow the above instructions.

If you are upgrading from a previous version of Config Assistant, you should
remove any copy of Config Assistant from your plugins directory if one is
installed there.

prompt> rm -rf $MT_HOME/plugins/ConfigAssistant

If you are upgrading from a version prior to 2.1.6, then you will also need
to remove the following directory:

prompt> rm -rf $MT_HOME/addons/ConfigAssistant.plugin

Starting with version 2.0, the AutoPrefs plugin has been merged into Config
Assistant. If you already have the AutoPrefs plugin installed, it will be
disabled by Config Assistant at which point you can remove AutoPrefs from your
plugins directory.

This plugin adds support for a new key in any plugin's config.yaml file
called options, which is placed as a descendant to a defined template set.
When a user of your plugin applies the corresponding template set then a
"Theme Options" menu item will automatically appear in their "Design" menu.
They can click that menu item to be taken directly to a page on which they can
edit all of their theme's settings.

In this example two fieldsets have been defined: homepage and feed, and
this will generate two tabs of options on the Theme Options screen. Note that
the fieldset keys (in this case homepage and feed) must be unique within
your theme or plugin.

In this example two options, or fields, have been defined: feedburner_id and
use_feedburner. Note that the option keys (in this case feedburner_id and
use_feedburner) must be unique within your theme or plugin.

show_label - display the label? (default: yes). This is ideal for
checkboxes.

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

condition - a code reference that will determine if an option is rendered
to the screen or not. The handler should return true to show the option, or
false to hide it.

default - a static value for the option.

fieldset - specify which fieldset a field belongs to.

order - the sort order for the field within its fieldset

republish - a list of template identifiers (delimited by a comma) that
reference templates that should be rebuilt when a theme option changes.
Index or archive template types can be specified; specifying other types
(system, modules, widgets) doesn't work because those don't actually publish
anything.

If the specified template identifier is for an index template, the
template is simply force republished.

If the specified template identifier is for an Entry or Page archive
template, the most recent Entry or Page is republished. If using cached
and included modules/widgets then this is enough to refresh them.

If the specified template identifier is for another type of archive
(Category, Yearly, Author, etc) then that template is republished in its
entirety. Use this with caution: republishing a type of archive can be
time-consuming. This is best used when there are a known limited number of
archives (for example, if only four categories will ever exist in your
blog), and when the Publish Queue is employed for that template type.

scope - (for plugin settings only, all theme options are required to be
blog specific) determines whether the config option will be rendered at the
blog level or system level.

required - can be set to 1 to indicate a field as required,
necessitating a value.

Below is a list of acceptable values for the type parameter for any defined
field:

asset - Select an asset from a popup dialog. An additional template tag is
created for you which gives you access to the asset created for you when the
file is uploaded. See "Asset Template Tags" below.

filter_class: filter an asset listing popup by specifying the asset
class. Popular values are image, audio, video, and file, though any
registered asset type is valid.

author - Select an author from a popup dialog. To appear in the popup, an
author must have a Role, associating them with the blog in which this field
is used. This field supports two additional optional keys:

roles - where a comma-separated list of valid Roles may be supplied to
filter the popup dialog contents.

all_authors - if flagged 1 then all authors in the system with post
permissions or a role (as specified in the above roles key) can be
supplied to filter the popup dialog contents.

blogs - Produces a pull down menu listing every blog in the system.
Warning: this is not advisable for installations with many blogs as it can
dramatically impact performance (negatively). This field supports an additional key:

category - Produces the ability to select a single category via a
drop-down listing. This field supports additional optional keys:

multiple - set to 1 to create a multi-select listing, allowing multiple
categories to be selected.

show_children - set to 1 to include child categories, in addition to
parent.

checkbox - Produces a single checkbox, ideal for boolean values, or a set
of checkboxes. When using this type to display multiple checkboxes, use the
values field option to provide a list of checkbox labels/values. Use the
delimiter field option to specify how your list of checkbox options are
separated. See "Working with Checkboxes."

datetime - Produces a date and time selection dialog for selecting a
timestamp.

entry - Produces the ability to select a single entry or many entries via
a small pop-up dialog. In the dialog, the user will be permitted to search
the system via keyword for the entry they are looking for. This field type
supports additional properties:

all_blogs - a boolean value which determines whether the user will be
constricted to searching/selecting entries in the current blog, or all
blogs on the system.

multiple - a boolean value which allows multiple entries to be selected.

inactive_area - a boolean value which adds a separate area to store
selected entry or entries but not publish them -- useful when you need to
temporarily remove an item from the home page, for example.

When the keys multiple or inactive_area are true, selected entries can
be sorted by drag and drop, making it easy to order content.

entry_or_page - Operates identically to the entry config type except
that it allows the ability to select either an Entry or Page (or any
combination of Entries and Pages). The same all_blogs, multiple, and
inactive_area keys are also supported.

file - Allows a user to upload a file, which in turn gets converted into
an asset. An additional field property is supported for file types:
destination which can be used to customize the path/url of the uploaded
file. See "Example File" below. Files uploaded are uploaded into a path
relative to the mt-static/support directory. Also, for each option of type
file that defined, an additional template tag is created for you which gives
you access to the asset created for you when the file is uploaded. See
"Asset Template Tags" below.

folder - Produces the ability to select a single folder via a drop-down
listing. This field supports additional optional keys:

multiple - set to 1 to create a multi-select listing, allowing multiple
folders to be selected.

show_children - set to 1 to include child folders, in addition to
parent.

link-group - Produces an ordered list of links manually entered by the
user. Options of this type will have defined for them an additional template
tag to make it easier to loop over the links entered by the user in your
templates. See "Link Group Template Tags" below.

page - Operates identically to the entry type except that it allows the
ability to select Pages instead of Entries. The same all_blogs,
multiple, and inactive_area keys are also supported.

radio - Produces a set of radio buttons of arbitrary values. Those values
are defined by specifying a sibling element called values which should
contain a comma delimited list of values to present as radio buttons.
Optionally use the delimiter key to specify a value separator: , (comma)
is the default; ; (semicolon) is a good alternative if the field values
contain a comma, for example.

radio-image - Produces a javascript enabled list of radio buttons where
each "button" is an image. Note that this version of the radio type supports
a special syntax for the values attribute. See example below.

select - Produces a pull-down menu of arbitrary values. Those values are
defined by specifying a sibling element called values which should contain
a comma delimited list of values to present in the pull down menu.
Optionally use the delimiter key to specify a value separator: , (comma)
is the default; ; (semicolon) is a good alternative if the field values
contain a comma, for example.

separator - Sometimes you will want to divide your options into smaller
sections, and the separator facilitates that. This is a special type of
field because there is no editable form to interact with and is
informational only. Only the label, hint, order, and fieldset keys
are valid with this field type.

tagged-entry - Produces a pull down menu of entries tagged a certain
way. This type supports the following additional attributes: lastn and
tag-filter.

text - Produces a simple single line text box.

textarea - Produces a multi-line text box. You can specify the rows
sibling element to control the size/height of the text box.

text-group - Produces an ordered list of text labels manually entered by
the user. Options of this type will have defined for them an additional
template tag to make it easier to loop over the text items entered by the
user in your templates. See "Text Group Template Tags" below.

** Entry, Page, and Entry Or Page Tags **

These three field types basically work the same, so the YAML used in your
theme will look similar, too. Consider this example:

This will build a field that allows for the selection of favorite Entries.
With the multiple key set many entries can be selected, and drag and drop to
sort the order of the selected entries will be available. With the
inactive_area key set Entries can be dragged to the inactive area,
preventing them from being published in the My Favorite Entries section, but
keeping them ready for easy re-use. (Note that moving Entries to the inactive
area does not unpublish them, it simply doesn't publish them where the Faves
tag is used.)

To publish My Favorite Entries a special block tag is available. Append
Entries to the tag defined to access all of the Entry context tags. Example:

The same capabilities exist for the Entry, Page, and Entry or Page field
types, and the capabilities function the same way for each. Regardless of
using the Entry, Page, or Entry or Page field type, Entries is appended to
access the entry/page context.

There are two ways this can be accessed. The raw string (comma-separated) of
category IDs can be returned with a function tag (<$mt:HeaderCategories$>).
Appending Categories or Folders to the end of the tag name turns it into a
block tag that supports all of the Category (or Folder) tags. For example:

That will generate an unordered listed of categories suitable for a top-level
navigation menu.

The following template variables are set:

__first__ True only if the current category is the first.

__last__ True only if the current category is the last.

__odd__ True only if the current iteration of the category loop is odd.

__even__ True only if the current iteration of the category loop is even.

__index__ Returns the current index of the category loop.

__size__ Returns the number of categories.

This loop also supports the "glue" attribute. The value of this attribute, if
set, will be put at the end of every iteration of the loop until the very last
iteration. It functions identically to the "glue" attribute provided by core
template tags.

For each option of type link-group that is defined, two template tags are
defined. The first is the one specified by the user using the tag parameter
associated with the option in the config.yaml. This template tag will be
useless to most users as it will return a JSON encoded data structure
containing all the links entered by the user.

The second template tag is the useful one. It is called <TAGNAME>Links. This
template tag is a container or block tag that loops over each of the links
entered by the user. Inside each iteration of the loop the following template
variables are defined for you:

For each option of type text-group that is defined, two template tags are
defined. The first is the one specified by the user using the tag parameter
associated with the option in the config.yaml. This template tag will be
useless to most users as it will return a JSON encoded data structure
containing all the links entered by the user.

The second template tag is the useful one. It is called <TAGNAME>Items. This
template tag is a container or block tag that loops over each of the links
entered by the user. Inside each iteration of the loop the following template
variables are defined for you:

For each option of type asset and file that is defined, two template tags
are defined. The first is the one specified by the user using the tag
parameter associated with the option in the config.yaml. This template tag
will return the Asset ID of the asset created for you.

The second template tag is <TAGNAME>Asset. This template tag is a container
or block tag that adds the uploaded asset to the current context allowing you
to use all of the asset related template tags in conjunction with the uploaded
file. For example, look at this config.yaml:

The file type allows theme admins to upload files via their Theme Options
screen. The file, or files, uploaded get imported into the system's asset
manager. The path where the uploaded file will be stored can be customized via
the destination field option.

Allowable file format tokens:

%e - Will generate a random string of characters. The default length of
the string is 8, but can be customized using the following syntax, %{n}e
where "n" is an integer representing the length of the string.

If you specify the scope Field Property as in the example below, the file
path will be written to the local blog, not the Theme's support directory.
This can be helpful to separate files on a blog-by-blog basis.

The radio-image type supports a special syntax for the values attribute
which allows you to associate an image with each choice:

values: "IMGRELPATH":"LABEL", "IMGRELPATH2":"LABEL2"

In the above, each IMGRELPATH represents the path to an image relative to
Movable Type's mt-static directory and each LABEL is the accompanying label
for the option. The path and label are separated by a colon and each combined
value is separated by a comma.

For example, radio-images defining a homepage layout for a plugin Foo
might look like this:

Sometimes however you need to use checkboxes to allow the user to select
multiple options that all relate to one another. Here is an example of how to
use this field to allow users to specify which areas of a site should have ads
enabled:

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 conditional block element. Here
are two example fields:

If you've installed many plugins, you know that you must often move static
content to a separate folder under [MT Home]/mt-static/plugins/. This often
confuses new users and is an annoyance to experienced users. Hence, we added a
feature to Config Assistant to eliminate the hassle.

To enable this feature in your plugin, put all of your static content into a
folder named static inside of your plugin envelope. As you can see below,
you can assemble your static content in whatever folder hierarchy you wish.

When a user first installs a plugin or theme using the static_version key or
installs an upgrade with a higher static_version value, Config Assistant
will recognize it and trigger MT/Melody's upgrade process during which it
deploys the contents of the static folder into a folder under
mt-static/support.

Of course, this relies on proper permissions being set on the
mt-static/support/ folder, but both Melody and Movable Type use this folder
as well and issue warnings if it is not writeable by the webserver. (Note:
This is the reason Config Assistant switched to using this path instead of the
more traditional mt-static/plugins/*)

During the course of development or general use, developers and admins may
force a resynchronization of the static files by running the static copy
utility, addons/ConfigAssistant.pack/tools/static-copy. If you wish, you can
symlink or even copy it to your MT_HOME/tools for easier access.

Future versions of Config Assistant will likely contain enhanced features
which auto-detect changes to static content making this completely
unnecessary.

You'll note that in the sections above, we omitted details about the exact
location of the deployed static content but simply said it's somewhere
underneath mt-static/support. This was completely intentional as Config
Assistant provides you with a better way to access the static content in
templates and plugin code.

In templates, you can use either of the two following tags:

mt:PluginStaticWebPath - Analog to mt:StaticWebPath, this generates a
URL pointing to the folder containing static content for a plugin specified
by the component attribute. Example:

mt:PluginStaticFilePath - Analog to mt:StaticFilePath, this generates an
absolute file path to the same which is useful for server-side includes or
other server-based access. (IMPORTANT: For security reasons, it's best
not to surface details about a user's filesystem to the site's visitors.
Please use this wisely.**). Example:

For the most part, admins never interact with this plugin directly. All an
admin needs to do is re-apply their theme or reset their templates, and if the
theme they apply supports this plugin and this plugin is installed, then the
blog's preferences will automagically be setup. If a new blog is created with
a theme that includes preferences and setting, the blog's preferences will
automagically be setup.

Alternatively, visit Preferences > Chooser in a blog to assign a set of
preferences and settings to that blog.

Developers and designers can use this plugin to automatically apply a set of
blog preferences to a blog when a user resets their blog templates. The format
for specifying these preferences is as following:

First, within your config.yaml, you need to define a preferences group. Each
preferences group has a unique identifier (corresponding to the group's
registry key). Then provide some additional descriptive meta data about the
preferences group and finally provide a list of all the preferences you want
to set. For example:

Note: This will only configure blog level plugin settings. System level
settings for plugins must be configured manually. This seems like a reasonable
restriction to keep plugins from obliterating configs inadvertently.

allow_comment_html (default: 1) - Allow HTML to be used within comments.

allow_commenter_regist (default: 1) - Allow visitors to register for new
accounts from the sign in screen.

allow_comments_default (default: 1) - Turn on comments by default for new
entries.

allow_pings (default: 1) - Global toggle for TrackBacks.

allow_pings_default (default: 1) - Turn on TrackBacks by default for new
entries.

allow_reg_comments (default: 1) - Global toggle for comments.

allow_unreg_comments (default: 0) -

archive_type (default: '') -

archive_type_preferred (default: '') -

autodiscover_links (default: 0) -

autolink_urls (default: 1) -

basename_limit (default: 100) -

captcha_provider (default: null) -

cc_license (default: null) -

commenter_authenticators (default: ) - Determines which authentication
options are enabled by default. The value of this property should be a comma
delimited list of acceptable values. Acceptable values are:

Plugin developers may wish to use Config Assistant to make it easy for users
to specific config options for their plugin. These options are traditionally
set under the Plugin Preferences area of Melody or the Tools > Plugins area in
Movable Type. For options defined in this way, developers may then need to
access the stored option value using Perl inside of their plugin. Let's look
at how to do this using the MT::PluginData class.

First let's look at a config.yaml. It is important to note that one can define
an options registry key outside the context of a template set. When you do
this, you are creating theme agnostic options. The following is an excerpt
from the Photo Gallery plugin for Movable Type:

Config Assistant supports a number of callbacks to give developers the ability
to respond to specific change events for options at a theme and plugin level.
All of these callbacks are in the options_change callback family.

Config Assistant defines a callback which can be triggered when a specific
theme option changes value or when any theme option changes value. To register
a callback for a specific theme option, you would use the following syntax:

Note: The callback is invoked after the new value has been inserted into
the config hash, but prior to the hash being saved. This gives developers the
opportunity to change the value of the config value one last time before being
committed to the database.**

Config Assistant has the ability to trigger a callback when any option within
a plugin changes. To register a callback of this nature you would use the
following syntax, replacing <plugin_id> with your plugin's id attribute
value and <handler> with a typical handler reference:

When the callback is invoked, it will be invoked with the following input
parameters:

$cb - The MT::Callback object for the current callback.

$app - An object instance for the currently running app, most likely, but
not necessarily, an MT::App subclass.

$plugin - A reference to the plugin object that was changed

FIXME: Does $plugin refer to an MT::Plugin or MT::PluginSettings
object? The former is unnecessary as you can get the same thing from
$cb->plugin. It seems like we should be passing the full options hashref as
well as a "changed values" hashref.

If you know that you've encountered a bug in the plugin or you have a request
for a feature you'd like to see, you can file a ticket in the Config
Assistant project in our issue tracking system and we'll get to
it as soon as possible.