HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS, which is now in beta. ocPortal 9 will be superseded by Composr 10.

Head over to compo.sr for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.


ocPortal Tutorial: Themeing your site

Written by Allen Ellis, ocProducts
Your website's entire appearance, from its layout, to its images, and color schemes all make up a 'theme'. These themes are completely customisable by you, given a moderate knowledge of XHTML (eXtensible 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. ocPortal 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. ocPortal'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 ocPortal 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 colours) 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.


The Theme Wizard is available via it's own icon in the Style section of the Admin Zone.

Note that 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.

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 customised 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
  • Color schemes: Pick a color scheme, and try to stick with it. Don't use different colors for every class in the CSS file – your colors will only end up conflicting and looking ugly
  • On the other hand, colors that contrast in a good way are encouraged. If you are able to pick multiple colors (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 color 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 'Style' section of your Admin Zone and you will find an icon for 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 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 theme" then brings you to a page that prompts you to type in your FTP details. This is so that ocPortal 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-writeable, you can probably leave these fields empty and just click the "Abstract file management" button.

At this point, ocPortal 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 the "My profile" link in the "personal stats" block shown on the main website, then "Edit Profile" 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 of ocPortal'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 ocPortal are:
  • global.css: This file contains most of the classes used throughout ocPortal. 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
  • ocf.css: These are a set of classes that are used within OCF
  • side_blocks.css: These are used for many of the blocks designed to be shown in panels

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

To edit a CSS file, click it from the list and click the submit button. This will bring you to a basic text editor with the CSS in it. You can change the CSS and click "Edit CSS" to update the CSS for this theme.

At the bottom, there is also an "Switch to Advanced CSS" link. Clicking this will generate individual color pickers for each different color in your CSS file. Then you can go through and change the colors this way, then click the "Edit CSS" button at the bottom. This option is recommended for beginners.

You should be able to see your changes right away.

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 ocPortal.

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 page" link at the bottom of the page.

Thumbnail: The "Tree" dropdown box

The "Tree" dropdown box

An example of this is the front page in the 'root' 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, 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 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.

Thumbnail: An example of the "Tree" page

An example of the "Tree" page

To get a list of all of the templates for a given page, choose the "tree" option from your toolkit (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 [Example ]. 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.

Thumbnail: The template editing page

The template editing page

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.

If you can't access this tree drop-down, there is a slightly less user-friendly alternative. If you add ?keep_markers=1 or &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.

Code

<!-- START-TEMPLATE=MENU_BRANCH_popup -->
<div class="non_current_page_2">
   <!-- START-TEMPLATE=HYPERLINK -->
   <a href="http://ocportal.com/pg/start/index.php">Welcome</a>
   <!-- END-TEMPLATE=HYPERLINK -->
<div style="display: none">, </div>

</div>

<!-- END-TEMPLATE=MENU_BRANCH_popup -->

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 Method

"Default"?

You may notice that this list of templates are all in the /default folder, which isn't necessarily the theme you're trying to edit. This is intentional – the only templates that will be copied into your /mytheme/templates folder are ones that you've actually made changes to. Everything else is just left in the /default/templates folder. This is to cut down on the amount of files you need to keep track of.
If you already know which template you intend to edit, you can do it directly through the 'Edit Templates' interface. To do this, go to the "Style" section of the Admin Zone and then the "Themes" icon. Then click "Edit Templates" for the theme of your choice. This will provide you with a list of templates to choose from.

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.

Images

Thumbnail: The "Add Image" page

The "Add Image" page

Many of the links and buttons in ocPortal are created as images. If you wish to edit these images (or add new ones), you can do so via ocPortal's "Edit Images" interface.

To edit an image, go to the "Styles" section of your Admin Zone and then the "Themes" icon, then choose the "Manage theme images" link for the theme of your choice. You will be taken to a screen with a dropdown 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 button that appears.

On this 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.

Power users

You can add new theme images by saving them directly into themes/yourtheme/images or themes/default/images_custom, using subdirectories where appropriate (the path forms part of the theme image name). You should never save into themes/default/images though, or make changes to those files directly, because this directory 'belongs' to the software itself. If you wish to override a default image, copy it to the directory where you'd put it as if it were a new image, then clear the Theme Image cache via the Cleanup Tools in the Tools section of the Admin Zone.
To add an image, go to the "Themes" section of your Admin Zone, then choose the "Manage theme images" link for the theme of your choice, as before. There is a link at the bottom, "Add theme image", which will take you to a screen allowing you to create a new theme image.
  • Name: You can call this whatever you like, but we recommend putting in something based on the image's pathname. For example, the "delete" image in the folder /themename/images/page, is currently titled page/delete. This makes it easy to tell on first glance which folder an image is in, which in turn usually determines what style of image it is
  • 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

If you are adding a theme image that is only relevant to your new theme, you should not tick "Use for all themes". 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 "Use for all themes". For example, an image used on one of your menus (you can add such images by adding them with image codes that start menu_items/).

Mobile support

ocPortal supports QVGA mobile resolution for all frontend screens, and automated mobile device detection. Mobile mode can also be flipped manually via a footer link.

You can choose to enable mobile mode only on a per-page basis if your content/layout isn't fully compatible (most complex fixed width designs would have problems if a lot of attention is not given). Devices like iPhones automatically go into mobile mode, so you don't want it to load up mobile display settings and overlay them on content that doesn't work, as it can make a big mess.
To activate the feature you need to put this in your themes/<themename>/theme.ini file:

Code

mobile_pages=forumview,topicview,topics,vforums
This particular example enables mobile support just on the forum pages.
On devices like iphones or Android, it still works if mobile mode is not enabled, it just uses zoom. Mobile mode is much nicer of course.

Tips

  1. Do not use a custom theme on the Admin Zone or CMS zone. It's not necessarily 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 Firefox Firebug addon (or developer tools in IE8, Safari, Google Chrome, or Opera) is incredibly handy in analysing how the ocPortal CSS interacts with the XHTML. You can use it to run all kinds of tests, and quickly get a handle on how things are built. The Firefox Firediff extension is also great as it helps you keep track of your changes so you can easily put them back into ocPortal's stored CSS.
  4. Read up on CSS and XHTML 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. ocPortal 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 ocPortal provides (see below)
  5. Try and think structurally. Remember that your layout is going to be best composed using standard ocPortal 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

For more tips, see a walk-through guide on our forum.

Concepts

Theme
Your theme is the sum of your CSS, images, and templates, which work together to create the style and layout for your site.
CSS
Your CSS is the element of your theme that specifically controls the colours and styles on your site, and has limited layout functionality
Templates
The templates on your site are individual HTML files that chain together to create the final HTML used on your site.
Images
Images are used throughout your site, in the form of buttons, backgrounds, emoticons, and more.
Tempcode
Tempcode is a set of symbols, parameters, and directives to help you edit your templates. These include the $IMG symbol.

See also