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

ocPortal Tutorial: Themeing your site

Written by Allen Ellis, ocProducts
{!DOC_THEMES}



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 color 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 nothing 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 about 1,000 templates that make up ocPortal and all of its add-ons. 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

{!DOC_THEMEWIZARD}

{!DOC_LOGOWIZARD}

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 flip side, 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 page 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, 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 drop-down list and click "submit". 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 files 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 above, 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 pages and pages that use templates are 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 "Themes" section of your Admin Zone. 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

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 two major ones are images and tables.

Images:
To insert an image into your template, use ocPortal's image parameter: {$IMG,codename}. Replace codename with the image code for the image you want to use. This will turn into the image's path. Be aware that this does not insert any HTML for you, so to use it fully:

Code

<img src="{$IMG,page/delete}" alt="Delete This" title="Delete This" />
This would insert the image http://www.mywebsite.com/themes/default/images/page/EN/delete.png into your page.

The advantage to using the ocPortal code instead of hand coding the image is two-fold. First, you'll notice that it is able to automatically detect the skin and language that is currently in use (in this case, the default theme and English). Secondly, if you ever move the image, you don't have to edit every page that ever used it to point to the new location. You can edit images from within your themes management page.

Standard boxes
Across ocPortal, we frequently use standard boxes to set content apart. To maintain a consistent look, we recommend you use them whenever possible. Tempcode has a directive to include one of these boxes, and is used like this:

Code

{+START,BOX,title,dimensions,type,options,meta,links}

Tip

The third parameter is actually part of the template name: STANDARDBOX_<type>. Thus, you could create new templates and use them as boxes.
After the +START,BOX, there are five parameters separated by commas.
  • The first is the title of this box, and you can name it anything you like.
  • The second is the width of your table. It is a CSS width (i.e., 35% or 250px). You may also specify a height, by using a value such as 100%|100px.
  • The third is the type of box. classic, panel, med, curved and light all come as standard.
  • The fourth is for special meta information to display and forms a pattern, key|value|key|value|… (e.g. Name|Allen|Gender|Male|Country|USA)
  • The fifth is for links to display and is a series of hyperlink tags separated by "|" (e.g. <a href="http://ocportal.com">ocPortal</a>|<a href="http://ocproducts.com">ocProducts</a>)
No parameters are actually needed. Dimensions defaults to '100%', type defaults to 'classic', and all others default to blank.

To learn more about these advanced features, read our advanced themeing tutorial.

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 "Themes" section of your Admin Zone, 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 most images you can get straight to their editing screen by holding down the 'control', 'shift' and 'alt' keys together whilst clicking on the image.

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.

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 the image's pathname. For example, the "delete" image in the folder /themename/images/page/delete.png, is currently titled page/delete.png. 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 on another website.
The final two options, "Use for all themes" and "Use for all languages" are self-explanatory.

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 colors 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, paramaters, and directives to help you edit your templates. These include the $IMG and $START_TABLE symbols.

See also