Creating Themes

Theming Overview

Showkase is designed to create web sites quickly and easily without any knowledge of html, css or other web technologies. All that technology is still there but the end user doesn’t see it – it’s tucked away in the theme. Themes are powerful. Not only do they determine the look of Showkase web sites, they also create many of the customization screens that appear in Showkase admin.

There are two kinds of themes in Showkase – base (or parent) themes and child themes. The base theme contains resources for several themes. Each child theme has just what it needs to assert its individuality. The themes you see in the Showkase Theme Select screen are usually child themes and the base theme is hidden. For instance Boma is a child of Base. There are only two levels of theme – no grandparents or grandchildren. Child themes were introduced in Showkase version 1.3, earlier versions support base themes only.

The next section is called ‘Easy themeing’ but let’s stress it again so we don’t waste anyone’s time – you will need a good knowledge of html and css to make much progress.

Easy Theming

Creating a Child Theme

By far the easiest way to create a new theme in Showkase is to make a child of an existing base theme. That way most of the work has already been done for you in the base theme.

It’s easy to create a child theme from one of the existing themes such as Boma.

1. Create a new folder inside _themes and give it a short simple name. It’s best to use lower case letters and numbers only – no spaces. Let’s call it example.
2. Copy the content of _themes/boma into your new folder.
3. Edit _themes/example/config.ini. Change displayName to "Example" and change the description to whatever you like – but keep it short.

That’s it – you have a new theme. You can switch to your new theme in the Showkase Theme Select screen. Of course it looks an awful lot like Boma! We’ll give it a bit more personality in the next section.

Working with Theme CSS and Javascript

You can make dramatic changes to the appearance of your new theme using only css. The styles for your new theme are in example/css/styles.css. Open-up this file in a text editor. It’s divided into three sections: a browser reset, then styles common to several themes, then the styles for the individual child theme (Boma since you copied it from there). It should not be necessary to change the first two sections. Work with the individual theme css. We can’t go into detail here – did we mention that you’d need a good knowledge of css to become a themer?

You can add your own javascript in example/js/theme.js. This file loads after the parent theme javascript which includes jQuery.

It’s possible to do a lot more in a child theme – override the parent html, change what the user sees in the Showkase customize screens, change viewer defaults and more. But before we get into all that we need to step back a bit and cover some basic concepts.

Advanced Theming

Creating a new base theme or creating a child that is radically different from its parent is a bit harder than tweaking an existing theme. It’s like creating a web site but requires a slightly different mindset. When you’re building a web site, you usually know roughly how many pages there will be in the site. You have full control over the css and the html and you can see if the content causes any problems for your design. With a theme, you have control over the css and most of the html, for instance the site navigation html will be supplied by Showkase. And if you are not the end user of your theme then you may never see the content. And you have no idea how many pages the user will create.

Good design practices of separating css style and html content will help a lot. You can use grid systems like 960.gs but many of these systems require you to specify the layout and style of the site with special classes or id's in the html. This can mix-up style and content and can make the life of a theme designer harder rather than easier.

Base themes are more complex than child themes. If you start on a new child theme and eventually find that you are overriding almost everything from the parent then maybe it’s time to create your own base theme.

Showkase uses the Smarty 3 template engine. Smarty is a very flexible system, it’s easy to use at a basic level and has many advanced features that put a lot of power in the hands of the themer. The Smarty web site has extensive documentation.

If you are not familiar with the Showkase application then you should install it on a test server and create a few web pages using the built-in themes.

As you move around the Showkase admin screens, just pause awhile on one of the customize screens, for instance Site > Customize Theme. The content of this screen can be completely controlled by the themer. Each form field on the screen corresponds to a variable defined within the theme. The themer has control over the type of field, default value, the field label and even the tooltip shown when the user hovers over the label.

All this is set in the base theme and can be overridden selectively in a child. Each screen has a corresponding .ini file, for instance the Theme Customize screen is generated by theme.ini. This shows the advantage of child themes – if you are fairly happy with the customize screen generated by the base theme then the theme.ini file for your child theme can be very simple. Other admin screens work similarly and have their own ini files such as site.ini, nav.ini, juicebox.ini, etc.

So we've just seen a Showkase user view of variables driving the look of the screen. Showkase can plug the values from these variables into templates to produce a finished web page. We’ll be returning to the topic of variables from the themer perspective later in this document.

Inside a Showkase Web Site

Now let’s move away from the Showkase application itself and take a look at the web site files and folders created by Showkase. Use ftp on a remote server or Windows Explorer / Mac Finder on a local server to look at the files in the test web site that you just created.

The front door of the site is the index.php file – the only php file in the site. It needs to be an active php file because it has to be able to find the rest of the site even if the the user moves it. Usually you will not need to touch the index.php file so you won’t need any knowledge of php to become an expert themer.

The site has a number of folders containing web pages. Each folder has an index.html file. This is a normal static html web page that has been generated automatically by Showkase. There is also a page.xml file in the folder which holds the page content in a machine-readable form. Some folders, particularly gallery pages may contain additional resources such as Flash files or scripts that have been added by Showkase.

There are also some special folders whose names all start with an underscore:

• _data holds data for the site as a whole
• _library holds library images and associated data
• _showkase holds configuration data
• _smarty holds cached data for the Smarty template engine
• _themes holds everything to do with themes
• _trash holds copies of web pages trashed by the user
• _viewers holds viewer core code and supporting files

As a theme designer, you can ignore all of these special folders except of course the _themes folder. Inside this folder you’ll see a number of sub-folders, one for each theme. Some of these themes will be base themes others will be child themes.

Inside the _theme Folder

Have a look at the contents of the Base theme folder – we won’t go into details at this stage. Inside the theme folder you’ll find the pagetypes.ini file that defines the page types that are supported by the theme. Then there’s the theme.ini file – the file that generates the theme customization screen that we looked at earlier. We’ll cover the detailed structure of the files later.

The viewers folder contains an ini file for each supported viewer such as juicebox.ini. These files set the viewer defaults and generate the viewer customize screens in Showkase admin.

Also inside the _theme folder is a css folder and other folders for holding resources like scripts and font files.

The heart of the theme is the pagetypes folder – inside you’ll find more ini files and template (.tpl) files – one pair for each supported page type plus some general templates like layout.tpl.

Templates define the web site html. We’ll explain how they work and how you can edit them later in this document.

When the user hits the Publish button in Showkase, the current values of the variables are pulled out of xml files and plugged into the templates. Several templates may combine to produce the final html web pages.

Working with Theme Variables

Theme variables store data provided by the theme designer, the Showkase user or the Showkase system. They can pass data to templates to produce web pages, change viewer settings and sometimes control Showkase itself. For instance the page body content entered by the user will be held in a variable and the Juicebox text color setting will be held in another variable. If the theme designer chooses to expose a variable then the user will be able to override the default setting in one of the Showkase admin screens.

Take a quick look at _themes/base/theme.ini to see a whole lot of variables of different types. The corresponding theme.ini file in a child theme is much simpler, for instance _themes/boma/theme.ini. This is because almost all of the variables that Boma needs are defined in its parent theme. Boma is simply adding a variable to show or hide the home navigation link. You can add new variables like this in your own theme without needing to touch the base theme at all.

Look at _themes/kosel/theme.ini. There are a few more settings here but still not nearly so many as in the base theme. Some of the variables already exist in the Kosel parent but we want to change the default value or hide the variable from user changes. In this case it’s not necessary for the child theme to redefine the whole variable. For instance the default value of ss_indexThumbColumns has been changed to 4. All the other settings for ss_indexThumbColumns come from the parent theme.

For a better understanding of Showkase variables read the Guide to Defining and Using Showkase Variables

Working with Html

You can get a long way with css but there may come a time when you want to change the html. This is the perhaps the most difficult aspect of theming and requires some understanding of how the Smarty template engine works and how several Showkase templates combine to produce the finished web page.

Template files all have the suffix .tpl. If a template file with the same name occurs in the parent theme and the child theme then the child theme will override its parent. You can see this in the Manager theme for instance where there is a layout.tpl file in both Base and Manager. This is the most straightforward way to change the html in your child theme – copy the template from the parent theme into the child theme and keep the same file name. Edit the child template. Smarty will find the child template first and ignore the parent template completely.

Replacing the whole template is best if the child template is very different from its parent. However, if you just want to change a few small parts of the html then you can keep the base template and override the bits you need to change. Showkase makes this possible by breaking the templates into blocks and making extensive use of Smarty’s template inheritance feature to create a chain of templates. For example, a juicebox page is constructed from this chain of templates:

layout.tpl | basetheme.tpl | theme.tpl | juicebox.tpl

Note that some of these templates are in the parent theme and some are in the child. Just remember that Smarty looks for templates in the child theme first and if it finds what it’s looking for then it looks no further.

The chain must be complete. If juicebox.tpl extends theme.tpl then there has to be a theme.tpl but it doesn’t have to do anything other than maintain the link.

Let’s examine the links in this chain starting with _themes/base/pagetypes/layout.tpl which contains html content that is common to all page types. It looks like a normal html file but with very little content. Instead, there are special tags, for instance:

{block "meta"}{/block}

These block tags tell the template engine where to place content from other template files further down the chain. Blocks can be nested inside other blocks. There are also a number of {$variables} within brace characters. These are the variables that we looked at earlier. They are defined in the ini files or provided automatically by the Showkase system.

Now take a look at _themes/base/pagetypes/basetheme.tpl. This file defines some of the blocks of html that will be slotted into the layout template. It must start with a special tag to connect it with the layout template:

{extends file="layout.tpl"}

Inside the {block} tags it looks like normal html with some more {$variables}. Some of the block tags will completely replace the corresponding tag in the layout template {block "meta"}, others will be prepended or appended to the layout template block {block "body" append}.

The next link in the chain is the theme.tpl template in the child theme. Boma theme.tpl is a simple example. First there is the {extends file="basetheme"} block to connect it into the chain. Then there are two content blocks. The first block appends a javascript link to the scriptlinks block in basetheme.tpl. The second block prepends some additional css to the styles block. So Boma does not need to replace the whole of the base theme templates and duplicate a lot of the code. It just makes the minimum changes.

The final link in the chain is the juicebox.tpl template in the parent theme. Boma could have its own juicebox.tpl file but there is no need for it. The parent html works fine for Boma and if there is no child template then Smarty will look for the template in the parent theme.

The html in Boma and Kosel is very similar so they can draw heavily on the parent theme templates and keep things simple in the children. Manager html is more different – no navigation, full-screen galleries and not all page types are supported. So let’s see how Manager handles that.

The supported page types are defined in _themes/manager/pagetypes.ini. Open the file in a text editor and you can see how Manager hides some of the page types supported by its parent theme.

We already mentioned how Manager replaces the whole of the layout.tpl template from Base. The Manager layout is actually simpler than Base so it makes sense to replace the whole lot rather than trying to change it.

The Manager theme.tpl is pretty similar to Boma – nothing new here.

Unlike Boma, Manager has a set of page templates such as _themes/manager/pagetypes/juicebox.tpl. These will override the corresponding templates in the parent Base theme.

The template inheritance feature can be a bit hard to get your head around at first but it’s very powerful and flexible. It greatly reduces the amount of code that needs to be duplicated in the parent and child themes. Remember one of the golden rules of computer coding – DRY – Don’t Repeat Yourself!

Theming Hints and Tips

Links in Templates

The <head> section of your html will probably contain some links to css files and scripts. Showkase provides two system variables which help you construct the links.

• $ss_themeUrl contains the url for the current (child) theme.
• $ss_themesUrl contains the url for the _themes directory which holds all the themes.

Both variables contain an absolute url (starting with a slash).

Here are examples of how these variables can be used in a template, firstly to access a css file in the child theme and then a script in the base theme.

<link rel="stylesheet" href="{$ss_themeUrl}/css/custom.css">

<script src="{$ss_themesUrl}/base/js/jquery-min.js"></script>

Page Types

At a minimum you should create (or adapt) templates for the following page types:

• Basic page – an empty page for the users to fill with their own content.
• About page – a page for the user to enter personal or company details
• Contact page – email, phone etc
• Galleries index page – an index page with thumbnails linking to the galleries
• Gallery page – at least one gallery type such as SimpleViewer or Juicebox.

Edit your theme pagetypes.ini file to expose only the page types that you are supporting.

Navigation and Page Groups

As the user creates new pages Showkase will generate html for a page navigation menu. This will be an unordered list of links. You may need to be a little clever with your css (and perhaps javascript) to get the look you want when you don’t have much control over the navigation html. Bear in mind that there is in principle no limit to the number of pages a user can create.

Showkase users can decide to use any page as the parent of a page group. For instance, they might have a page called projects as the parent and a series of project pages grouped under it or a galleries page to keep all the galleries together. When the user adds pages to the group, a second unordered list of links will be created in the navigation and nested under the link for the parent page. Only the parent unordered list and one level of nested lists is allowed – groups cannot contain groups. How you handle these nested links is up to you – simple indents, bullets, dropdowns, accordions or whatever suits the design.

Currently there is no way to set your own css classes on elements within the generated navigation html. Standard classes, namespaced with sk- are provided by Showkase as in the example below.

Example of navigation html

<nav id="nav">
  <ul class="nav">
    <li class="sk-type-galleryindex sk-page-4 sk-first active">
      <a href="/sk-export/home/index.html">Galleries</a>
      <ul class="subnav">
        <li class="sk-type-listviewer sk-page-1 sk-group sk-group-4 sk-first">
          <a href="/sk-export/pacific/index.html">Pacific</a>
        </li>
        <li class="sk-type-simpleviewer sk-page-2 sk-group sk-group-4 sk-last active">
          <a href="/sk-export/generated/index.html">Generated</a>
        </li>
      </ul>
    </li>
    <li class="sk-type-about sk-page-3 sk-last">
      <a href="/sk-export/about/index.html">About</a>
    </li>
  </ul>
</nav>

Navigation active link (you are here)

Many web sites apply a distinctive style to the navigation link for the current page, or active link. Showkase adds an ‘active’ class to each active link and its parent. These classes can be targetted with css.

Showing and hiding sub-navigation

Showkase provides the theme designer with a choice of three variables for the navigation html. Each variable contains an unordered list of links but they differ in whether or not they contain inactive child page links.

1. $ss_allNavLinks contains links to all pages.
2. $ss_activeNavLinks contains the top level list items and nested items for children of the current page only.
3. $ss_navLinks is the same as $ss_activeNavLinks by default.
4. $ss_navLinks is the same as $ss_allNavLinks if another variable $ss_showSubNav exists and is equal to "true". This is the easiest way to place the decision on showing inactive subnav in the hands of the Showkase user.

Gallery Index (thumbnail) pages

Html for a galleries index page can be generated in Smarty using showkase system variables. Look at the Base theme for how to do it. Note that users may give their galleries long titles so you might need to allow for word-wrap or set overflow hidden.

Images in Templates

Images unique to your theme such as icons are easy – store the images in a subdirectory of your theme directory and set the src attribute using the techniques we discussed earlier in connection with linking css files:

<img width="80" height="80" alt="plus sign" src="{$ss_themeUrl}/img/plus.png">

You can’t use Smarty variable inside theme css files so if you have background images set in your css file then use relative links.

#content {
	background: url(../img/background.jpg) 0 0 no-repeat;
}

You can also put css in the head of the page itself within style tags if you prefer:

<style>
#content {
  background: url({$ss_themeUrl}/img/background.jpg) 0 0 no-repeat;
}
</style>

There are several ways to handle user-submitted images.

Gallery images are largely taken care of by Showkase and the gallery itself.

One way to handle large display images such as a splash image for the home page is to use a gallery instead of a single image. That way you can take advantage of the support for galleries within Showkase.

Another way to handle single user-supplied images is to define a variable in your page ini file to hold the image tag src attribute. You can see this technique used in the Boma and Kosel About pages.

[mytheme_figure1Src]
exposed = "true"
type = "imagesrc"
section = "Page body"
label = "Image url"
value = "../_themes/mytheme/img/figure1placeholder.jpg"

The Showkase customize screen will show a text field with a browse button. Users can type a url into the text field. Or the browse button takes them to the Showkase image library and clicking on a library thumbnail enters the url into the imagesrc form field.

You can then refer to the variable in your page template:

<img src="{$mytheme_figure1Src}" alt="about" />

Two themes may have a single image in the about page but it’s unlikely they have the same size and format. So we have given our imagesrc variable a theme-specific name – it won't show in other themes. We've also supplied a default image stored within the theme directory. You could help users by including some text in the default image: For best results upload a 500px x 240px image to the image library to replace this one. If the user moves to another theme and then back to yours, Showkase will remember the url stored in mytheme_figure1Src.

If you are designing a responsive theme that can cope with different image sizes coming in from another theme then you can use one of the Showkase reserved variable names ss_figure1Src.

[ss_figure1Src]
exposed = "true"
type = "imagesrc"
section = "Page body"
label = "Image url"
value = "../_themes/mytheme/img/figure1placeholder.jpg"

You may want to give the user an option of having no image by entering an empty field for the url. You can use some Smarty code in the page template to achieve this:

<div>
{if $mytheme_figure1Src eq ''}
&nbsp;
{else}
<img src="{$mytheme_figure1Src}" alt="about" width="500" height="240" >
{/if}
</div>

Of course, the replacement content doesn’t have to be a no-break space it could be an empty string or a single pixel gif or some text or whatever your design can handle best.

Another way to handle images is hand the responsibility over to the user by providing them with an editor field. They can enter text and embed library images themselves within the WYSIWYG editor. This gives the user a lot of flexibility but you don’t have much control over how it will look.

Designing a New Base Theme

This is not to be undertaken lightly. It should only be necessary if you are creating something really new and different. Or if you have the ambition to start a whole new dynasty of child themes.

There are some restrictions on theme design and some guidelines for the theme to work well with Showkase and with themes created by other designers.

Important Restrictions

• Only one gallery per html page
• Showkase provides only one set of navigation html. That usually means one navigation menu per page, although you could use the same html twice and make it look different with css or javascript.

The easiest approach is to start from an existing Showkase base theme.

1. Create a new folder inside _themes, we’ll call it newbase for this document.
2. Copy everything from the base folder into newbase.
3. Edit _themes/newbase/config.ini so it looks like this:

   ; Name to show when choosing or editing the theme
   displayName = "New Base Theme"
   
   ; Description for theme select page - keep it short!
   description = "Make this up for yourself"
   
   ; Show in theme select screen
   exposed = "true"
   
   ; Version string displayed in change theme page
   version = "1.0"
   
   ; Parent theme directory. Empty string if this is a base theme
   parent = ""
   
   ; Control cacheing by the Smarty template engine
   ; Normally set to "false" to speed-up publishing
   ; When developing a child theme set to "true" so changes show-up immediately
   ; The variable has no effect on the speed of the published web site.
   
   devMode = "true"
   

4. Base does not have any css so create a css file for your new theme. It can be just an empty file for starters _themes/newbase/css/styles.css.
5. Edit or replace css, javascript, ini files and templates to get your theme working as you want it to.

Base has several children so it’s worthwhile having quite a complex template inheritance chain to reduce repetition. Your base theme may exist by itself without any children at all or it might have few children. In this case you might want to simplify the template chain. You must at least have a template for each supported page type. A layout template is not strictly necessary but it does cut-down enormously on repeated code, especially in the html head section.

When your theme is finished and tested then edit the config.ini file again and set devMode to "false".

	Notice: Undefined index: pageBody (a78e9ddf488b87b32b4fa94d498ff81b05462660.file.basic.tpl.php, line 115)
	Notice: Trying to get property of non-object (a78e9ddf488b87b32b4fa94d498ff81b05462660.file.basic.tpl.php, line 115)