Composr Tutorial: Themeing your site

Your website's entire appearance, from its layout, to its images, and color schemes all make up a 'theme'. These themes are completely customizable by you, given a moderate knowledge of HTML5 (HyperText Markup Language) and CSS (Cascading Style Sheets).

Technical structure

The two major components (aside from images) are the HTML and CSS of your website. The former controls most of the layout of your page, while the latter is responsible for the look of your site, including colour schemes and border styles.

The CSS is edited much like any typical website's CSS would be. Composr has CSS split up into a number of files, but other than that there is little that makes it different than any website's CSS.

The HTML is a different matter. Composr's HTML is split up into small sections, called "templates". These templates have several advantages:

• First, splitting large complex pages down to individual templates allow those templates to be re-used, meaning there is less code to be maintained. It also allows sections of code that are repeated often to only be written in one place. This makes updating and maintaining your HTML a lot easier
• Second, we believe this makes editing an easier process. Instead of loading up an entire website to find the proper HTML to edit, one can simply call up a template, which is typically between 2 and 20 lines long. This means if you want to edit a specific section, you can load the template for that section and only have to work within that template

At this time, there are over 1,000 templates that make up Composr and all of its addons. This may seem like a daunting number at first, but usually you'll find that you only need to edit a few of the major ones to achieve a new overall look that you desire.

Cheating: the Theme Wizard

An 'Automatic theme generator' is provided that will generate themes based on the default theme but tailored according to the parameters (such as colors) you define. This will allow you to create an individual look to your website, without going through the full artistic and technical process of theme generation. The results are of course limited (conversely virtually anything can be done using the manual themeing process), but good enough for many websites.

Be aware of the following small deficiencies:

• Some default software emoticons are animated, and attractive animated images have to be saved to a particular background colour -- so you may wish to uninstall these animated emoticons or rework them in an image editor.
• Extreme black/white themes will not come out of the Theme Wizard 100% perfectly, and need a small amount of tuning. Using the Theme Wizard at extreme black/white, causes contrast problems, as a result of the maths (essentially, there are fewer intermediate shades of black or white than there are shades of colour if the saturation is high enough for colour to be discernible). There's no good automatic solution to that, other than to manually go in and change some of our subtly shaded colours to hard white/black as required. The issue is worst in the few places where we're using different colours to provide contrast rather than combination dark & light.

The Theme Wizard is available at Admin Zone > Style > Themes > Theme Wizard link.

A 'Logo Wizard' is provided that will create you very simple site logos (the logos in the top-left of your website). It is recommended that you use this tool to create your initial logo and consider making your own customized logo at a later point.

Making a new theme manually

Good design

When making your own theme, you need to be aware of several things. Firstly, it is good to have a general idea of what you're going to do before you dive into making changes. This way you can hopefully maintain a more consistent look across your website, and avoid a lot of repeated work.

When making a new theme, it is wise to put good design tactics to use before beginning your work. These include:

• Maintaining a consistent look across your pages
• Avoid "busy", cramped looking pages -- allow room for your viewer to 'breath'. Padding is an excellent way to accomplish this
• Visual flow: make certain your use of headings and other large/small sections are appropriate to help direct the viewer's eye to the most important information
• Colour schemes: Pick a colour scheme, and try to stick with it. Don't use different colours for every class in the CSS file -- your colours will only end up conflicting and looking ugly
• On the other hand, colours that contrast in a good way are encouraged. If you are able to pick multiple colours (usually not more than two) that compliment each other, it is wise to use these. This will allow you to separate important content through use of a colour variation

There are more design tips like this in books and across the Internet, if you are further interested.

Technical aspect

To create a new theme manually, go to Admin Zone > Style > Themes, and you will find a link to do it. This will bring up a list of your current themes, which is probably just the "default" theme. We highly recommend creating a new theme and working within that, since if you accidentally make a mistake you can always fall back to the default theme.

Click the "Add empty theme" link at the bottom. This will bring you to a screen prompting you for a name for this new theme, an option to apply it as the default theme across all of your zones, as well as other options. It is advisable to not tick the 'use as default on all zones' option until you've styled your new theme to your liking, unless your website is closed to the public anyway. If your website is currently open and you want to make sure that no other members may even manually select your new theme until you are ready, you may set permissions for it.

Clicking "Add empty theme" then brings you to a page that prompts you to type in your FTP details. This is so that Composr can create the appropriate folders and files without requiring you to CHMOD these folders to 777 (which would pose a security risk). If you are running this on your local Windows computer, or if you know the themes folder is world-writable, you can probably leave these fields empty and just click the "Abstract file management" button.

At this point, Composr will make a set of empty folders for this new theme, and you may begin editing it. You will be prompted to edit this theme's templates, CSS, images, or be taken back to a main page.

It is recommended that at this point you go to edit your account settings and switch over to your new theme, so that you can see changes as you make them.

CSS

Editing the CSS is one of the most trivial, but most important, of Composr's themeing abilities. You can edit it by clicking "Edit CSS" in the row for the theme of your choice. You will be prompted to edit a CSS file. The main ones that come with Composr are:

• global.css: This file contains most of the classes used throughout Composr. This is the file you'll be editing most of the time
• no_cache.css: These are classes that make use of Tempcode (for example, checking what browser is being used) to vary the style of the class
• cns.css: These are a set of classes that are used within Conversr

The other CSS files are used in specific areas of the system.

To edit a CSS file:

1. click it from the list
2. click the "Edit" button
3. change the CSS. For example, adding:
   

   Code (CSS)

   body {
           font-style: italic;
   }
    
   … would make all text italic (obviously a silly, but simple, example).
4. click "Edit CSS" to save

You should be able to see your changes right away.

If you get confused by Composr's use of Tempcode within the CSS you are free to strip and replace it with pure CSS as you go. The Tempcode is used for the Theme Wizard, and to make maintenance a bit easier, but you don't really have any particular personal incentive to maintain that.

Contextual CSS editing

You can edit CSS contextually, via the options in the Page Rendering Tools dropdown in the footer (assuming this still exists in your theme). All the CSS files used on the screen you are on will show as options in the dropdown list.

The contextual editor allows you to make live changes, to preview on the fly, then save them.

You may want to add &keep_no_minify=1/?keep_no_minify=1 to the URL before using these tools as it will make the live previews more accurate. If you're not sure how, just go to http://yourbaseurl/index.php?keep_no_minify=1 and browse back to where you want to be. The Composr minification features will sometimes prevent the contextual editor from being able to interactively remove styles you remove in the CSS editor.

Debugging

If you find the CSS totally "corrupts", it is likely you have made a typo somewhere. For example, failing to close a comment.

You can't effectively check the Composr CSS because it has lots of Tempcode in it. Additionally, the normal outputted CSS is minified, so hard to read and relate to.
Fortunately there is a solution. If you go to http://yourbaseurl/index.php?keep_no_minify=1 then the CSS will not be minified. You may then look at your HTML source, locate the URL to your CSS, and then pass this onto a regular CSS validator.

Equations

Some CSS files have {$THEME_WIZARD_COLOR,#RRGGBB,name,equation} lines near the top.

When the Theme Wizard runs the first parameter (the colour) of the THEME_WIZARD_COLOR line is regenerated from the third parameter (the equation) by running through the calculation logic of the Theme Wizard.

For example,
… may become:
(this would happen if the seed colour used in the Theme Wizard was #ff0000)

This is all happening only when the Theme Wizard is run.

There is a special case for these particular equations in global.css only:
The Theme Wizard actually totally replaces these equations based on the seed, and whether light or dark was specified for the theme. It is these equations that sit at the root of the Theme Wizard calculation (because they don't depend on any other equations, they are defined directly by colour). The Theme Wizard is essentially an algebra solver using colour theory (a branch of applied mathematics). It keeps working at solving the equations, using the ones from global.css as a base, until it concludes.

When the CSS file is compiled, it works as a simple variable system. The second parameter serves as the variable name, which can then be referenced in the CSS as {$GET,name}. It's a very straight-forward substitution system.

You can if you wish just bypass the Theme Wizard equations system and directly enter your own CSS colour codes in place or in addition to what the Theme Wizard is doing. You are in no way tied into the mechanism of the Theme Wizard once you begin editing your own theme. That said, it can be useful to help you keep your colour palette consistent.

CSS prefixing

Some browsers experiment with new CSS properties using prefixes. More details are explained here: What Are CSS Vendor or Browser Prefixes?.

In Composr we use {$BETA_CSS_PROPERTY,property: value;} to automatically adding prefixing to a property, or make other changes to make a property work across different web browsers.

Of course doing this risks relying on browser CSS behaviour that may be buggy or subject to change. By passing it through BETA_CSS_PROPERTY in a consistent way we can actually change the output across Composr patch releases, if browsers change their syntax -- so it's a nice little solution we have here.

Other notes about CSS conventions

Some additional comments are made available at the top of global.css. Mainly, our support for rtl languages and our use of em units.

Revision history

If you have made any edits to your file's CSS, they will show up in a list underneath the CSS. You'll see the dates they were made, who edited them, and a link to restore it if you choose.

Templates

As stated earlier, the templates allow you to control the layout of your site, by allowing you to edit all of the HTML used across Composr.

Before you edit your templates, you need to know which template you're going to edit. It's also important to know if you actually want to edit a template in the first place. In many cases, the page is built up using Comcode , in which case you would edit the page simply by clicking the "edit this page" link at the bottom of the page.

An example of this is the front page in the Welcome zone. If, for example you wanted to edit the 'poll' section, you simply click the "Edit Page" link at the bottom of the page. This takes you directly to an "Edit Comcode page" screen, where you can edit any element of that page. Knowing the difference between Comcode page s and pages that use templates is sometimes difficult. The general rule of thumb is that if there's an 'edit this page' button at the bottom of the page, try it first to see if you can edit what you want. If not, you'll need to determine which template you need to edit.

To get a list of all of the templates for a given page, choose the "Template Tree" page rendering tool (see example). Then click the "view" option, and a new window will appear, containing a list of templates for the page you're viewing, shown in a structured tree format (image). This list may look a little bit intimidating at first, but once you understand the concept behind it, it's relatively simple.

The list is essentially a list of all of the templates used on that page. The ones that are nested underneath parents are templates that are used within those parents.

The entries on the list are individual templates. If you know which one you want to edit, you can simply click it, and you will be taken to a page where you can edit that template. You may also select multiple templates for editing; this is very advantageous as it allows you to do a group-preview of your changes before you save them.

On this page, you will see a text field where you can edit the HTML for this template. Below it is a grayed-out version of the same template, containing the original in case you need to reference it.

You can simply modify the template here, and then click the "Edit Template" link to save your changes, or, if you reached the template editor from the 'template tree' screen then you can preview the changes of all templates you currently have open for editing without having to immediately save them.

There is also a section at the bottom allowing you to restore a previous version, if you have any.

Alternative: Templates page rendering tool

There is a "Templates" page rendering tool you can use. This is similar to the "Template Tree" tool, except it is a flat sorted listed with no repetition. The number of times each template is used is displayed.

Advantages of this technique:

1. Much more compact display
2. Shows templates 'override' options that are supported even if not used (e.g. as supported in the catalogue system, for overriding templates on a per-catalogue basis)

Alternative: keep_markers

If you can't access this tree drop-down (perhaps you have removed it from your custom theme), there is a slightly less user-friendly alternative. If you add &keep_markers=1/?keep_markers=1 to the end of your URL, click "Go" again, then click View > Source in your browser, you will be able to see the HTML markup for your page, with comments marking the beginning and end of each template. This is a great way to find a template if you know exactly which section of the page it's at.


You can see that it's marking the beginning and end of two templates. The first is MENU_BRANCH_popup.tpl, which contains another template: HYPERLINK.tpl.

Alternative: Manually identifying the template to edit

If you already know which template you intend to edit (by intuition, memory, or reading the code), you can do it directly through the 'Edit Templates' screen.

1. Go to Admin Zone > Style > Themes.
2. Click "Edit Templates" for the theme of your choice.
3. You will see a list of templates to choose from, so you can pick the appropriate one.

Understanding Templates Code (Tempcode)

There are many sections of code in your templates that you'll need to be aware of in order to be effective in your editing. The code is written in our templating language, which is known as Tempcode. For more information see the Tempcode programming tutorial.

Screen previews

For templates of bundled functionality, the template editor will show a 'Preview' button. The button invokes the screen preview that covers the particular template, but incorporating any live changes you're making in the editor. The screen previews are a Lorem Ipsum sandbox that works regardless of the content on the actual website.

It's a very useful feature.

Theme images

An image used by a Composr theme (including the default theme) is called a "theme image"; this is basically every image that isn't a part of content (gallery images, banners, etc, would be content). There's a whole system for dealing with theme images.

Naming convention

Theme image codenames are mapped to URLs via a database table, but initially they are auto-detected from a very simple naming convention…

themes/yourtheme/images_custom/foo/bar.png would be the foo/bar theme image and could be referenced by this Tempcode in templates or CSS files: {$IMG,foo/bar}.

Composr searches under your theme's images_custom and images folders for matches, and if it can't find one it will fallback to searching the default theme's images_custom and images folders.

All the following file extensions are recognised, in precedence order:

• png
• jpg
• jpeg
• gif
• ico
• svg

Don't have multiple files with the same base name but different file extensions as only the highest-precedence one will ever be used.

Once the correct URL has been detected, the database table is updated. This is basically a cache and can be cleared out from Admin Zone > Tools > Website Cleanup Tools.

Editing theme images

To edit a theme image from within Composr, go to the Admin Zone > Style > Themes, then choose the "Edit theme images" link for the theme of your choice. You will be taken to a screen with a list of every image currently in use. Choose an image, then click "Edit Image".

Alternatively, for many images (larger ones using <img> tags) you can get straight to their editing screen by hovering the mouse over the image and clicking the "Edit theme image" button that appears (see screenshot).

On the edit theme image screen, you are shown the current version of this image in the top. You also have the opportunity to edit this image's name, location, or to upload a new image in its place.

Deleting theme images

You can delete a theme image from the bottom of its edit form, if it's not a default theme image.

Adding theme images

To add a theme image, go to Admin Zone > Style > Themes, then choose the "Edit theme images" icon for the theme of your choice, as before. There is a button at the bottom, "Add theme image", which will take you to a screen allowing you to create a new theme image.

You need to fill these fields:

• Name: You can call this whatever you like, but we recommend putting in something based on the image's pathname. For example, the "sortablefield_asc" image in the folder themes/themename/images/results, is currently titled results/sortablefield_asc. This makes it easy to tell on first glance which folder an image is in, which in turn usually determines what group of images it belongs in.
• Upload or URL: Choose one of these options to upload your image to your website. Use the upload field for files that currently exist on your computer, or use the URL option for an image that is already online somewhere.
• Use for all themes…
  
  • If you are adding a theme image that is only relevant to your new theme: you should not tick (check) this. For example, an image that is only referenced by one of your customised templates.
  • If you are adding a theme image that potentially could be used by any theme: you should tick (check) this. For example, an image used on one of your menus (you can add such images by adding them with image codes that start icons/).

This is a simple example:

1. Find or make a suitable image for your website. If you want to add a new background pattern for your website then you can find a suitable one from a public domain/creative commons tile graphic for your website.
   For this example we'll use this background. Download this file.
2. Go to Admin Zone > Style > Themes > Edit theme images (against your own theme).
3. Select the "Add theme image" button at the bottom of the screen, which will direct you to the add theme image form.
4. Fill the Codename for the image. For this example we'll use new_background.
5. Browse for the image file under the Image field.
6. Submit the form via the "Add theme image" button.
7. To apply the uploaded image to your website theme, you have to edit the CSS file.
   Go to Admin Zone > Style > Themes > Edit CSS (against your own theme).
8. Our change in action

   

   (Click to enlarge)

   Edited CSS

   

   (Click to enlarge)

   Searching the CSS

   

   (Click to enlarge)

   Select the global.css file to edit (actually it's selected by default), and click the "Edit" button.
9. Find background: url('{$IMG_INLINE;,outer_background}'); using either the browser's find feature or the find feature in the editor bar.
10. Change background: url('{$IMG_INLINE;,outer_background}'); to background: url('{$IMG_INLINE;,new_background}'); (our new theme image).

(a more sane option would have been to directly edit the outer_background theme image, but I wanted to give a simple example of a new theme image while doing only minimal CSS editing)

Deleting themes

You can delete a theme from the bottom of its edit form.

Tips

1. Do not use a custom theme on the Admin Zone or CMS zone. It's not necessary and would make you have to consider all kinds of extra details
2. Uninstall any non-required addons, so you don't have to test your new theme on so many screens. It is a huge decrease in the burden of themeing
3. The web developer tools in modern web browsers are incredibly handy in analysing how the Composr CSS interacts with the HTML. You can use them to run all kinds of tests, and quickly get a handle on how things are built.
4. Read up on CSS and HTML generally. If you are going beyond simple themeing you'll need to understand the complex aspects of these technologies, and they aren't always simple. Composr is entirely built on web standards, and thus can be reformulated using them. The web standards are supplemented with Tempcode and glued together with the structure Composr provides (see below)
5. Try and think structurally. Remember that your layout is going to be best composed using standard Composr features, like panels, menus, blocks, Custom Comcode tags, pages, and Comcode/Tempcode includes. You can bend all these far beyond the default settings (e.g. a panel can be placed anywhere and be any shape), so don't feel like you're constrained by them -- they are a tool for you to manage your site once it is finished
6. Make good use of the template tree if you're not sure what templates are being used on a screen. Alternatively use the template search feature (available on the screen where you choose a template to edit)
7. If you are choosing a template to edit manually from the full list but you know the name of the template, you can quickly get to it by typing rather than scrolling. Just click one of the entries in the list, and then type "dash-space-template-name", and most browsers will jump straight to it
8. Remember to test how your e-mails look as well as your screens
9. The font-size changer assumes you will use em-based (i.e. relative) sizing for all styles. The font sizer works by setting a larger base font size. The default theme sizes almost everything relatively (using em), so a larger base font size has an effect that cascades through everything. If you change styles to pt or px then that is absolute and hence the cascade will be stopped at that point.
10. Don't forget to make a favicon
11. Don't forget to consider how your website looks when printed
12. If you want to exhaustively test your theme for third-party use, the screen previews feature will really help
13. If you are more comfortable copying individual files and editing them within your favourite text editor, this may well be a better approach than using the inbuilt template and CSS editors -- especially if you are a developer
14. If you get stuck or make a mistake, don't feel bad -- this happens to the best developers too

Many more tips and points of guidance are included in the Designer themes, implementing a clean-room design tutorial.

Copying themes

You may copy themes between sites, or duplicate them, but make sure you empty the template cache before using a copied theme. The cache files hard-code file paths, URL paths, and the theme name.

Limitations of multiple themes (advanced)

There are a couple of limitations if you wish to run multiple themes at once:

1. When Comcode is compiled, it is compiled against the active theme. So don't try and customise Comcode templates differently for different themes as it will be 'arbitrary' which template is shown to an end-user.
2. When e-mails are sent to multiple recipients at once, or unknown recipients, it will use the site's default configured theme (it won't separately style things for each individual recipient). The theme affects the MAIL template chosen, the theme images used, and the CSS. Note that it is very rare for Composr to actually mail multiple recipients at once, because the notification system itself generates e-mails separately for each member being e-mailed.

See also

• Guide to web technologies (including HTML, CSS, and JavaScript)
• Designer themes, implementing a clean-room design
• Mobile design
• Tempcode programming
• Releasing a theme
• Theme lifecycle
• Composr site structure
• Making a new theme
• Using Chrome development tools to help with themeing

Feedback

Have a suggestion? Report an issue on the tracker.