ocPortal Tutorial: Designer themes, implementing a clean-room design

Feedback

It is very important that at any point where you think things are confusing, either in ocPortal, or in this documentation, that you write it down and let us know. We strive to make ocPortal the most user-friendly way for making a sophisticated cost-effective website and we really need to know where people get confused in order to do that. Our job is never done making ocPortal easy to use.

Anything that makes you think for more than 30 seconds is an issue we may want to resolve.

Research into ocPortal

1. Install the most recent stable version of ocPortal (or beta/RC release if you know you need to develop for a newer version or are working to a more distant deadline).
2. Get a good understanding of what features ocPortal has. In particular, what screens and blocks are available. This is important because your themes will have to make use of these facilities to implement the designs.
   
   • Add some test content for each content type. This will give you test data and also give you an idea of the features available and what fields there are.
   • Edit the front page (there's a link to do it under it as long as you are logged in as an Administrator). On the form you'll see an "Add Block" button that can add all the different blocks. You don't actually need to add all the blocks to see them because there's a preview feature. Preview all the blocks and look at the options to see what they do.
   • Visit the site-map, and go to each screen on it. This will give you an idea what screens the system has.
3. Now that you know what features are available, you need to decide what features will be used for each part of your design. Making_a_theme.pdf shows an annotated theme design that was done by someone who has never used ocPortal. You can see via the annotations how this clean-room-design can be implemented.

As a designer you will find a number of challenges that a designer does not normally face:

1. All content in a design has to be editable, so there's got to be some kind of feature associated with all the content. Every bit of text is associated to some kind of field for some kind of content type.
2. If content is missing, it shouldn't just leave empty boxes (for example), you need to think how things will work.
3. Often there will be more or less content on the final site than you've laid out in your design. Maybe in your design you assumed you could lay things out in columns of 3 items, but the end-user decided to add 5.
4. Whilst you can probably ensure that you can align things on a design, when users start adding content, you cannot know how much they will type.
5. For a theme, chances are the end user will make changes. For instance, they may switch out your choice of blocks with a different choice. Therefore you have to implement in a modular way, so that design elements or pages you did not specifically give attention to still look decent. A good example of this is styling the standard box templates (which most blocks will use) so that all boxes look good, rather than trying to style each individual block completely separately.
6. Sometimes not everything should show for every user. For example a link to add content might only be shown to administrators.

» This section is accompanied by an annotated PDF.

Implementing your design

This section will step through how to build your design, in a number of steps and sub-steps.

Static design

1. Implement your XHTML/CSS as standalone, if you haven't already.
2. Make sure you have followed these guidelines:
   
   • Don't use the CSS clear property, because it interferes with how ocPortal handles it's 3-column layout and other default styling. Contain floats in a box using something like overflow: hidden; width: 100%; outline: 0.
   • Avoid setting CSS heights wherever possible. If you set heights then if people increase their font size then it's likely text will overflow and look awful. There's rarely a true reason to set a height anyway: if you need to clear floats, use the technique described above.
   • Do not assign widths or heights or min-widths or min-heights unless necessary (e.g. to make sure you align with a background's size). It makes it very hard to adapt designs later if the spacings change and it makes pixel-level browser bugs cause larger problems.
   • Do not use floats unless doing it to make stuff sit next to something else. For example, do not float stuff just to make it not overlap with another float, and do not float stuff to try and work around IE bugs. There are much better ways to solve these problems without resorting to floats (which introduce many other kinds of problem).
   • Do not use background images unless an image really is in the background. It is harder to implement (needs CSS widths/heights setting, which is inflexible) and we can't use transparency in IE6 if we do this and we can't assign alt text. Use 'img' tags Instead.
   • Do not use a CSS reset: ocPortal does not use a CSS reset in it's default templates so you would need to re-theme all ocPortal screens to re-apply default spacings.
   • Make sure the default font size is sensible for the main content area. You will not be able to specify the font size of all text on the final theme as there will be a lot of layout that comes from default ocPortal templates and you won't have time to give them all individual consideration.
   • It's not a good idea to make your main content area too thin, because default ocPortal templates will assume that they have at least about 600 pixels.
   • Do not have two images with the same name but different extensions. For example do not have an example.jpg and an example.gif. They should have different names such as examplea.jpg and exampleb.gif

A starting point (the Theme Wizard)

1. Using the Theme Wizard (in Admin Zone –> Style –> Themes), create a base theme that matches the colour of the theme that needs to be build as closely as possible (if your theme has many colours, choose the one used most). Tell it to make the theme active.
2. You will also want to make sure the 'Block cache' is disabled in the configuration (Admin Zone –> Setup –> Configuration –> Site options –> Caches). This will allow you to make block template changes without having to worry about emptying the block cache each time. It is advisable to leave the other caches as they are; ocPortal is smart enough to detect if files have been changed in most cases.

» This section is accompanied by a video.

Images and CSS

1. Take your theme images and copy them into a new themes/<yourthemename>/images_custom/<yoursitename> directory. This will allow you to reference them in ocPortal as theme images.
2. Go to edit the CSS for your theme in ocPortal. Do this by going to the Admin Zone, selecting 'Themes' from the drop down, and choosing the 'Edit CSS' option next to your theme. Choose to edit the 'global' CSS file. Take your CSS and past it on the top. If you prefer, you can edit themes/<yourthemename>/css_custom/global.css in your favourite text editor.
3. You need to change the image references in your CSS. If you had something like 'images/example.jpg' it would need to be changed to {$IMG,<yoursitename>/example}. You should not add the .jpg/.png/.gif on the end. This will make it find themes/<yourthemename>/images_custom/<yoursitename>/example.jpg (or example.png or example.gif).

» This section is accompanied by a video.

Global layout of XHTML

1. You will next need to start modifying templates to incorporate your "global" XHTML (XHTML you expect to show on all pages). Start with the main ones: HEADER, GLOBAL and FOOTER. You can do this in ocPortal from the themes section, or you can do it in your favourite text editor (e.g. Dreamweaver) by copying for example themes/default/templates/HEADER.tpl to themes/<yourthemename>/templates_custom/HEADER.tpl. It will take you a bit of time to learn what default template code to keep and what can go. Basically you will want to keep:
   
   • most of the contents of the <head> tag from HEADER
   • References to panels, like {$GET,panel_left} from GLOBAL, so that panels can still be placed (assuming you have panels on your design! - or you may have a left and no right, or vice-versa). You can rearrange it all and place it in different places, and you don't need all the stuff about widths because you are allowed to make bigger assumptions than our default templates can. It is possible to hard-code panels into the GLOBAL template instead of using separate files, but is makes it harder for webmasters to make changes. If you feel more comfortable not using panels at first this is fine.
   • {MIDDLE} from GLOBAL, which is the main content of a page.
   • {MESSAGE_TOP} and {MESSAGE} from GLOBAL, which is used to put out status messages as you complete things on the site or if small errors happen.
   • {$JS_TEMPCODE,footer} and the <script> tag from FOOTER.
   • {$COPYRIGHT`} from FOOTER, which should be used instead of the hard-coded copyright of your design (most designs have it).
   • The rest (and there are lots, because our default theme is very thorough) can be removed.
2. If you have incorporated panels and have made the assumption that they will never be blank/hidden, then you must put supports_wide=0 into your themes/<theme>/theme.ini file.
3. Once you have your main XHTML incorporated you will see lots of problems with layout, because there will be incompatibilities with your styling and the default styling. So now is a good time to fix all these. You probably will want to remove a lot of the default styles ocPortal uses from global.css.
4. Similarly, you may find you made assumptions in your CSS. For example, you may have set quite specific styles for default elements because you only use them in a specific way on your design. Your ocPortal theme will need to not make too many assumptions like this, remember a lot of your CSS will be running on screens you haven't given individual design attention to because they will be running a lot of default XHTML from ocPortal.

» This section is accompanied by a video.

Laying out your panel/page structure

1. Once things look fairly good it is time to start incorporating all the individual blocks onto the site, as identified in the 'Research into ocPortal' stage. Mostly this is done by editing individual Comcode pages. For example, the left panel is a page called ':panel_left' that you can edit from the Content Management section, underneath the 'Pages' icon. Or, you can edit it by copying pages/comcode/EN/panel_left.txt to pages/comcode_custom/EN/panel_left.txt and using any text editor (Comcode is like plain text but with some tags, or you can type … to put in XHTML). Or, you can edit all panels at once in the Zone Editor via the prominent 'Edit in Zone Editor' links. You will probably want to blank out what is already in the files and start them from scratch. At this stage we are not considering style, only content/structure, so consider your block decisions from the first stage but forget about design for now. Place the blocks as appropriate onto your:
   
   • Comcode page: Start page, :start
   • Comcode page: Left panel (if you have one on the design), :panel_left
   • Comcode page: Right panel (if you have one on the design), :panel_right
   • Comcode page: Top panel (if you have one on the design), :panel_top
   • Comcode page: Bottom panel (if you have one on the design), :panel_bottom
   • HEADER: Often there will be blocks in the header, like 'search' or 'login'. You can place these using code like {$BLOCK,block=<blockname>}
   • FOOTER: Similarly sometimes the is a menu in the footer, which can be placed like

     Code

     {$BLOCK,block=side_stored_menu,type=<menu-type>,param=<menu-name>}

» This section is accompanied by a video.

Lots of XHTML template editing

1. Now that the blocks are placed, you need to style them. See the tip to the right for how to find out what templates to edit.
2. Almost all the blocks use the "standard box" templates, by putting {+START,BOX,...} and {+END} around their template (e.g. BLOCK_MAIN_NEWS.tpl does this). A block on a panel uses a 'panel' box which is taken from STANDARDBOX_panel.tpl, and most others use STANDARDBOX_classic.tpl. If you have the same kind of XHTML as boxes around your blocks, try and incorporate it properly into the box template and associated CSS styles. Otherwise, you can remove {+START,BOX,...} and {+END} from the block templates and just code in your box XHTML directly.
3. So you should now have styled blocks on your panels and start page, but they probably aren't joined together in the way you want. So you will probably want to put some work into improving the markup in the panels and start page. Basically you want to get everything in there that you had in your own XHTML that was not itself part of the blocks. As a designer you probably will be writing pure XHTML for your panels and start page (by embedding it within … Comcode tags) rather than trying to translate to Comcode and putting the blocks within that XHTML. That's fine, but there's also a big risk that the final webmaster may come along and ruin it via editing using the WYSIWYG editor. You can disable the WYSIWYG editor for a page by pasting this special comment into it:

   Code

   {$,page hint: no_wysiwyg}

» This section is accompanied by a video.

Last steps

1. It is a good idea to verify your theme is stable across different ocPortal screens. When you defined the global layout and associated CSS it is possible you made some bad assumptions, like assuming fixed width styles can be placed on 'body' (which is bad if ocPortal uses global.css inside an iframe, for example). First do a verification manually by viewing a few screens; good choices are: the forum index, doing a website search, and previewing some changes from an edit form.
2. Next you can verify your theme more formally by using the 'Screen previews' feature from the 'Themes' section of the Admin Zone. It provides details of all screens, and you can check them for how well they work. Don't spend ages on this unless you have made very extensive modifications or the site is going to use a very wide number of default ocPortal features, but at least do some checks on some random selections to give yourself greater confidence.
3. Test your theme for all the major browsers. We suggest specifically testing in: IE8, IE9, Firefox, Google Chrome.
4. You will need to make an e-mail template. If you are making a theme, do this by overriding the MAIL.tpl template into themes/<yourthemename>/templates_custom/MAIL.tpl. However if you are making a website it is absolutely critical you say it into themes/default/templates_custom/MAIL.tpl or otherwise the default e-mail theme and ocPortal branding will be used on many system e-mails or queued e-mails.
5. Also, don't forget to implement a favicon . In ocPortal this is done just as a theme image called 'favicon', so you can override it by making a themes/<yourthemename>/images_custom/favicon.ico file.
6. If you override any existing default theme image manually, such as a favicon, you will need to empty the theme image cache from Admin Zone>Tools>Cleanup Tools.
7. You may also want to check how the website prints, possibly adding some print-overrides into your CSS file (CSS can target printing separately, and the default global.css does already to an extent)

Things you may wonder about

Javascript libraries (such as jQuery)

You may have used some Javascript libraries in your design. jQuery is very common nowadays. You can reference these Javascript resources very simply in the <head> tag just like you would in any simple static website, and it won't cause any problems.

If you are using jQuery you may want to consider linking to the online copy that Google host's, because then visitors will get a faster page load time because it's probably already cached on their computers (because many sites use the same copies). Obviously only do this if your site is always going to be viewed on the live Internet (it's not good for Intranets!).

Placing blocks into templates

You can place a block in a template like:
Where "…" is further parameters.

For an example you can see how it is done for the side_stored_menu block, in the 'Menus' section further down.

Creating page-links

If you are linking to a specific page via a template or some XHTML within a Comcode page (i.e. you're not using an ocPortal menu) you can generate a consistent link to the page like:
"news" is the name of the page being linked to, and "site" is the zone the "news" page is in.
You can usually identify page-links to use from the URL. In this case the URL would be something like:

• http://<yourbaseurl>/site/index.php?page=news
• or, http://<yourbaseurl>/site/news.htm
• or, http://<yourbaseurl>/site/pg/news.

You can see now one reason why we don't hard-code URLs in ocPortal! The URLs can be different, depending on what SEO options are enabled. Page-links also make it easier to use the same code on different domain names.

Escaping ("*" to the right of variable names)

You may wonder why above we put a "*" after calling up ocPortal's PAGE_LINK symbol with a parameter "site:news". It doesn't serve an obvious purpose. What it actually does is makes sure the data is ready for use in XHTML, and we call this "escaping". For example if a URL contains "&" it must actually be written using "&" in the XHTML.

This is actually important for security, if you don't properly "escape" your data it can lead to all kinds of security holes.

Therefore we quite consistently escape our symbols and template parameters, even if we trust them. E.g. we say {$SITE_NAME*} not {$SITE_NAME} if we are embedding the site name into an XHTML template.

ocPortal does not handle this automatically because the conversion carries an assumption, and it is up to you to decide in what context your data is being used (e.g. a Javascript template likely would not want XHTML escaping applied). But in 99% of cases it will need the '*'.

Specific advice for specific situations

New panels / re-used text / content-in-layout

There are three situations that may require you to add new panels to ocPortal, or to add a special content page that is included in another:

1. New panels: most designs use some combination of left/right/top/bottom panels and a header (HEADER template) and a footer (FOOTER template). But it might not always be the case, one could imagine all kinds of complex panel arrangements.
2. Re-used text: It might be the case that some text is used on many pages, so you don't want to keep copy & pasting it.
3. Content-in-layout: Often a design will include some content in the header that the final webmaster might want to edit. If you are your own webmaster it doesn't matter so much, but ideally it's better to give someone the name of a page to edit instead of a template.

The solution to these problems are page/panel inclusion into templates. Any page name that starts with "panel_" is a panel and won't be shown in the site-map. Similarly, any page name that starts with "_" is considered special and won't show in the site-map.
To include a new panel with the page name of panel_<panelname> it is as simple as placing this code into your template:
To include a page named <otherpagename> into another Comcode page you can do something very similar using this in the page being included into:

» This section is accompanied by a video.

Logo wizard

If you want the Logo Wizard to be able to modify your logo, you will need to make a copy of your logo called themes/<yourthemename>/images/logo/logo-template.png but without any site-name or slogan on it. The Logo Wizard will then write it on. If you need the logo wizard to put them in different places to the default ocPortal logo, or to use different colours, you can put the following into your themes/<yourthemename>/theme.ini file:
and customise the numbers until they work.

Menus

You don't want to hard-code sets of links into templates for themes as it's hard to edit, so we suggest you use menus. There are a number of different default menu layout types:

• zone: used at the top of the default theme.
• top: styled to work well as a single-layer horizontal menu. On the default theme it's used on the forums, for example.
• dropdown: a horizontal menu with drop-downs. Used in the Admin Zone, for example.
• tree: a vertical menu. Used by default on panels.
• embossed: a vertical menu, that makes each link look like a button.
• popup: a vertical menu, with pop-outs (the vertical equivalent of a drop-down menu).
• select: a simple XHTML <select> based navigation menu.

The menu layout types are distinguished by their templates. Each menu type has it's own set of templates that includes the name of the menu layout type. The template naming pattern would be MENU_<layouttype>.tpl, MENU_BRANCH_<layouttype>.tpl and MENU_SPACER_<layouttype>.tpl. You can create a new menu layout type just by making a new set of templates (using an existing set as a base), but this is virtually never necessary: it is often easiest just to customise one of the default sets.

You can have as many menus of each layout type as you like. They are placed using the side_stored_menu block.
and in Comcode like:
Where <name> is something that identifies the particular menu instance, holding together the links in that particular menu instance. You can just make the <name>s up, and you'll get a new empty menu each time you do. If you're making a theme it's best to try and use default pre-existing menu names so that the default links are immediately available in your theme.

Catalogues (for custom content types)

When you have a custom content type to add (something that there isn't a specific ocPortal feature for, such as "Project Staff" or "Representatives" on making_a_theme.pdf), you'll need to make a catalogue. Decide what fields you want then add the catalogue from the 'Content Management' zone.

You will probably want to have a non-tree catalogue, with a display type of 'field-maps' (these can be changed later if needed).

When you have added the catalogue you will need to add a category to it, and then add at least some test entries to that category.

Catalogue templating

For this example, we will assume you are trying to show off the catalogue via a block in your design, rather than an individual page.

Use the main_cc_embed block to embed the catalogue (the Add Block tool can add this for you, and it will help you select your catalogue category).

The default catalogue templates are very formulaic in their arrangement of content. This is because they know nothing about the content and thus just display it consistently according to the catalogue's display type (tabular, field-maps, or list). If you want full layout control you should use a display type of 'field-maps' for your catalogue and then you can place/style each field individually. Before we do this though, we need to override the catalogue templates for our individual catalogue.

To do this copy the following templates and edit the copies (for this example I am assuming your catalogue has the codename 'project_staff'):

• CATALOGUE_DEFAULT_CATEGORY_EMBED –> CATALOGUE_project_staff_CATEGORY_EMBED
• CATALOGUE_DEFAULT_ENTRY_EMBED –> CATALOGUE_project_staff_ENTRY_EMBED
• CATALOGUE_DEFAULT_ENTRY_FIELD –> CATALOGUE_project_staff_ENTRY_FIELD

(by overriding catalogue templates to a particular catalogue name we can make changes without interfering with how other catalogues look)

Each individual field is passed into the main template (for the case of the main_cc_embed block, it is CATALOGUE_project_staff_CATEGORY_EMBED), with names like {FIELD_0} etc (this is the first field). {FIELDS} is the formulaic arrangement and you'll probably want to remove it.

If you're not sure what parameters are available to use in a template you can add this code temporarily:
And this will show a full print out of all the parameters available to you. Often it's hard to read this if you don't have a lot of space in your design at the time of you putting this in, but you can copy and paste it out to a word processor to keep it for reference. For example you may want the URL or the parameter for the IMG tag and these can both be found in this way.

» This section is accompanied by a video.

Complex content arrangements

Sometimes a design will have what looks like a panel but actually only appears on the start page. For example, there might be an obvious page area, panels either side of the page area, and an obvious header, but also a bar that goes above the panels and is only shown for the start page. The best way to implement this is by actually making it a panel (panel_top) but putting some special code in there to make it only show for the start page. You can do this with the following code:

» This section is accompanied by a video.

Development/debug mode

If you are developing from a subversion checkout (you'll know if you are) then your install will be in development/debug mode. The main thing you will notice is that invalid XHTML will often create very nasty error screens in the browser. This is an intentional feature, as we throw ocPortal into this mode for developers so that bugs cannot go unnoticed and to ensure we write proper XHTML. On live sites we don't have development/debug mode on because it is inevitable that bad XHTML will leak in, and many versions of Internet Explorer can't support proper XHTML mode anyway.

One problem though is some third-party code won't work with XHTML. For example, we have observed that Google Maps cannot. To disable XHTML you can manually/temporarily add this to the end of the URL: &keep_no_debug_mode=1. This will carry through with any links you click.

Proceeding to build a real site

If you are not just making a theme, but a whole site, you will need to do some of the following also:

1. Add all your real content
2. Edit the menus in the theme, to place the real final links
3. If a page does not exist in the standard ocPortal then the page needs to be created. The menu can link to non-existing pages (so make up a name for the "Link" field, like "my_new_page") and when this menu item is clicked it shows an error that the page doe not exist and also gives an option to add this page. Once the page is added, this can be edit it like any other Comcode page.
4. Install any non-bundled addons you need, such as the Google Maps addon
5. If you have used completely new theme images inside content, such as Comcode Pages or catalogue entries (using in your own theme's CSS or templates is fine) then you actually want these theme images to be defined inside the default theme rather than your own theme. This is because theoretically any theme could need to use these images, not just your one. So for each of these "content theme images" move themes/<yourthemename>/images_custom/<yoursitename>/<example> to themes/default/images_custom/<yoursitename>/<example>.

Internationalisation

ocPortal has excellent support for multiple languages. You may have noticed how Comcode pages (including panels) are located in 'EN' folders. If other language packs are installed there are folders for other languages, so that you can have a different copy of each Comcode page for each language.

There is a block that contains a drop-down list for switching languages, the side_language block. Often a design will put neat little flag icons on, in which case you need to put this code as the href of your link (this example if for a French flag icon): {$SELF_URL*,0,0,0,keep_lang=FR}. The keep_lang URL parameter will be added to the current URL via this link, and ocPortal will keep passing it through for any further clicks.

You will need to ensure you don't put English text into your templates. To avoid this you need to use "language strings". Let's pretend you have this text in a template:

Designed by BigBoy designs

to internationalise it you would need to create a named language string. We'll pick a name that represents the text. In this case, DESIGNED_BY_TEAM. We would replace the text with {!DESIGNED_BY_TEAM,BigBoy designs} and add this to the lang_custom/EN/global.ini file (create this file if it des not already exist):
Do you see how we passed in a bit of constant text to the phrase that would not be translated ("BigBoy designs") and embedded it via {1}? By doing this we avoid assuming word-order, because some languages order words in different ways.

To make a French version of this string, we would simply add this to lang_custom/FR/global.ini:

All ocPortal content can be translated, so you don't need to worry about things like menu items. The content text can be translated by the site team from the Admin Zone via a prioritised translation queue.