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

Moving forward with Composr

ocPortal has been relaunched as Composr CMS. ocPortal 9 is superseded by Composr 10.

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

ocPortal Tutorial: Running advertisements (via the banner system)

Written by Chris Graham, ocProducts
Thumbnail: A banner

A banner

A system for 'rotating' a collection of stored banners is provided. The system is designed to be flexible, such that it can serve a number of different purposes, including:
  • serving banners directly from a banner network, via the HTML they provide for you to include in your site
  • serving your own network of banners (perhaps paid banners, or perhaps community banners)
  • serving community banners, bought via the point-store
  • creating a community banner network between independent sites, where sites get as many views/clicks out as they provide in

Managing your own banner rotation

Thumbnail: Adding a banner

Adding a banner

There are many options to allow a rich and flexible rotation system. These include:
  • The deployment agreement. A permanent banner can always be shown. A campaign banner is given a finite number of 'clicks', and will not be shown when the clicks have run out (although that number is editable). Default banners can always be shown, but are generally set to only appear when there are no permanent or campaign banners.
  • You may specify a banner type. Types are set up to enforce certain restrictions (image dimensions, and file size) on the banners within that type. It is possible to call up the ocPortal banner.php with '?b_type=<type>' on the URL, which will force only banners of that type to be shown. Likewise, the 'BANNER' symbols first parameter can be set to <type> (e.g. {$BANNER,skyscraper}). This is useful for a number of things, but perhaps the most significant is that is allows you to distinguish between banners of different sizes, storing each in an effectively separate rotation. You can then edit your templates to reference these different rotations, by pasting in the appropriate HTML (see BANNER.tpl for an unfiltered example – this is the HTML used for the banner that appears in the top-right by default).
  • Banners may be given an expiration date; this is useful in many situations, such as if a banner becomes inappropriate after an advertised event finishes, or if a client has only paid until a certain date.
  • The 'importance modulus' allows you to balance the likelihoods of different banners being shown. It is not a percentage or fraction, but a high number (higher than other banners are given on average) should be given to a banner that is more likely to be shown.

Important note: The campaign banner system allows a hit-balancing system, whereby the site the banner is for may show your network banners itself, and for each click they put into your network, they get an extra click out.

More on balancing banners

All banners are balanced against each other by an attribute known as the 'importance modulus', which is defined for every banner. The banner with the highest importance level is the one most likely to get shown. As new banners are added, importance modulus of banners will be needed to be adjusted higher if they're chance of being shown is required not to go down; this would be at the detriment of the banners you did not adjust the importance levels of.

In other words, the importance modulus is not a chance of a banner being shown, but only a balancing factor. If you have 900 banners with importance 1, then a banner with importance modulus 100 has a 10% chance of being shown.

The system will show permanent and campaign banners as a 50:50 split. Default banners can appear instead of either though, but only according to their importance level.

Supported file types

The banner system supports 4 different broad categories of file type:
  • images
  • flash (swf format)
  • text
  • urls (which are shown using frames)
  • pure HTML
  • HTML, with support for embedded PHP code


You can add textual banners, which by default look exactly like Google Text ads. The best thing though is that you can set them to be 'hot text', which means that any Comcode will be scanned for use of the keywords, with matches leading to inline display of the text banners.


If you specify a URL to a script (such as the URL to another ocPortal installation's banner.php) instead of an image, then that script will be loaded in a frame, and is assumed to provide its own rotation inside that space. Because of this, only the script URL is required in place of the image URL, and the actual 'URL' field may be left blank and will be ignored (as the linked rotation provides these itself).

Linking to non-image URLs instead of images is handy in a number of situations, including:
  • if you want to chain banner networks together
  • if you want to link to a textual banner
  • if you want to make a page that displays a randomised banner based on some kind of algorithm (such as choosing randomly from a folder of pictures)

Using a banner network's HTML

Thumbnail: Configuring the HTML to an external banner/rotation

Configuring the HTML to an external banner/rotation

In order to use banners from an existing banner network, you often are asked to incorporate a chunk of HTML into your site. ocPortal makes this easy for you, as you can add banners consisting of raw HTML (or even PHP code).

If you are using Google Adsense and don't see any banners, consider whether your account is set up correctly.

Banners are shared on a site network using an iframe going to a URL like:
This code is given out when you add a banner. The 'source' comes from the name of the banner you added, which for purposes of a banner network, is considered also as the name of the site also showing banners in the network. A source site won't be shown its own banners. If you wish you may just strip out the source parameter if you don't need such a restriction – if, for example, you are just using the banner sharing code all within your own site.


Who may view what

If you turn on the "Permissions" option (under the "Banners" section in the Feature options category of the Admin Zone configuration), you'll be able to configure which usergroups may view which individual banners. This is useful for banner targeting – and the flip side of that is you can avoid showing inappropriate banners, e.g. adults banners to minors.

Who may avoid banners

Any usergroup with the "Avoid banners" permission will not see banners. Super administrators will have this permission (as they always have all permissions), and hence super administrators will never see banners. To test banners from a super administrator account (such as the default 'admin' account), use the 'SU' feature to switch to the test account: add &keep_su=test onto the end of a URL.

Banner status

Thumbnail: Viewing the status of a banner

Viewing the status of a banner

There is a facility for staff and banner submitters to view the status of their banner. Information about how much the banner has been viewed and clicked is shown, as well as the equivalent statistics for how the banners associated website (if there is one) has viewed and clicked the banner network.

The details shown may have important statistical significance. For example, a banner that is viewed a lot, but never clicked, may not be a 'profitable' one to have in the rotation (note however, that a simple banner view could impact a visitor, and thus it actually being clicked is not always a measure of the user impact).

Having multiple banner sets

You may have multiple sets of banners, determined by the 'Type' of the banners. A banners 'Type' defines what set it goes in.

Each of these sets may be called up as a separate rotation, displayed in a different place, and it is often useful as a convention to use sets to group together those banners that have the same width and height.

To set up a new rotation, displayed in the layout in a space of your choosing, use the following instructions.

a) Copy this code from the GLOBAL_HTML_WRAP template:


   {$SET,BANNER,{$BANNER}} {$,This is to avoid evaluating the banner parameter twice}
      <div class="global_banner" style="text-align: {!en_right}">{$GET,BANNER}</div>

b) Change this bit of the above:




Where 'example' is changed for whatever type string you've used for the banner set you want to show.

c) Change the global_banner CSS class used in the code snippet to a new CSS class of your own choosing (or just pull it out if you don't require any special styling around your banner).

d) Place the code in any template you like (or multiple ones). Obviously you'll need to write it in in such a way as for it to fit well into the layout. This is a standard CSS/XHTML themeing issue.

The Point Store

If you wish to use your banner space, in part of full, for showing banners that your community want, then you may wish to enable the Point Store, to allow members to buy banners using points.

More information on the Point Store is provided in the 'Creating an economy/reward-system for members via points' tutorial.

Alternatively, or in conjunction with the Point Store, members may simple submit banners, and you may choose to validate them without requiring the members to spend points.


If banners won't show check:
  1. Banners are enabled in the configuration.
  2. You are not viewing as a super-administrator or any other usergroup that has 'Avoid banners' permission.
  3. Your banner is validated.
  4. Your banner has not expired.
  5. Your banner has hits assigned, is a permanent banner, or is a default banner and there aren't non-default banners obscuring it.
  6. That the banner type your banner is in is displayed (by default only the default 'General' banners are displayed, in the GLOBAL_HTML_WRAP.tpl template). See "Having multiple banner sets".
  7. The banner type has permissions for the viewer's usergroup.
  8. The "Community advert chance" configuration option is not set to zero.


Default banner
A banner that is displayable at any time (i.e. both when campaign and permanent banners would be chosen for viewing), but is intended to have a low importance level such that it is shown when the system is low on banners
Campaign banner
A banner that has a limited number of hits, but with support for hit balancing should the banner be tied to a site that is generating banner network clicks
Importance modulus
A number representing the how likely a banner is to be shown, releative to the other importance moduli (in essence, they are ratios to each other of how likely the banner will be shown)
Hit balancing
A feature that allows a banner network to be created such that banners get as many hits out of the system as their sites put clicks into the system
An advertising banner

See also