ocPortal Tutorial - Theming your site

Document Sample
ocPortal Tutorial - Theming your site Powered By Docstoc
					     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).

                                                 Table of contents

1.   Technical structure
2.   Cheating: the Theme Wizard
3.   Making a new theme manually
a.   Good design
4.   Technical aspect
a.   CSS
b.   Revision history
c.   Templates
d.   Alternative Method
e.   Understanding Templates Code (Tempcode)
f.   Images
5.   Tips
6.   See also

     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.

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
There are more design tips like this in books and across the Internet, if you are further

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.


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

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.


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.

The "Tree" dropdown
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 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

An example
of the "Tree"

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

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 template editing

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

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.

<div class="non_current_page_2">
   <a href="http://ocportal.com/pg/start/index.php">Welcome</a>
<div style="display: none">, </div>



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

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.


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
Alternatively, for most images you can get straight to their editing screen by holding down the
'control', 'shift' and 'alt' keys together (Mac users: 'Command' + 'Option/Alt' + 'Shift') 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.

                                             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/delete , 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 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

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/ ).


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

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

Shared By:
Tags: ocPortal
Description: http://www.redshoesconsulting.com/