Skip to content

Ref ThemeConfigGlossary

Jump to bottom Edit New page
Hiranyaloka edited this page Jul 12, 2011 · 2 revisions

Theme config.yaml Glossary

The following is a reference manual for all the elements that can be contained by a theme's config.yaml file.

Theme

  • Element name: theme ID
  • Parent Element: template_sets
  • Properties:
    • base_path - The path, relative to the directory where the theme's config.yaml file is located, where this themes templates can be found.
    • label - The name of the theme as it will appear to the user inside the Melody CMS.
    • options - A collection of all the options related to this theme. complex type
    • order - The sort order of the theme relative to other themes in the install. It is recommended to leave this blank.
    • templates - A listing of all the templates belonging to this theme. complex type

Example

template_sets:
  theme_id:
    label: 'My Theme'
    base_path: templates/theme_id
    order: 101

Templates

  • Element name: templates
  • Parent Element: theme ID
  • Properties:
    • index - A list of all of the index templates in this theme. complex type
    • individual - A list of all of the individual archive templates and their mappings in this theme. complex type
    • module - A list of all of the template modules associated with this theme. complex type
    • system - A list of all of the system templates associated with this theme. complex type
    • widget - A list of all of the widgets associated with this theme. complex type
    • widgetset - A list of all of the widget sets associated with this theme. complex type

Example

templates:
  templates:
    index:
      main_index:
        label: "Main Index"
    module:
      header:
        label: "Blog Header"
      footer:
        label: "Blog Footer"

Index Templates

An index template has the following properties:

  • Element name: template ID
  • Parent Element: index
  • Properties:
    • label - The display name of the template.
    • outfile - The filename to which this template will output its contents. The filename can also include path information relative to the current blog's site path.
    • rebuild_me - A boolean value (1 or 0) indicating whether a template should be rebuilt when a new comment or entry is created. Obsolete: please use build_type instead.
    • build_type - An integer identifying when and how a template should be published. See MTDG: Build Types.

Archive Mappings

  • Element name: map id
  • Parent Element: mappings
  • Properties:
    • archive_type - One of several allowable strings that identifys the kind and frequency of the archive this mapping refers to. See "Archive Types."
    • build_type - An integer identifying when and how a template under this mapping should be published. See "Build Types" above.
    • file_template - A string identifying the output file and folder naming convention that will be used when publishing files under this mapping. e.g. /2009/12/15/basename.html or /category-name/basename/index.html.
    • preferred - Determines if the mapping under this template is the "preferred" archive to link to when constructing links via the Melody Templating Language. For example, if a theme publishes two entry archives per post, one in HTML and the other in RSS, then what URL should Melody use when processing the tag <$mt:EntryPermalink$>? The answer of course is which ever mapping has been flagged as "preferred."

Individual Archives

  • Element name: template ID
  • Parent Element: templates
  • Properties:
    • label - The display name of the template.
    • mappings - A list of all of the archive mappings associated with this template. complex type

Supported Archive Mapping Types

When declaring the archive type in a mapping bound to an individual archive template, only the following archive types are supported:

  • Individual - for use with entries.
  • Page - for use with pages.

Example

Here is an example of a config.yaml that declares two different individual archive templates, one for entries and the other for pages.

templates:
  index:
    main_index:
      label: Main Index
  individual:
    permalink:
      label: Entry
      mappings:
        individual:
          archive_type: Individual
          file_template: %y/%m/%-f
          preferred: 1
    page_content:
      label: Page
      mappings:
        page:
          archive_type: Page
          file_template: %-c/%-f
          preferred: 1

Date-based, Category and Author Archives

Generic archive template definitions are virtually identical to individual archive template definitions. Here are their properties:

  • Element name: template ID
  • Parent Element: templates
  • Properties:
    • label - The display name of the template.
    • mappings - A list of all of the archive mappings associated with this template. complex type

The only real difference lies in what archive types are permissible within the archive mapping declaration. Here is a list of allowable archive mapping types:

Allowable Archive Mapping Types

  • Daily
  • Weekly
  • Monthly
  • Yearly
  • Author
  • Author Daily
  • Author Weekly
  • Author Monthly
  • Author Yearly
  • Category
  • Category Daily
  • Category Weekly
  • Category Monthly
  • Category Yearly

Example

Here is an example of a single archive template called "Entry Listing" which is being used to produced to different types of archives, one for categories and one for every month:

archive:
  entry_listing:
    label: 'Entry Listing'
    mappings:
      by-category:
        archive_type: Category
      by-month:
        archive_type: Monthly

Template Modules

  • Element name: template ID
  • Parent Element: module
  • Properties:
    • label - The display name of the template module.
    • cache - The caching preferences for this module. See "Module and Widget Caching Options". complex type
    • include_with_ssi - The option presumes that Server Side Includes have been enabled for the blog in question.

Example

  module:
    sitemap_mod:
      label: 'Sitemap Include'
      include_with_ssi: 1
      cache:
        expire_type: 1
        expire_interval: 60

Widgets

  • Element name: template ID
  • Parent Element: widget
  • Properties:
    • label - The display name of the template module.
    • cache - The caching preferences for this module. See "Module and Widget Caching Options". complex type
    • include_with_ssi - The option presumes that Server Side Includes have been enabled for the blog in question.

Example

  widget:
    w_learn_more:
      label: 'Learn More'
    w_photo_of_the_day:
      label: 'Photo of the Day'

Template Module/Widget Caching

  • Element name: cache
  • Parent Element: template id
  • Properties:
    • expire_type - An integer signifying what will trigger the cache to be flushed, e.g. a time-based cache or event based cache. See "Expiration Types and Intervals" below.
    • expire_interval - The time to live for the cache, as expressed in minutes. Only applicable when expire_type is set to 1.
    • expire_event - A comma delimited list of the events that will trigger this module's cache to be flushed. See "Expiration Event Types" below.

Expiration Types and Intervals

  • 1 - Expire the cache after a period of time.
  • 2 - Expire the cache upon a specific event.

Expiration Event Types

Users can select from among the following to determine when a module's cache will be flushed. Each of the options below refers to an object type (Author, Entry, TrackBack, etc) that when created, updated or deleted will trigger the cache to be flushed.

  • asset
  • author
  • category
  • comment
  • entry
  • folder
  • page
  • tbping

Widget Sets

Its properties are:

  • Element name: widgetset id
  • Parent Element: widgetset
  • Properties:
    • label - The name of the widget set as it will appear in Melody's user interface and how a designer will reference it via the <$mt:WidgetSet$> template tag.
    • widgets - An ordered list of widget names that will comprise the sidebar. Each name listed should have a corresponding widget with the same defined within the widget section of the corresponding template sets configuration.

Example

  widgetset:
    homepage:
      label: "Homepage Sidebar"
      widgets:
         - 'Search Box'
         - 'Advertisement'
         - 'Recent Comments'
         - 'Popular Entries'

 


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