Skip to content

designguide theme templates

Jump to bottom Edit New page
Violet edited this page Dec 6, 2010 · 1 revision

MTDG: Index and Archive Templates

Index and Archive templates are the templates primarily responsible for defining the HTML and thus, look and feel of your website. The primary difference being that index templates output only a single file, and archive templates are used to output numerous files according to a URL pattern you specify. For example, your website only has one homepage. Thus, your homepage is best implemented as an index template that output a single file "index.html". On the other hand, your website will consist of numerous articles, each with a unique URL. But no matter how many articles you write, you only need one archive template to provide Melody with the HTML for all of your site's articles.

Quick Example

Because I know you are anxious to get started, let's begin with a quick example of a theme that defines two templates: a homepage and an article.

templates:
  index:
    main_index:
      label: 'Homepage'
      outfile: 'index.html'
  individual:
    article:
      label: 'Article'
      mappings:
        individual:
          archive_type: Individual
          file_template: %y/%m/%-f
          preferred: 1

And now with that out of the way, let's explain what it means.

Index Templates

Index templates within Melody correspond to those templates that output a single file. Examples of index templates are:

  • Your site's homepage
  • An RSS or Atom feed
  • A Google Sitemap
  • An archive listing
  • and more of course.

An index template can have the following properties:

  • label - The display name of the template.
  • filename - The name of the file that contains the template's contents/HTML. If no filename is specified, than the basename of the template will be used by default.
  • 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.
  • build_type - An integer identifying when and how a template should be published. See MTDG: Build Types.

Looking back at the example from above, let's make some sense of it:

templates:
  index:
    main_index:
      label: 'Homepage'
      outfile: 'index.html'

  1. The "basename" of the template is "index". Because no explicit filename was provided, this is also forms the basis of the filename that will contain the templates contents. So for example, if your base_path was set to my_templates, then the contents of your Main Index template will be found here:

    • plugins/MySuperTheme/my_templates/main_index.mtml

  2. Inside of Melody, in the template listing screen, your main index template will be identified by the label "Homepage."

  3. This template will be processed and output its contents to a file called "index.html". If the publishing path of your blog is "/var/www/html/" then Melody will output the following file for you:

    • /var/www/html/index.html

Archive Templates

Archives provide your visitors with a number of ways to explore, browse and discover new content. Archives are used to group content you have created by a variety of criteria, such as the category they were published in, or the date they were authored, or even a mix of the two (e.g. "show me all of the entries in the 'News' category written in November 2008").

Archives are also used to publish the dedicated page for each entry or page, also known as the permalink page, where comments are published and readers are invited to submit their own.

Once you have created your template, the key factor in determining the kind of archive you are creating is in the archive mapping. An "archive mapping" is responsible for defining two key elements for an archive template:

  • The type of archive the template will produce (category vs. author vs monthly for example).
  • The pattern that will be used in deriving a URL for any given page produced by the archive.

Before we dive into the specific archive types, lets get a grapple on archive mappings, because we will be using them with each of the archive types we can publish.

Archive Mappings

While index templates output only one file per template, a single archive template can be responsible for publishing hundreds and thousands of files. Furthermore, a single archive template can be used to publish different types of archives. For example, it is completely reasonable for a designer to use the exact same template logic for presenting a list of entries within a specific category as they would to present a list of entries published in a given month.

Archive mappings give designers the power and flexibility to use and re-use templates to produce a great variety of pages on a website.

Let's look at a quick example, and the delve into a mapping's properties in more detail. Here is an example individual archive template declaration:

  individual:
    a_template_id:
      label: "My Entry Feed"
      mappings:
        my_map_id:
          archive_type: Individual
          file_template: %y/%m/%-f.xml

The above sample declares an individual archive template with an id of a_template_id and a name of "My Entry Feed." It publishes this template once for every entry in the system using a file naming scheme like this:

Year + '/' + Month + '/' + Entry Basename + '.xml'

Tip: you may notice that every mapping is given a unique "map id" the value of which must be unique among the other mappings bound to the same template. Other than that, the map id is effectively ignored by Melody.

Individual Archive Templates

An individual archive template is responsible for publishing a file for each page and/or entry contained within a site powered by Melody. A site can publish multiple individual archives for a given entry, the primary use case being publishing an entry's permalink page in HTML, in addition to an RSS feed for the entry's comments that readers can subscribe to.

Example

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

The example above declares two templates, one for entries and the other for pages. The one used for entries has an id of "permalink" and therefore its contents can be found in the template file called "permalink.mtml" in the template set's base path. The template is named "Entry" and will publish each entry to a page accessible via a URL such as the following:

Date-based, Category and Author Archive Templates

Generic archive template definitions are virtually identical to individual archive template definitions.

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

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