Skip to content

designguide theme basics

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

MTDG: The Basics: Building Your First Theme

To illustrate how one would begin with the process of creating a theme, let's walk through a sequence of commands that will stub out the basic structure of a plugin.

The examples below show the commands one would enter on the command line. Of course, knowing how to hack a command line is not necessary. All we are doing below is creating folders (or directories) and files. You can do that using Windows Explorer or Mac Finder.

  1. Let's set the current working directory to our home directory:

     prompt> cd ~

  2. Now, create the base directory for your theme and then make it your current working directory.

     prompt> mkdir MySuperTheme
 prompt> cd MySuperTheme

  3. Create the paths you will need for theme's program files and templates.

     prompt> mkdir plugins
 prompt> mkdir plugins/MySuperTheme
 prompt> mkdir plugins/MySuperTheme/templates

    Tip: As a short-hand one can use the mkdir -p command to recursively create a set of directories if they don't exist.

  4. Create the paths you will need for the theme's static files:

     prompt> mkdir -p plugins/MySuperTheme/static

  5. Create some of the key files your theme will almost certainly rely upon:

     prompt> touch plugins/MySuperTheme/static/styles.css
 prompt> touch plugins/MySuperTheme/config.yaml
 prompt> touch plugins/MySuperTheme/templates/main_index.mtml

    Tip: The touch command in Unix systems simply creates an empty file using the designated file name.

    At this point you should have built out a really simple file and folder structure. One that contains a number of folders and sub-folders, exactly three files and looks something like this:

    • MySuperTheme/plugins/MySuperTheme/config.yaml
    • MySuperTheme/plugins/MySuperTheme/static/styles.css
    • MySuperTheme/plugins/MySuperTheme/templates/main_index.mtml

  6. Give your main index template some content to display. Let us also reference within it the CSS stylesheet you created so that you can properly style your theme's homepage. Edit main_index.mtml in your templates directory and enter this content:

     <html>
 <head>
   <title><$mt:BlogName$> - Hello World</title>
   <link rel="stylesheet" type="text/css" 
      href="<$mt:PluginStaticWebPath component="MySuperTheme"$>styles.css" />
 </head>
 <body>
   <p>Hello World.</p>
 </body>
 </html>

  7. Next, let's create the plugin's configuration file which effectively registers the theme we are creating with Melody, and populate it with the very minimal amount of information. Edit your config.yaml and then cut and paste this into it:

     id: MySuperTheme
 name: "My Super Theme"
 description: "A demo theme from the documentation."
 author_name: Byrne Reese
 author_link: http://www.majordojo.com/
 version: 1.0

    The above defines the very basics for your plugin. Make sure that it's left-aligned in column 1 or the farthest left column that you decide to use.

  8. Finally, let's register and associate the main index template you created above within your theme's configuration file. This final step is what will give users the ability to select and apply your theme to their website or blog. Edit your config.yaml file again, and cut and paste the following at the end of that file:

     template_sets:
   my_super_theme:
     label: "Blog Theme (My Super Theme)"
     base_path: templates
     templates:
       index:
         main_index:
           label: "Main Index"
           outfile: "index.html"

The code above registers a theme with Melody called "Blog Theme (My Super Theme)" with an theme ID of my_super_theme. This theme ID must be unique within a user's installation. No other theme can bear the same ID. Make sure that the term template_sets is left-aligned in column 1 or the same farthest left column that you used for the id, name, description, etc.

The code above also points Melody to the path on the file system where it can find all of the templates associated with this theme. The path specified is relative to the directory containing the config.yaml file.

Finally, the code above associates a single template with the theme called "Main Index." The template is an "index" template and has an ID of main_index. The template's ID also happens to correspond to the file name of the template where Melody will find the template code for this template. Alternatively the file name can be stated explicitly like so:

templates:
  index:
    main_index:
      label: "Main Index"
      filename: "homepage.mtml"
      outfile: "index.html"

Therefore the path to a template can be determined one of two ways:

  • Derived: <base_path>/<template id>.mtml
  • Explicit: <base_path>/<filename>

And there you have it - your very first theme. Now all you have to do is check it into source control (ahem, github, cough), and install it into your Melody install. Or if you have no idea what I just said, skip it. We'll come back to that later.

Once it is installed, then you can apply your theme to any new or existing blog. In that process Melody will read your configuration file, install all relevant templates, setup your theme options and more.

Continue Reading

 


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

Credits

  • Author: Six Apart Ltd., Byrne Reese
  • Edited by: Violet Bliss Dietz
Add a custom footer
Add a custom sidebar
Clone this wiki locally