ocPortal Tutorial: Specific templates and CSS classes

Written by Philip Withnall, ocProducts

This tutorial details some of the templates and CSS classes used by ocPortal. It is not a definitive reference by any means, but is intended to demonstrate by example how templates and CSS classes are used.

Table of contents

ocPortal Tutorial: Specific templates and CSS classes

Primary templates

`BASIC_HTML_WRAP`

BASIC_HTML_WRAP is used for stand-alone outputted pages, such as the uninstaller, banners (for iframes) and author lists. It contains only basic markup with no styling, and accepts the following parameters:

TARGET: a target for the <base /> element
TITLE*: the page title (will be HTML-escaped)
CONTENT: the page content

Similarly there is STYLED_HTML_WRAP and POPUP_HTML_WRAP.

`COMCODE_PAGE_SCREEN`

COMCODE_PAGE_SCREEN is the wrapper for any Comcode page. Most of the markup in this template is for administrative purposes only, but you can add your own markup to change the appearance of Comcode pages. It accepts the following parameters:

WARNING_DETAILS: any warning to be displayed on the Comcode page
CONTENT: the actual page content, parsed from the Comcode
SHOW_AS_EDIT: a boolean value for whether to show the last date the Comcode page was edited
EDIT_DATE_RAW: the raw date (i.e. timestamp) at which the page was last edited (it is normally converted to a pretty date using the {$DATE,...} Tempcode function)
EDIT_URL*: the URL where the Comcode page can be edited (will be HTML-escaped)
NAME*: the name of the Comcode page (will be HTML-escaped)

`FOOTER`

FOOTER holds the markup for actually closing the page (i.e. the </html>).

`FORM`

FORM wraps almost every form in the system (apart from a few special cases such as the shoutbox and OcCLE). It provides Javascript input validation, warnings about required fields and an introduction. There are many template related to forms in ocPortal, and they all begin with "FORM_"; there isn't room to list or describe them here, but if you're completely re-theming ocPortal you might want to take a look at them. This template accepts the following parameters:

TEXT: the introductory or explanatory text to display at the top of the form
REQUIRED_NOTICE: a boolean value for whether to show the "required fields" notice
POST_URL*: the URL to which the form contents will be posted
HIDDEN: the hidden fields
FIELDS: the fields to display
SKIPPABLE: if passed, the form will be skippable, and the value of this parameter will be used as a unique identifier

`FORM_SCREEN`

FORM_SCREEN is used instead of the normal FORM template if the form's the only thing on the page. It accepts the following parameters:

TITLE: the page title
WARNING_DETAILS: any warning to be displayed on the page
TEXT: the introductory or explanatory text to display at the top of the page
SKIP_REQUIRED_NOTICE: a boolean value for whether to skip the "required fields" notice (note that this is the converse of the REQUIRED_NOTICE parameter for the FORM template)
IFRAME_URL*: the URL to which to submit the form contents if using the iframe results system; don't pass it if you want to submit the form normally (will be HTML-escaped)
POST_URL*: the URL to which to submit the form contents if submitting the form normally (will be HTML-escaped)
HIDDEN: the hidden fields
FIELDS: the fields to display
SKIPPABLE: if passed, the form will be skippable, and the value of this parameter will be used as a unique identifier

`FORM_SCREEN_FIELD`

FORM_SCREEN_FIELD is a generic wrapper for fields in a form. It is provided with a specific input element (such as a textbox or checkbox), and wraps it with the label, description, required warnings, and so forth. It accepts the following parameters:

BORING_NAME*: the name with which the input is referred to; it has to be a valid ID (will be HTML-escaped)
NAME*: the human-readable name for the form field, displayed as the label (will be HTML-escaped)
REQUIRED: a boolean value specifying whether the field is required
COMCODE: the markup for the Comcode link to display, if appropriate
SKIP_LABEL: a boolean value specifying whether to skip the hidden accessibility label
DESCRIPTION: the description for the form field

`GLOBAL`

GLOBAL is the main template: it is used for all pages, and encompasses all other templates. It accepts the following parameters:

BREADCRUMBS: the breadcrumb trail for the top of the page
HELPER_PANEL_TUTORIAL*: URL to a tutorial on the current page (will be HTML-escaped)
HELPER_PANEL_PIC: the name of the image to display as the background to the helper panel
HELPER_PANEL_HTML: HTML to display in the helper panel
HELPER_PANEL_TEXT: text to display in the helper panel
MESSAGE_TOP: message to display at the top of the page
MIDDLE: the actual main page content
MESSAGE: message to display at the bottom of the page

`HEADER`

HEADER is the template containing the opening markup for the page, including the DOCTYPE and XML header. It accepts the following parameters:

HEADER_TEXT*: the text to display as a secondary message in the browser titlebar (will be HTML-escaped)
DESCRIPTION*: the page's meta description (will be HTML-escaped)
KEYWORDS*: the page's meta keywords (will be HTML-escaped)
CHARSET: the current charset
REFRESH: any meta refresh markup
DEFERRED_ERRORS: any deferred error messages (passed as a linear array)
ZONES: array of zones, containing CODE* (will be HTML-escaped) and TITLE for each zone, to display in the zone bar
LOGO_URL*: the URL to the site's logo (will be HTML-escaped)

`INDEX_SCREEN`

INDEX_SCREEN is a general-purpose page structuring template, providing for an introduction, content (a list of available actions), and a post-content section. It accepts the following parameters:

TITLE: the page title
PRE: the introduction section content
CONTENT: the main page content (typically a list of INDEX_SCREEN_ENTRY templates for available actions)
POST: the post-content section content

`INDEX_SCREEN_ENTRY`

INDEX_SCREEN_ENTRY is one entry to be used in INDEX_SCREEN. A list of INDEX_SCREEN_ENTRY templates should be built up using attach, and used as the CONTENT parameter for INDEX_SCREEN. It accepts the following parameters:

URL*: the URL of the action (will be HTML-escaped)
NAME*: the name for the link (will be HTML-escaped)

`JAVASCRIPT`

JAVASCRIPT is used as the main Javascript available on any screen. New Javascript should not be added to this file though as this file is often changed across patch versions (new global Javascript should be added to JAVASCRIPT_CUSTOM_GLOBALS), unless it's too specific to be loaded/available everywhere. It takes no parameters.

`MAIL`

MAIL is used as the HTML wrapper for e-mails sent by the system. It is fully styled and structured like a normal ocPortal page. It accepts the following parameters:

LANG*: the language in which the e-mail is being sent (will be HTML-escaped)
TITLE*: the title/subject matter of the e-mail (will be HTML-escaped)
CSS: the CSS to style the e-mail
LOGOMAP: the logo or imagemap for the site logo
CONTENT: the content of the e-mail

`MEDBORDER_BOX`

MEDBORDER_BOX is for a box with a medium border, similar to the STANDARDBOX. It accepts the following parameter:

CONTENT: the content to be displayed in the box

`MENU_`

The MENU_ prefixed templates define the markup for ocPortal menus. Each menu type has its own sets of the following templates:

MENU_* wraps the menu type
MENU_BRANCH_* is for a branch of the menu
MENU_NODE_BRANCH_* is for a node branch (a branch which can contain other branches). It will always be contained within a MENU_BRANCH template via that templates 'CONTENT' parameter.
MENU_SPACER_* is for a spacer item
MENU_CURRENT_PAGE_* is for marking up a current page (non-current pages just go directly through HYPERLINK, whilst current pages go through both via nesting)

`MESSAGE_SCREEN`

MESSAGE_SCREEN is used to display a message to the user as a standalone page (e.g. a harmless message, not an error message). It accepts the following parameters:

TITLE: the page title
TEXT*: the text to display as the message (will be HTML-escaped)

`MISTAKE_SCREEN`

MISTAKE_SCREEN is used to display a page highlighting your mistake with a back button (e.g. a Comcode error page). It accepts the following parameters:

TITLE: the page title
TEXT*: the text to display as the message (will be HTML-escaped)

`OCF_FORUM`

OCF_FORUM wraps around a forum or virtual forum display in OCF. It accepts the following parameters:

FILTERS: a list of applicable filters, used in virtual forums (e.g. personal topics)
CATEGORIES: the categories to display in this forum
BUTTONS: the buttons to display below the categories
TOPIC_WRAPPER: the topics to display in this forum

`OCF_FORUM_CATEGORY`

OCF_FORUM_CATEGORY wraps groups of sub-forum links into categories, to be displayed at the top of the forum listing. It accepts the following parameters:

CATEGORY_ID*: the ID of the category (will be HTML-escaped)
EXPAND_TYPE*: whether the category is expanded or contracted; the name of the image to display (will be HTML-escaped)
CATEGORY_TITLE*: the title of the category (will be HTML-escaped)
CATEGORY_DESCRIPTION*: the category description, if applicable (will be HTML-escaped)
DISPLAY*: the value for the CSS display property for the category (will be HTML-escaped)
FORUMS: the forums in the category

`OCF_FORUM_IN_CATEGORY`

OCF_FORUM_IN_CATEGORY is used for each forum inside a OCF_FORUM_CATEGORY template. It accepts the following parameters:

NEW_POST_OR_NOT*: whether there's a new post; the name of the image to display (will be HTML-escaped)
FORUM_URL*: the URL of the forum (will be HTML-escaped)
FORUM_NAME*: the forum name (will be HTML-escaped)
EDIT_URL*: the URL to edit the forum (will be HTML-escaped)
DESCRIPTION: the forum description, if applicable
SUBFORUMS: a list of the forum's subforums, if applicable
NUM_TOPICS*: the number of topics in the forum (will be HTML-escaped)
NUM_POSTS*: the number of posts in the forum (will be HTML-escaped)
LATEST: the details of the latest post in the forum

`OCF_GUEST_BAR`

OCF_GUEST_BAR is the guests' equivalent of OCF_MEMBER_BAR, and is displayed in the same place. It accepts the following parameters:

NAVIGATION: markup for zone navigation
LOGIN_URL*: the URL to which the login form should be submitted (will be HTML-escaped)
JOIN_LINK*: the URL for the join page (will be HTML-escaped)
FULL_LINK*: the URL for the full login page (will be HTML-escaped)

`OCF_MEMBER_BAR`

OCF_MEMBER_BAR is used to display the "personal bar" in OCF, if the member has it configured in wide mode (i.e. no side panels). The personal bar displays all their pertinent information and links (point count, post count, personal topics, etc.) in one bar at the top. It accepts the following parameters:

AVATAR*: the URL of the member's avatar, if applicable (will be HTML-escaped)
PROFILE_URL*: the URL of the member's profile (will be HTML-escaped)
USERNAME: the member's username
LOGOUT_URL*: the logout URL (will be HTML-escaped)
NUM_POINTS_ADVANCE*: the number of points the member needs to advance to the next usergroup (will be HTML-escaped)
NUM_POINTS*: the number of points the member has (will be HTML-escaped)
NUM_POSTS*: the number of posts the member has (will be HTML-escaped)
PRIMARY_GROUP*: the member's primary usergroup (will be HTML-escaped)
LAST_VISIT_DATE*: the last date on which the member visited (will be HTML-escaped)
NEW_TOPICS*: a link to the new topics since the member last visited (will be HTML-escaped)
NEW_POSTS*: a link to the new posts since the member last visited (will be HTML-escaped)
PERSONAL_ZONE_URL*: the URL of the member's personal zone (will be HTML-escaped)
MEMBER_LINKS: a list of links for the member
PERSONAL_TOPIC_URL*: the URL of the member's personal topic virtual forum (will be HTML-escaped)
PT_EXTRA: lists personal topic activity, if applicable
NEW_POSTS_URL*: the URL for the new posts since the member last visited (will be HTML-escaped)
UNREAD_TOPICS_URL*: the URL for the member's unread topics (will be HTML-escaped)

`OCF_TOPIC_POST`

OCF_TOPIC_POST contains a single post in a topic in OCF, including the poster's details, and the moderation buttons along the bottom. It accepts the following parameters:

POST_TITLE*: the title of the post, if applicable
CLASS*: the CSS class to apply to the post (will be HTML-escaped)
EMPHASIS*: the markup to apply to the post if it's emphasised (will be HTML-escaped)
ID*: the post ID (will be HTML-escaped)
FIRST_UNREAD: the markup to apply to the post if it's the first unread post in the topic
POST_DATE*: the date and time at which the post was made (will be HTML-escaped)
UNVALIDATED*: the markup to apply to the post if it's non-validated (will be HTML-escaped)
POST_URL*: an URL pointing to the post, including an anchor reference (will be HTML-escaped)
POSTER: the poster's name, and markup for details on hovering over their name
POST_AVATAR: the poster's avatar
POSTER_TITLE: the poster's title
RANK_IMAGES: the poster's rank images
POST: the actual post content
LAST_EDITED: when the post was last edited, if applicable
SIGNATURE: the poster's signature
BUTTONS: the moderation and reply buttons to display

`OCF_TOPIC_WRAP`

OCF_TOPIC_WRAP wraps all the posts in the topic view of a topic on OCF. It displays all the surrounding control functions, buttons, and viewer listings. It accepts the following parameters:

PAGE_BUTTONS: the buttons (such as "new topic" and "reply") to display at the top and bottom of the page
POLL: the poll markup, if applicable
RESULTS_BROWSER: the results browser markup (page navigation)
POSTS: the actual posts
NUM_GUESTS*: the number of guests viewing the topic (will be HTML-escaped)
NUM_MEMBERS*: the number of members viewing the topic (will be HTML-escaped)
MEMBERS_VIEWING: a list of member names viewing the topic
MODERATOR_ACTIONS: the markup for the moderation actions (a list of option tags to be placed inside a select)
ACTION_URL*: the URL to which moderator and marked post actions should be submitted (will be HTML-escaped)
MARKED_POST_ACTIONS: the markup for the marked post actions (a list of option tags to be placed inside a select)
TREE: the breadcrumb forum hierarchy navigation tree
QUICK_REPLY: the quick reply box

`OCF_WRAPPER`

OCF_WRAPPER is used to wrap all pages in OCF. It accepts the following parameters:

TITLE: the page title
HEAD: the page header (usually the personal bar, if the user has it configured in wide mode)
NOTIFICATIONS: any notifications to be displayed (personal topic replies, etc.)
CONTENT: the page content
FOOT: the page footer (OCF statistics)

`PAGE_TITLE`

PAGE_TITLE is used to display the title for a page (not in the browser title bar). It accepts the following parameters:

ID*: the ID for the title element (will be HTML-escaped)
TITLE: the title text
HELP_URL*: the URL for a linked help document (will be HTML-escaped)
HELP_TERM*: the term to use as an anchor in the help document (will be HTML-escaped)
SUB: a subtitle, displayed below the main title

`POSTING_FORM`

POSTING_FORM is used for standard submission forms with Comcode content, attachments, etc. It accepts the following parameters:

POST_URL*: the URL to which to send all the form contents (will be HTML-escaped)
DEFAULT_PARSED*: a pre-parsed version of the Comcode for the post (will be HTML-escaped)
HIDDEN_FIELDS: any hidden fields to put in the form
SPECIALISATION: fields to be prepended to the form
POST_COMMENT*: help on how you should post (will be HTML-escaped)
COMCODE: the Comcode message ("this is Comcode-enabled") and WYSIWYG toggler
COMCODE_EDITOR: the markup for the standard Comcode WYSIWYG editor
CLASS*: the CSS classes to use for the Comcode editor (will be HTML-escaped)
POST*: the default post content
EMOTICON_CHOOSER: the emoticon chooser markup
SPECIALISATION2: fields to be appended to the form
HELP*: help for the form to be displayed underneath (will be HTML-escaped)
ATTACHMENTS: any pre-existing attachments to be displayed on the form
EXTRA: any extra markup or text to attach to the bottom of the form

`RESULTS_BROWSER_WRAP`

RESULTS_BROWSER_WRAP wraps results browsers, which are appended to multi-page content to standardise navigation, sorting, and jumping to pages. It accepts the following parameters:

PER_PAGE: a form allowing the user to specify how many results should be displayed per-page
PART: the markup for the navigation, sorting, and page jumping functions

PART is built up as follows:

RESULTS_BROWSER_PREVIOUS_LINK if there are previous pages, RESULTS_BROWSER_PREVIOUS if there are not (for the "previous" link)
RESULTS_BROWSER_CONTINUE if there are too many pages to list
Combinations of RESULTS_BROWSER_PAGE_NUMBER and RESULTS_BROWSER_PAGE_NUMBER_LINK for the page links
RESULTS_BROWSER_CONTINUE_LAST for the "last" link if there are too many pages to list
RESULTS_BROWSER_CONTINUE_FIRST.tpl for the "first" link if there are too many pages to list
RESULTS_BROWSER_NEXT_LINK if there are more pages, RESULTS_BROWSER_NEXT if there are not (for the "next" link)
RESULTS_BROWSER_LIST_PAGES if there are too many pages to list

`RESULTS_TABLE`

RESULTS_TABLE is used for presenting tabulated results with sorting, to the user. It accepts the following parameters:

FIELDS: the actual table rows for the entries (RESULTS_TABLE_ENTRY)
MESSAGE: the introduction/explanatory message to display at the top
FIELDS_TITLE: the header cells for the table
SORT: the markup for the sorting form
BROWSER: the markup for the browser

`RESULTS_TABLE_ENTRY`

RESULTS_TABLE_ENTRY is the markup surrounding a row in a results table. It accepts the following parameter:

VALUES: the cells in the row

`RESULTS_TABLE_FIELD`

RESULTS_TABLE_FIELD is the markup for a cell in the results table. It accepts the following parameter:

VALUE: the cell content

`RESULTS_TABLE_FIELD_TITLE`

RESULTS_TABLE_FIELD_TITLE is the markup for a header cell in a results table. It accepts the following parameter:

VALUE*: the header title (will be HTML-escaped)

`RESULTS_TABLE_FIELD_TITLE_SORTABLE`

RESULTS_TABLE_FIELD_TITLE_SORTABLE is the markup for a sortable header cell in a results table. It accepts the following parameters:

SORT_URL_ASC*: the URL which will sort the table content in ascending order (will be HTML-escaped)
VALUE*: the header title (will be HTML-escaped)
SORT_URL_DESC*: the URL which will sort the table content in descending order (will be HTML-escaped)

`RESULTS_TABLE_SCREEN`

RESULTS_TABLE_SCREEN is a wrapper for a results table, used when it's the only thing on the page. It accepts the following parameters:

TITLE: the page title
RESULTS_TABLE: the results table markup

`STANDARDBOX_*`

STANDARDBOX_* templates are all different variations on the standard box: the box seen all through ocPortal containing and separating various pieces of information. They all accept the following parameters:

WIDTH*: the width (in CSS syntax) of the box (will be HTML-escaped)
HEIGHT*: the height (in CSS syntax) of the box (will be HTML-escaped)
TITLE: the title for the box
META: an associative array of meta values to display
CONTENT: the content to display in the box
LINKS: an array of action links to display at the bottom of the box

`YESNO_SCREEN`

YESNO_SCREEN is used to display a standard "yes/no" prompt to the user. It accepts the following parameters:

TITLE: the page title
TEXT: the question or prompt
URL*: the URL to which the answer should be posted (will be HTML-escaped)

Primary CSS classes

The following are all in global.css:

.global_top is used to style the top section of the page, containing the logo and zone menu
.global_title surrounds the page title and the breadcrumb area
.global_middle is the middle section of the page, containing the actual content
.global_side is used for both side panels, and thus contains no positional styling
.global_helper_panel is used for the helper panel container, but none of the content (that's styled by other classes)
.global_message surrounds any notifications at the bottom, including the standardboxes in which they are contained
.global_notification styles the actual body of each notification
.standardbox_* styles are used in the three varieties of standardbox: classic (a box), panel (for use in panels) and curved (a box with curved corners). There are many standardbox classes, mainly due to the wide variety of situations in which standardboxes have to be used (with/without title, wrapped/unwrapped, internally/externally), but most of them won't need changing
.lightborder is a modifier style, which can be used on all sorts of things, and basically gives them a lighter border and background colour
.dottedborder is also a modifier style, but is mainly used for forms, and uses a dotted border, which helps link cells together
.medborder is another modifier style, similar to .lightborder (the two can be used interchangeably)
.solidborder is the last modifier style, and separates items more finally than any of the others – it too can be used on any element