Home > Theme Design > Tutorial
login

© Metadot Corporation

Create a new theme from scratch  

Your site comes with some preselected theme which you could modify to fit your needs. But sometimes you may want to build a theme from scratch. This tutorial will help you to do that.

Create a blank theme  

To create a blank theme follow these simple steps:

    1. Go to your "Themes" screen, find the link "create a blank theme" and click on it - the dialog will be opened

    2. Choose some non-existed name (for example "my theme") and click "create" button

    3. "my theme" will appear in your saved theme list ready to be edited

    4. Go to edit "my theme" by clicking on its edit link

    5. You have a pretty empty theme ready to be filled with content.

Copy the layout skeleton  

Now you should start filling your theme with content.

    1. Click edit link of your empty theme to go to the theme edit screen.

    2. Click on main layout link (located at the right) to load the edit fields for the layout.

    3. Copy the basic layout structure described here and paste it in the editing area of the main layout.

Here what we have as layout content:

<html>
<head>

<!-- your meta tags would be here -->

{{page | js_and_css}}

<!-- your css and javascript tags would be here -->

</head>
<body {{page | body_attrs}}>
{{page | edit_bar }}

<!-- your html should be here -->

{{page.load_gizmos}}
</body>
</html>

Of course this is just the very basic skeleton of the layout which we have to fill with "flesh".

Let start filling the comments from the top to the bottom. 

Edit Page Head  

    1. Remove the comment "<!-- your meta tags would be here -->".

    2. Add page title:<title>{{site.name}} - {{page.title}}</title>This will show the site name and page title in the browser title bar. "site" and "page" are liquid objects used to render the page content. More about liquid syntax can be found here . Information about the liquid objects and their properties can be found in Variable reference section of this wiki.

    3. Add meta tags:

<meta name="Description" content="{{page.meta_description}}" />
<meta name="Keywords" content="{{page.meta_keyword}}" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
It is always good these two tags to be present in your pages, so search engines could more appropriate place your page in their indexes and people could find them easier. Use simple language for the description and keywords that match the content of the page. 

The page head section will look like this:
<head>
   <title>{{site.name}} - {{page.title}}</title>
    <meta name="Description" content="{{page.meta_description}}" />
    <meta name="Keywords" content="{{page.meta_keyword}}" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

   
   {{page | js_and_css}}
   
   <!-- your css and javascript tags would be here -->
</head>

Let skip for a while the comment "<!-- your css and javascript tags would be here -->" and continue with filling the body of the page.

Edit Page Body  

<body> tag

You may notice using of two special liquid tags in the body tag and immediately after it:

<body {{page | body_attrs}}>
{{page | edit_bar}}
The first liquid tag "{{page | body_attrs}}" is needed in case the page is in edit mode - it generates onmouse and onclick handlers. The second tag "{{page | edit_bar }}" generates the code and html for the edit bar you will use when page is in edit mode. The both tags are mandatory and should be present in your theme layouts at these places.

 

Using tables 

Lets say we want to have a page with two columns - one main and wider and one optional and narrowed. We have to use tables in which cells we will place the gizmo areas - the future containers of our gizmos. Here is a simple example:

<table  width="100%">
    <tr>
        <td width="80%">{{1 | gizmo_area}}</td>
        <td width="20%">{{2 | gizmo_area}}</td>
    </tr>
</table>

"{{1 | gizmo_area}}" and "{{2 | gizmo_area}}" are the liquid tags we will use to place gizmo containers (areas) in the page. The number represent the gizmo area number and should start always from "1". You can add up to 7 different gizmo areas in one page. The gizmos in one gizmo area are placed one below another as the order could be changed anytime you want using drag&drop functionality - you can even move gizmos between the gizmo areas very easily. Lets return back to our layout body. What we have now is a page with 2 columns - one that filled 80% of the page and another - 20%. You may change the table width if you want, but remember - the gizmo areas should be placed inside a table cell (td element) to work properly.

At this moment the main layout content looks like this:

<html>
<head>

    <title>{{site.name}} - {{page.title}}</title>
    <meta name="Description" content="{{page.meta_description}}" />
    <meta name="Keywords" content="{{page.meta_keyword}}" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

    {{page | js_and_css}}

    <!-- your css and javascript tags would be here -->

</head>
<body {{page | body_attrs}}>
{{page | edit_bar }}

<table width="100%">
<tr>
    <td width="80%">{{1 | gizmo_area}}</td>
    <td width="20%">{{2 | gizmo_area}}</td>
</tr>
</table>

{{page.load_gizmos}}
</body>
</html>

 

Preview the layout

Its time to take a look what we have done so far. Click "save" and be sure the layout is saved and then click on the link "preview" right next to the "main layout" link. It will open a new window with preview of your site first page rendered with the layout you just saved.

But where is the navigation menu, where is the login menu? Lets add them!

 

Navigation and login menus 

<table width="100%">
<tr>
    <td colspan="2" align="right">{{page.login_menu}}</td>
</tr>
<tr>
    <td colspan="2"><div id="main-menu">{{page.global_nav}}</div></td>
</tr>

<tr>
    <td width="80%">{{1 | gizmo_area}}</td>
    <td width="20%">{{2 | gizmo_area}}</td>
</tr>
</table>

Click save and then preview. The login menu looks OK, but that navigation menu is strange - should it be horizontal with no bullets? It seems we should write some css.

 

Add CSS 

We have two options - to write inline css directly in our layout using <style> tag or to write it in a separate file, which will be referenced in our layout as css resource (<link> tag). Lets choose the second way. We have to create the css file and upload it as a theme asset. Use your preferred text/css editor and create a file "my.css" with the following content:

#main-menu ul {
    list-style: none;
    margin: 0;
    padding: 0;
}
#main-menu ul li {
    float: left;
    padding-right: 10px;
}

Save the file and go back to edit theme screen, click on "upload asset" button and from the shown form browse and select your "my.css" file and click "save". That will upload and add your file as a theme asset with a name "my.css" which you could use in your layout. How we will do that? Lets return to the head section, when we skipped for a while the comment "<!-- your css and javascript tags would be here -->". Now is time to add the css to the layout. Here is how will look the layout's head section:

<head>

<title>{{site.name}} - {{page.title}}</title>
<meta name="Description" content="{{page.meta_description}}" />
<meta name="Keywords" content="{{page.meta_keyword}}" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

{{page | js_and_css}}

{{ 'my.css' | stylesheet }}

</head>
Notice the line with liquid tag for the css? Its that simple - just use the same name as your uploaded css file. Now click "save" and "preview" again - it looks better now isn't it?

 

Add local navigation menu 

The navigation menu is built using the property "global_nav" of the liquid object "page". This will show only the main page link and the list of the links to the first level pages (which are created as direct sub-pages of the main page). But what about pages that are sub-pages of that first level pages, and what about their sub-pages and so on? How could we show the sub-pages of any page? Easy - just use the property "local_nav" instead of "global_nav" or we may use them both doing something like that:

...
<tr>
    <td colspan="2"><div id="main-menu">{{page.global_nav}}</div></td>
</tr>
<tr>
    <td width="80%">{{1 | gizmo_area}}</td>
    <td width="20%"><h2>Navigation</h2>{{page.local_nav}}<hr>{{2 | gizmo_area}}</td>
</tr>
...

 

Add breadcrumb 

Using local_nav could not give us the clear picture where in the site tree we are when browsing the site pages. For the big sites with deep hierarchy of pages it is very important to have a way for quick return to some page of the hierarchy. The way to do it is to provide the full path to the current page with links to all parent pages. You can easily add such a path to your pages by using the page property "breadcrumb":

...
<tr>
    <td colspan="2"><div id="main-menu">{{page.global_nav}}</div></td>
</tr>
<tr>
    <td colspan="2">{{page.breadcrumb}}</td>
</tr>
<tr>
    <td width="80%">{{1 | gizmo_area}}</td>
    <td width="20%"><h2>Navigation</h2>{{page.local_nav}}<hr>{{2 | gizmo_area}}</td>
</tr>
...

Isn't it cool? By default the breadcrumb separator is "::", so if you want to change it you may use the functions "gt" or "lt" which will change the separator to ">" or "<". Lets change it to ">" and see what we have so far in the main layout:

<html>
<head>
    <title>{{site.name}} - {{page.title}}</title>
    <meta name="Description" content="{{page.meta_description}}" />
    <meta name="Keywords" content="{{page.meta_keyword}}" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

    {{page | js_and_css}}

    {{ 'my.css' | stylesheet }}

</head>
<body {{page | body_attrs}}>
{{page | edit_bar }}

<table width="100%">
<tr>
    <td colspan="2" align="right">{{page.login_menu}}</td>
</tr>
<tr>
    <td colspan="2"><div id="main-menu">{{page.global_nav}}</div></td>
</tr>
<tr>
    <td colspan="2">{{page.breadcrumb | gt}}</td>
</tr>
<tr>
    <td width="80%">{{1 | gizmo_area}}</td>
    <td width="20%"><h2>Navigation</h2>{{page.local_nav}}<hr>{{2 | gizmo_area}}</td>
</tr>
</table>

{{page.load_gizmos}}
</body>
</html>

 

Add site name and site tagline 

Now we want to add the site name on each page together with the site tagline. Lets add them just above the main menu:

...
<tr>
    <td colspan="2" align="right">{{page.login_menu}}</td>
</tr>
<tr>
    <td colspan="2"><div id="site-title"><h1>{{site.name}}</h1>{{site.tagline}}</div></td>
</tr>

<tr>
    <td colspan="2"><div id="main-menu">{{page.global_nav}}</div></td>
</tr>
...

 

Using if/else statement 

We may use liquid "if/else" tags as well. For example we may want to show the 'Navigation" label and horizontal line (<hr> tag) only when there is a local navigation items for the current page:

...
<tr>
    <td colspan="2">{{page.breadcrumb}}</td>
</tr>
<tr>
    <td width="80%">{{1 | gizmo_area}}</td>
    <td width="20%">
    {% if page.has_local_nav %}
         <h2>Navigation</h2>{{page.local_nav}}<hr>
     {% endif %}

       {{2 | gizmo_area}}
    </td>
</tr>
...

More about if/else statement can be found here

Add message container 

We shall add the place where the system messages will appear, otherwise the user will not see any of them while browsing your pages. The messages are often related to the results of different operations (create new page, edit gizmo, etc.)  where appropriate message is always welcome. Lets place it just above the gizmo area 1:

...
<tr>
    <td colspan="2">{{page.breadcrumb}}{{ "" | message }}</td>
</tr>
<tr>
    <td width="80%">
        {{1 | gizmo_area}}
    </td>
...

 

And... thats it!

We finished with a very basic theme layout:

<html>
<head>

    <title>{{site.name}} - {{page.title}}</title>
    <meta name="Description" content="{{page.meta_description}}" />
    <meta name="Keywords" content="{{page.meta_keyword}}" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

    {{page | js_and_css}}

    {{ 'my.css' | stylesheet }}

</head>
<body {{page | body_attrs}}>
{{page | edit_bar }}

<table width=100%>
<tr>
    <td colspan="2" align="right">{{page.login_menu}}</td>
</tr>
<tr>
    <td colspan="2"><div id="site-title"><h1>{{site.name}}</h1>{{site.tagline}}</div></td>
</tr>
<tr>
    <td colspan="2"><div id="main-menu">{{page.global_nav}}</div></td>
</tr>
<tr>
    <td colspan="2">{{page.breadcrumb | gt}}{{ "" | message }}</td>
</tr>
<tr>
    <td width="80%">
        {{1 | gizmo_area}}
    </td>
    <td width="20%">
    {% if page.has_local_nav %}
        <h2>Navigation</h2>
        {{page.local_nav}}<hr>
    {% endif %}
        {{2 | gizmo_area}}
    </td>
</tr>
</table>

{{page.load_gizmos}}
</body>
</html>

Of course you always could make it much prettier by adding all "bells and whistles" you need - css, images, javascripts, but remember to follow the layout structure, be sure the mandatory liquid tags are on their places and always put gizmo areas inside "td" tags.