Creating your own custom themelet for Morph

In this tutorial we are going to take you through the process of building your own custom themelet to work with the Morph template framework.

Important: Before you go on, its highly recommended that you first read "The anatomy of a themelet".

Joomla templates vs themelets

Firstly, Morph does not create or build templates, rather it is a foundation for you to build upon. Traditionally when you build a Joomla! template, you would need to take your completed design, slice the images and then code the html and css. You would then add in the Joomla! template code and logic.

Using Morph, you actually skip the entire process of building the xhtml/php structure, as that is all included in the framework. If you take a look at a packaged themelet, you will notice that it is made up of images, css and javascript. Essentially the themelet is a graphical layer that sits on top of the Morph Framework.

---

What if I would like to convert a Joomla template into a themelet?

The process of creating a themelet is the same whether you are converting an existing template or starting from a design. The only difference is that when converting a template, all your images would already be sliced and you would have some css that you could work with.

If you haven't already, we recommend that you optimize your existing images before you start. There are some great apps and web based services that you can use to do this. Read more.

---

How easy is it?

This all depends on how familiar you are with technologies used in Morph. For most, a solid understanding of css and Joomla would suffice.

A quick case-study is when Andy converted our Mocha template to a Morph themelet. The basic conversion without refinements took a little over 6 hours. This is extremely impressive considering that the original template took close to a month to build first time round and while it is not yet 100% completed, it is still far more feature rich and comprehensive than the original Mocha template.

The entire process may seem a bit daunting at first, but always keep in mind that help is only a forum post away. We are here to help and there is no such thing as a silly question ;)

---

Creating a custom themelet.

Before we begin, the Morph Framework css and javascript files must never be modified. If you need to override any of the core xhtml output or css, you can do so using overrides. The overrides work much like Joomla's overrides. If there is a core framework css file that you wish to modify, simply add a file with the same name (ie yui.css) to your themelets css folder and Morph will use yours instead.

Step 1: Use the Vanilla themelet as a base

We developed Vanilla to be a solid base that you can use when creating your own custom themelets. The first step in the process is to duplicate the Vanilla themelet and change all the various references to the themelet name.

1.1) Duplicate the Vanilla themelet

Make sure you have Vanilla installed, then duplicate "morph_assets/themelet/vanilla" folder and rename it to the name of your themelet, eg: "your-themelet". All the files you need are contained within this folder.

1.2) Update the themelet information in themeletDetails.xml

Inside your themelet's folder there is a file called themeletDetails.xml. Open this file in your editor of choice and replace all instances of the word Vanilla with the name of your themelet.

Note: if your themelet name is two words, you need to use a dash to separate the words, eg: light-candy for Light Candy.

1.3) Update the image paths in the themelets css

You will also need to update the image path references used throughout the themelets various css files. This can easily be done using a find and replace in the editor of your choice.

Themelet image path before:

background:#fff url(../../../../morph_assets/themelets/vanilla/images/your-image.png);}

Themelet image path after:

background:#fff url(../../../../morph_assets/themelets/yourthemelet/images/your-image.png);}

It's important to mention that the images path should always be set to: ../../../../morph_assets/themelets/vanilla/images/ (replacing the themelet name with your own). This is important, as it ensures that the images work with css packing both on and off.

---

Step 2: Configure your sites structure to fit your design:

Now that you have your themelet base, you can start configuring Morph's various blocks to set a foundation to work on, thus providing you with the necessary hooks that you can use to achieve your themelets layout. You will need to look at your general page layout and the style of the design. Some designs are centered, others are full width, while some may be centered but the background spans across the full width of the browser window. An example of this can be seen on the Morph feature site.

Before you do so, we recommend reading the "Understanding Morph's block options" tutorial, as it covers the various options that are available in each of the different blocks.

Looking at Vanilla, you will notice that it is a fixed width centered layout. By simply adjusting a few settings in Configurator you can drastically change the layout.

Example A: No block wrapping enabled

This first example represents Vanilla's fixed width layout and doesn't have any block wraps enabled.

Example B: Block wrapping enabled

This example shows whats possible with block wrapping enabled. The contents are still centered, but the overall block spans the full width of the page.

What should the overall width be? Does the design use a fixed or fluid layout? Will you be using either of the sidebars? If so, how should they be positioned and what should their widths be? Will you be using any of the four shelves?

Due to the vast number of possible layout combination's that are possible with Morph, we have created an interactive demo to let you try out with the different module positions and block layouts.

---

Step 3: Pulling it all together with css

Now its time to start playing with the css and images. Start from the top block and work your way down the page, adding the css and images for the various elements and features you have included in your layout. For example, if you are using the Topfish menu, then you will need to modify the topnav-topfish.css file to match your color scheme and typography options. Do the same for each of the features that you have added.

---

Step 4: Packaging your themelet

The last step of packaging only applies if you plan on making your themelet installable (ie, on a clients site) in Configurator and is related to the install files naming convention and Configurator defaults.

Setting Configurator defaults via the themelets xml

We have built the system that themelets are able to override the default settings set in Configurator. Any option that is in Configurator can be overridden via the themelets xml.

Themelet install file naming convention

First of all the themelet install zip needs to be named using the following convention "themelet_vanilla_v1.03.zip". Notice how the file name is prefixed with the word "themelet_". This is important, as it tells the Configurator installer that you are installing a themelet.

The second part is your themelets name and again if you themelet name is made up of more than one word, you need to separate them with dashes, eg: "themelet_light-candy_v1.03.zip".

The last bit refers to the themelets version, again sticking to a convention of _v0.00, with each new version incrementing with 1, ie: v0.01, v0.02, etc.

---

Summary

You should now have a themelet that looks like your design. Now you can work on what is unique to your project. Once your site is up and running, send us a link so we can see what masterpieces you have created.