Skip to content

cbtpcasestudy

Jump to bottom Edit New page
Violet edited this page Nov 2, 2010 · 5 revisions

A Case Study on Theme Development of the Classic Blog Theme Pack

Building a Theme

“Themes” are the best way to create and deploy a new site. They are the best way to update a new design on an existing site. They are the best way to share your latest design with the community and make it easy for anyone to use. They're basically a little ball of awesome!

What is a "Theme"?

A theme is a collection of the pieces needed to create and publish a complete blog or website: CSS, Javascript, images, templates, and maybe some configuration options and theme metadata.

All of these pieces are pulled together into a plugin so that your theme can be easily installed. (Yes, you are technically creating a plugin.)

The Classic Blog Theme Pack Reference Example

The Classic Blog Theme Pack includes four themes, based on the old Classic Blog template set that was introduced in Movable Type 4.0. You can find the Classic Blog Theme Pack at http://github.com/danwolfgang/Classic-Blog-Theme-Pack. This Theme Pack serves as a definitive reference and is referred to throughout this document.

What is a "Theme Pack"?

A Theme Pack is just a collection of themes. Yes, several themes can exist within a plugin!

Required Components for a Theme

Folder Structure

Refer to the Classic Blog Theme Pack and you'll see a simple folder structure that holds the contents:

ClassicBlogThemePack/
    static/
        base/
        classic-blog-cityscape/
        classic-blog-hills/
        classic-blog-minimalist/
        classic-blog-unity/
        images/
    templates/

The folder ClassicBlogThemePack is the name of the plugin package, or envelope. When you create your theme, you should name this folder after your theme.

The static folder holds things like your images, icons, CSS, and Javascript.

The templates folder holds the MT-language templates.

Plugin Dependencies

A robust theme will take advantage of the following plugins:

  • Auto Prefs
  • Config Assistant
  • Theme Manager

Those plugins may sound familiar if you're using Melody: they are part of the default installation. In other words, if you're running Melody you don't need to install these. If you want your theme to be used on Movable Type, you'll need to install these plugins.

Those plugins are “core” to a good theme. They will let you build a theme that is easy to use and let you communicate your theme's flexibility with the site administrator.

The Classic Blog Theme Pack also requires the Custom CSS plugin to function. This is a plugin you may choose to use with your Theme to add additional flexibility, but it's up to you.

And of course, there are many other plugins you may want to take advantage of with your theme. Just be sure to document these prerequisites so that users know they are required!

The heart of the Theme: config.yaml

Plugin developers will be familiar with the config.yaml file: it contains the information Melody and Movable Type need to load a plugin or theme. Yes, this file is the start of plugin development, but don't let that scare you: a YAML file is just a text file with a simple hierarchy of keys and values.

config.yaml can easily be broken down into several sections, so lets look at each piece individually. Again, refer to the Classic Blog Theme Pack where you'll find a config.yaml; its contents are discussed below.

Save config.yaml in your plugin's envelope. The "envelope" is simply the containing folder. In this example, it's ClassicBlogThemePack.

ClassicBlogThemePack/
    config.yaml

Related: the Movable Type Developer Guide contains some documentation on config.yaml that you may find useful: an Introduction to Plugins and Plugin Basics: Building Your First Movable Type Plugin.

Basic Structure

There are a few keys and values you'll need to define in order for Melody to recognize your theme as a plugin. Read through the following YAML structure and I bet you'll see a lot of pieces you understand already!

Create and save this chunk of YAML and you'll have the beginnings of your plugin: within Melody or Movable Type, you can visit System Overview > Plugins and find your plugin listed there.

name: 'Classic Blog Theme Pack'
key: ClassicBlogThemePack
id: ClassicBlogThemePack
description: '“Classic Blog” was the original template set included with Movable Type 4.0. This Theme Pack combines the various styles available for the Classic Blog template set, and completely removes the need for the StyleCatcher.'
author_name: 'Dan Wolfgang, uiNNOVATIONS'
author_link: 'http://uinnovations.com'
version: 1.0.3
static_version: 4
  • name is the name of your plugin. This may be the same as the name of your theme. Remember that the Classic Blog Theme Pack contains four themes, and so I decided to give the plugin a different name than the individual themes.
  • key and id are both used programmatically within Melody. They need to be names with no spaces. (Technically, you don't need to specify either of these values because Melody will generate the as necessary. I like to specify them myself, however, just so that I know what they are. This is more important for plugin development than theme development, but it's a good practice to just supply the key and id.
  • description is a pretty self-explanatory value. Again, note that you may use a description of your theme here, or this may be a unique description as it is for this Theme Pack.
  • author_name is a chance for you to give some credit to yourself!
  • author_link is a fully-qualified URL. This is linked to the author_name text.
  • version is an arbitrary version number you can create for your plugin. Specifying a version number is helpful because it's an easy way for users to know what version of the theme they are using, and to let users know that a newer version of your theme is available to them.
  • static_version is an important key to help automate the installation of your theme. You'll be placing "static" content like images and Javascript in a static/ folder, and this static_version key will cause the content to be copied to the final destination. The static_version key and the static/ folder will be discussed in greater depth later in this doc. For the moment, however, just understand that you'll want to specify an integer here (1, 2, 3, etc) and that you can increment this number whenever you want to trigger a theme upgrade. (This option is making use of a feature in the Config Assistant plugin.)

At this point, you've technically created a plugin. It doesn't actually do anything yet, but Melody will load it. You're well on your way to building a theme!

More about YAML and Keys and Values

Within config.yaml you are going to specify a lot of data in a simple "key: value" format. While the format is simple, it's powerful and can get complex. So, here's a quick overview of some of the things that you will need to know:

  • Indenting matters. Be sure to indent everything correctly to create the right hierarchy. You'll see plenty of examples of this throughout this tutorial.
  • In a "key:value" pair, the key is the thing on the left. Keys should be alpha-numeric values (A-Z, 0-9); underscores can be used. Spaces are not allowed, and neither are other characters like "," or "-".
  • In a "key:value" pair, the value is the thing on the right. Values can be a number, word, sentence, file name, etc. You should get into the habit of quoting the value when its more than one word.

YAML does so much more. We'll touch on a few points throughout this, but for comprehensive information you should refer to the spec.

YAML Errors

A common error you may run into is

Got an error: Error reading ... Stream does not end with newline character ...

YAML is a little picky about the end of the file: there must be a new line at the end. That's it: just hit enter one more time at the end of your config.yaml to create one last blank line.

Adding a Template Set to config.yaml

Now that you've got the basic framework of a plugin created, it's time to start adding the pieces to make a functional theme. You'll use the template_sets key to start building an outline-style set of definitions about your theme.

Details about your theme will help make it easy for the user to work with your theme. Notice the indented structure being created here -- that's very important to make Melody interpret this information correctly. The indents are representative of a structure: classic_blog_minimalist is a part of template_sets, for example.

template_sets:
    classic_blog_minimalist:
        base_path: templates
        label: 'Classic Blog, Minimalist'
        description: '“Classic Blog” was the original template set included with Movable Type 4.0. “Minimalist” comes in several colors (blue, brown, green, grey, light blue, light green, pink, purple, red, and white) and page layouts.'
        author_name: 'Lilia Ahner'
        author_link: 'http://lilia.vox.com'
        documentation: docs.html
        blog_preferences: classic_blog_preferences
        preview: 'classic-blog-minimalist/preview.jpg'
        thumbnail: 'classic-blog-minimalist/thumbnail.jpg'

Perhaps the most important key defined in the above structure is classic_blog_minimalist. This is the ID of your template set. This can be almost any value you choose, but be sure it's descriptive of your theme! Be sure to use a clear and descriptive ID for your blog: theme is uninformative and unclear, for example, while a name like melody_colorburst_theme is much more descriptive and unique. You can publish this value with the template tag <mt:BlogTemplateSetID>. Note: do not make your template set ID the same as your plugin ID.

Theme Metadata

You can see that the classic_blog_minimalist template set has several values to describe it. Each are explained below.

  • base_path indicates where the themes templates can be found. This theme has placed them in the templates folder. Refer to your plugin envelope and you'll see a templates folder inside of it--that's this folder!
  • label is the user-facing name of this theme. It's the name you use for this theme when you're bragging about your great work.
  • description should also be clear (and familiar at this point)! If the theme description is not specified, the plugin description will be displayed. Notice that in the Classic Blog Theme Pack--with its four themes--different descriptions were required for each theme, so I made sure to specify the description for each theme.
  • The author_name and author_link fields will also fall back to the plugin values previously set. These values only need to be set at the theme level if they need to be different. Again, the Classic Blog Theme Pack has four themes in it, by different designers. Because I wanted to be sure that each designer got the credit they deserve, I specified these values for each theme.

 


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

Credits

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