Skip to content

designguide theme options

Jump to bottom Edit New page
mikert edited this page Feb 14, 2011 · 2 revisions

MTDG: Theme Options

Melody offers designers with a simple way of surfaces users of their themes with an options pane within the CMS that gives their users the means to configure and customize their theme without ever having to edit HTML, Melody template code, CSS or the like. It is the preferred mechanism by most designers to give their users who have very little technical knowledge a great deal of control over their website in prescribed ways.

Furthermore, these options are defined strictly through a configuration file. There is no knowledge of Perl, no knowledge of PHP, no knowledge of a programming language of any kind required to be able to surface to your users a wide variety of controls for their website.

When a theme defines options for itself, a menu item called "Theme Options" will automatically appear under Melody's Design menu. Selecting that menu item will take the user to a dashboard listing all of the theme's options grouped nicely into sections for ease of use and organization.

Here is a sample config.yaml which declares a theme called "We Love Melody." In this theme we expose three options:

  1. A place for a user to enter their "Feedburner ID."
  2. A place for a user to toggle the use of Feedburner on and off.
  3. A place for a user to enter how many entries they wish to appear on the front door.

In addition, this hypothetical theme defines three template tags for the designer to access the values entered by the user. Again, this is done automatically for you without any need to know or learn a programming language.

id: DemoThemePlugin
name: My Theme Demo
template_sets:
  melody_rocks:
    label: "We Love Melody"
    options:
      fieldsets:
        homepage:
          label: 'Homepage Options'
        feed:
          label: 'Feed Options'
      feedburner_id:
        type: text
        label: "Feedburner ID"
        hint: "This is the name of your Feedburner feed."
        tag: 'MyPluginFeedburnerID'
        fieldset: feed
      use_feedburner:
        type: checkbox
        label: "Use Feedburner?"
        tag: 'IfFeedburner?'
        fieldset: feed
      posts_for_frontfoor:
        type: text
        label: "Entries on Frontdoor"
        hint: 'The number of entries to show on the front door.'
        tag: 'FrontdoorEntryCount'
        fieldset: homepage
        condition: > 
          sub { return 1; }

Field Sets

Field sets are a grouping of related options associated with a theme. Field sets provide designers with a simple way of organizing and segmenting fields into different options screens under the "Theme Options" menu item.

  • Element name: fieldsets
  • Parent Element: options
  • Properties:
    • fieldset_id - A list of fieldsets each identified by a unique fieldset ID. Fields will reference this fieldset ID for placement. complex type
      • label - The display name of the fieldset.
      • order - The sort order of the fieldset determining its placement in the navigation between fieldsets.

Fields

Fields represent each individual option you wish to expose to a theme's user or administrator. There is a wide variety of form element types to choose from, e.g. radio buttons, pull down menus, text areas, etc. The types of fields are also extensible so that if you find that there is particular type of field missing, contact a developers, they can create it for you.

Each field definition supports the following properties:

  • Element name: field id
  • Parent Element: options
  • Properties:
    • type - the type of the field. See "Field Types" for a list of supported types and any special syntaxes they support.
    • label - the label to display to the left of the input element
    • show_label - Determines whether or not to display the field's label. In some cases, as with checkboxes, it is desirable to suppress the label. Default: true.
    • 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.
    • 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

Full Documentation

Supported Field Types

Below is a list of field types supported by Melody. APIs exist for developers to extend this list with custom fields/options should the list below not contain the field type you need.

  • 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.

  • select - Produces a pull-down menu or 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

  • checkbox - Produces a single checkbox, ideal for boolean values.

  • blogs - Produces a pull down menu listing every blog in the system. Warning: this is not advisable for large installations as it can dramatically impact performance (negatively).

  • 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.

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

  • entry - Produces a simple button that when clicked will surface a modal dialog in which a user can select an entry to link to. Ideal for selecting a featured story for the homepage.

Example

The following example shows how one would define a theme option of type "Radio Image," or set of radio buttons whose labels are graphical as opposed to text.

The radio-image type supports a special syntax for the values attribute. The list of radio buttons is a comma-delimited list of image/value pairs (delimited by a colon). Got that? The images you reference are all relative to Melody's mt-static directory. Confused? I think a sample will make it perfectly clear:

  homepage_layout:
    type: radio-image
    label: 'Homepage Layout'
    hint: 'The layout for the homepage of your blog.'
    tag: 'HomepageLayout'
    values: >
      "plugins/Foo/layout-1.png":"Layout 1","plugins/Foo/layout-2.png":"Layout 2"

Defining Template Tags

Each individual theme option or field can define a template tag by which a designer or developer can access the value saved by the user.

Tip: If a tag name terminates in a question mark then the system will interpret the tag as a conditional block element, allowing you to use the tag in conjunction with the <mt:Else> tag.

Example

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>

Continue Reading

 

Category: Guide

Tags: theme design


Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.

Credits

  • Author: Byrne Reese
  • Edited by: Violet Bliss Dietz
Add a custom footer
Add a custom sidebar
Clone this wiki locally