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: The ocPortal programming framework

Written by Chris Graham, ocProducts
Thumbnail: ocPortal has a well documented API (code)

ocPortal has a well documented API (code)

ocPortal is not just a web application, but also a programming framework. ocPortal defines a very large, fully documented, API, and has numerous mechanisms for the addition of code. Programmers are able to cleanly extend or override any aspect of the system, to enhance ocPortal or bend ocPortal in any area necessary.

It should be noted that ocPortal can be heavily customised without any programming, via editing the templates, but this will mostly only adjust layout and appearance, rather than adding-to or modifying ocPortal behaviour.

It is also important to note, that programming tasks are inherently technical, and requires some combination of some of these elements:
  • education
  • experience
  • a technical mind

Thumbnail: ocPortal has a well documented API

ocPortal has a well documented API

There is nothing we could do to change this, as it is just the unavoidable nature of the work. Wherever possible we make things abstract (such as Comcode page s, or Catalogue s) so users with specific needs do not need to hire-in-help or learn programming to fulfil them.

Open source

ocPortal is Free Software and Open Source, meaning it's completely open and customisable.

The ocPortal API

Every function in ocPortal is documented using a system based on phpdoc (itself based on 'javadoc'). One purpose in this documentation is that it makes it easy for a programmer to program for ocPortal: they have a few hundred fully documented ocPortal functions available to them.

With phpdoc and the function header-line itself, every function has the following:
  • A description
  • A list of all parameters
    • The code-name of the parameter
    • The type of the parameter (including whether false [~type] or NULL [?type] values are accepted)
    • A description of the parameter
    • Whether the parameter is optional
  • The return type (if any), and a description of it
Of course, the actual function code is also available. All this information is presented as a part of the API guide which is precompiled using phpDocumentor. We also have the Code Book which includes a lot of additional information about programming for ocPortal, and is one of the actual sources of information for ocProducts staff; it includes a lot of important and expert information, including guidelines for writing secure code.

Extending ocPortal

ocPortal is not just a lump of code like most software: a lot of effort has gone into structuring the system so that code may be cleanly hooked in, via various methods.

These methods include:
  • Overriding of existing source files with modified versions. Every directory that holds effective source code (as opposed to the shell files such as index.php or dload.php that just provide entry points into ocPortal) support a system of overriding: in other words, every ocPortal source code file can be replaced with a customised version, cleanly, without damaging the existing code and without the changes getting buried. This is done via elevation of a file to a _custom suffixed directory of where the file originally was
  • An ocPortal editor (the code editor) is provided to provide a simple (password protected) editor for your site, and does this automatically
  • New Module s can be added just by writing a file and placing it in the modules_custom directory for the zone that it is to run in. In addition, there is support for a simple form of module, called a Mini-module that can be added in a similar way, but is much easier to write for amateur programmers
  • New Block s can be added just by writing a file and placing it in the sources_custom/blocks directory. In addition, there is support for a simple form of module, called a 'mini-block' that can be added in a similar way, but is much easier to write for amateur programmers
  • New API source code files can be added just by writing a file and placing it into the sources_custom directory
  • 'Hooks' to add features into a hooked area can be written. For example, a 'search hook' can be written by writing a file and placing it into the sources_custom/hooks/modules/search directory

An example of a new module

Thumbnail: ocPortal templates for the tester mod

ocPortal templates for the tester mod

As a part of testing ocPortal 2.5 (along time ago now), we wrote a new custom module that provided a quick way for all testers and developers to progress for the testing/bug-fixing process in a collaborative fashion. The module allowed the addition of tests, and assigning of those tests to members in a testing usergroup. It had a security system, so that non-testers could not access the system, and so that security could be defined to determine which testers had write access to edit tests. It also had forum integration, so that bug report topics could automatically be created and associated with a test.

Thumbnail: ocPortal language files for the tester mod

ocPortal language files for the tester mod

All this was done, without touching the core ocPortal code. The ocPortal API made all the integration (security, members, usergroups, forum topics, etc) very easy. It is not the intent of this tutorial to explain exactly how this module was written, but some screen-shots have been attached to illustrate where new files were created in order for it to work.

The process of writing the module went along this basic route:
  1. The functionality of the module was decided upon, and tests designed that would allow us to test all this functionality worked once the module was finished (we usually define tests first, write a module in one go, and then carry out all the tests: it usually is the most efficient and robust way for us to write the code)
  2. The database schema was designed for the module, by consideration and then simply listing of the tables and fields that would be needed to adequately (and consistently with our standards and the guidance of our expertise)
  3. The shell for the main module was written, based on that which all other modules (other than minimodules and abstracted AED modules) uses
  4. It was decided what screens that module would use, and these were all assigned code-names. Functions were created for these code-names, and the run function was filled in to call them up according to the 'type' parameter (as featured in all other modules)
  5. Install and uninstall functions were written for the module, according to the database schema
  6. Add, edit, and delete backend functions were written for the data of the module
  7. Add, edit, and delete screens were written for the data of the module (including definition of associated language strings for the standard ocPortal field inputting interface [wherever possible, referencing existing ones, to reduce the burden for anyone wishing to translating the module once we release it publicly as an ocPortal addon])
  8. The screens for the main interface were written
  9. The module was tested, and then deployed

Thumbnail: ocPortal module for the tester mod

ocPortal module for the tester mod

The new module, approximately 1,000 lines of code (PHP and XHTML) was completed within one long day, and in active use soon after. It is a moderately advanced module, and was of great help to our organisation. Naturally, it would take a lot longer for an inexperienced ocPortal programmer to create this module, but the point is that it was made a lot faster due to our API and extension infrastructure: without these, a custom application from scratch might have taken a full week to develop. The alternative to a custom module would have been a third party application, but this would not have provided us with the level of integration we demand for our systems (not to mention compatibility with things as they are currently, and how they might change in the future). It is worth mentioning at this point that ocProducts staff are available for implementing systems built around on ocPortal.

Some of the API functions used in the module include:
  • create_table
  • add_specific_permission
  • add_config_option
  • query_select
  • do_template
  • do_lang
  • has_specific_permission
  • build_url
  • assign_refresh
  • get_param_integer
  • get_member
  • member_group_query
I'm sure you can see why such a function library (and the pre-written subsystems that exist behind them) speeds up development considerably. All this is built into ocPortal by default, so no libraries need hunting down, installing and managing to achieve all this.


There are 3 different kinds of PHP override in ocPortal:
  1. Extending a module
  2. Replacing/supplementing a file
  3. Replacing/supplementing a file, with support for progmattic alteration of the original code

It's important to note that as well as overrides you can place entirely new files in the *_custom directories, and ocPortal will be able to reference them as if they were original files.

All these techniques are handled inside the ocPortal sources/global.php file. If you are a good programmer but still can't work out how to do all this stuff (it's easy once you know how, but a bit unorthodox compared to normal techniques), look at the code of this file. As sources/global.php is the file that does the magic it's the only file that you can't override; it is therefore kept minimal, hence why we have a sources/global2.php which picks up where sources/global.php leaves off.

Extending a module

This form of overriding works via class inheritance. All you need to do is to make a modules_custom directory version of an original modules directory file, with two differences:
  1. Instead of just naming the module class Module_<modulename>, rename it and inherit using Mx_<modulename> extends Module_<modulename>
  2. As this works via standard class inheritance you are at liberty to, and should, only re-define methods in your override when those methods are actually different from the original ones. i.e. start with a shell of a class and only re-define methods that you are actually wanting to change

Replacing/supplementing a file

If you override a file to the sources_custom directory then that file will essentially be overlaid on top of its equivalent in the sources directory. (You can use this technique in other *_custom directories too, such as modules_custom directories – although in this case it is less useful, as there is less granularity due to a module only containing a single class)

You can redefine any existing function or class, and you can define new functions or classes. ocPortal does some magic so that you can reference the old versions of the functions or classes by prepending non_overrided__ to their names (e.g. example_function would become non_overrided__example_function). This is very useful if you can write your overridden function without having to completely replace the original function. For example, if we just want to add some logging to example_function

PHP code

function example_function($a,$b)
some_logging_function('call to example_function with '.$a.' and '.$b);
some_logging_function('leaving example_function returning '.$ret);

It is also very useful for classes because it allows you to create a subclass of the original, without changing its name (which would break ocPortal, as ocPortal expects a certain fixed name for its classes). For example:

PHP code

class example extends non_overrided__example
some_logging_function('call to example::mymethod with '.$a.' and '.$b);
some_logging_function('leaving example::mymethod returning '.$ret);

This is a great technique for making changes to forum drivers.

One word of caution – if you are not supplementing a code files 'init' function, then you will want to strip out the init function from your override, otherwise both it and the original will be called in sequence. This is unavoidable, because the modified file is loaded first and thus cannot call the original init function itself – and thus responsibility for that stays with the ocPortal code. There are two exceptions:
  1. If your override contains every class or function the original file has (i.e. you overrode the whole file by copy&pasting) then the original init function will not be called as ocPortal assumes you copy&pasted all that code into your own init function.
  2. If you want a partial override but don't want the original init function to run, you need to use progmattic alteration to mask the original init function. This is explained in the last paragraph of the next section.

Progmattic alteration

Sometimes you want to override something in the middle of a function and thus there is no neat way to do it without copy&pasting the whole function.

In theory, good software architecture (modularity etc) is meant to prevent this situation happening, but in practice:
  • its completely impossible for an original programmer to predict what changes someone might want to make to their code
  • programming languages have no inbuilt features to work around problems stemming from this lack of foresight (even the most heralded OOP techniques cannot do it)
There are 3 ways this problem could be solved:
  1. Alter the original ocPortal code. This is a very bad idea because you then have a very hard time identifying your changes, and performing even patch upgrades
  2. Override whole functions. This is a bad idea for non-trivial functions because it makes feature/major upgrades much more problematic
  3. Use a mechanism that goes beyond what programming languages can normally do

We took approach '3', and thus have written a special feature into ocPortal for it. Its admittedly a bit messy but in practical terms it works almost flawlessly.

In ocPortal it works as thus:
  1. First you create a sources_custom file
  2. Next you define an init function of this file. If you were overriding sources/example.php you would define a init__example function. If you were overriding sources/forum/example.php you would define a init__forum__example function (i.e. any slashes get changed to '__' in the function name)
  3. The init function should take a single parameter, and return something based upon that parameter. The value of this parameter will be the string value of the code you're overriding, after any function/class renaming has happened (see 'Replacing/supplementing a file' above). i.e. your function is taking a huge lump of PHP code as its parameter. In-between taking the parameter and returning it you can perform any changes you like. You can use any string functions like preg_replace or strpos; or use the handy ocPortal get_function_hash / insert_code_before__by_linenum / insert_code_after__by_linenum / insert_code_before__by_command / insert_code_after__by_command / remove_code functions

There is one important rule when it comes to progmattic alteration: you are not allowed to call non_overridded__init__<whatever> from your init__<whatever> function. You cannot do this because the PHP code containing that function has not been evaluated at that point and thus the function is not yet defined. If you try and do it then ocPortal will disable progmattic alteration and hence revert to the more basic 'Replacing/supplementing a file' technique. ocPortal will automatically call non_overridded__init__<whatever> as soon as it becomes available so you do not need to copy&paste its contents to your own function. If you do not want non_overridded__init__<whatever> to be automatically called then you need to rename it in your own init function so that ocPortal cannot find it.


Thumbnail: Exporting an addon (1)

Exporting an addon (1)

In order for addons to ocPortal to be distributed in a user-friendly fashion, an addon pack exporter and importer is provided. Three types of addon are supported by this tool:
  • Language packs (for any new language translation)
  • Themes (for any new theme)
  • Code modifications (defined by manual selection of files)

ocPortal addons are TAR files which include a special definition file. They may be constructed manually if an author wishes to have more control over the construction process.

Thumbnail: Exporting an addon (2)

Exporting an addon (2)

Sometimes addons are known as 'hacks'. This stems from the alternative (perhaps, original) definition of a 'hacker' as an enthusiastic programmer, often one who likes to manipulate existing systems. It is not meant as a security related term. Another term sometimes used is 'mods'.

Thumbnail: Importing an addon (2)

Importing an addon (2)

Thumbnail: Importing an addon (1)

Importing an addon (1)

You will only be able to export files into an addon from directories that are 'allowed' to contain new or modified files. For example, the 'sources' directory should not be modified, but the 'sources_custom' directory may. This is part of the file override system ocPortal employs: modified versions of old files or entirely new files should be placed in the custom version of a directory so that it is clear they are non-original, and will not be automatically overwritten during upgrade. There are a few directories that have no _custom equivalent, and therefore you may export files to a mod from these.
Since version 3 of ocPortal, overridden PHP files may override on a per-function/per-class level. In other words, if you overrode a PHP file then you could make your sources_custom file such that the only functions/classes it contains are the ones that you changed.

The Code Editor

Thumbnail: A password is obviously needed to use the code editor

A password is obviously needed to use the code editor

Thumbnail: Choosing a code file to edit

Choosing a code file to edit

Thumbnail: Using the code editor

Using the code editor

ocPortal provides a very simple code editor for editing of existing ocPortal code files, or creation of new files. The code editor has inbuilt, automated, support for the ocPortal file override system: editing an original ocPortal file will save the edited version in the equivalent '_custom' suffixed directory where possible.

The code editor is very useful for making adhoc changes to a live-site, but is not intended as a full development environment.

PHP programming help

Thumbnail: PHP has an excellent reference manual

PHP has an excellent reference manual

It is beyond the scope of ocProducts documentation to explain how to program in PHP (although we do have a stab at it in the Programming tutorial), or other languages that are used such as SQL or HTML. PHP includes an excellent reference guide, and there are many good tutorials on the web for HTML. ocPortal uses a very minimalistic form of SQL, and usually code does not need to use any directly, due to our database abstraction functions, so this should not be a problem.

The ocPortal API guide does actually include a PHP reference that defines a subset of PHP that we allow ourselves to use in ocPortal. The subset is specially limited so as to avoid PHP version conflicts, and the need for PHP extensions that may not be installed.

Other advantages to our framework

If you still are not convinced that ocPortal is the right choice for you, consider some of these:
  • There are many frameworks for creating web applications available (such as Typo3 or Ruby-On-Rails), but few true frameworks like ocPortal are also 'out of the box' systems
  • In addition to the above, few pure frameworks provide the dimensions of functionality that ocPortal can provide
  • ocPortal's framework has excellent security. For example,
    • the database abstraction system allows relational databases to be accessed without concern of SQL-injection
    • The template system is written to make XSS injection virtually impossible (where the vast majority of programmers write code that is full of XSS vulnerabilities, without even knowing what they are)
  • ocPortal's framework is of professional quality, managed by a single company that keeps every aspect of it to high standards, and compatible with each other. If you opt for frameworks which are incomplete, and end up using addon libraries to achieve additional functionality, you will soon realise, both immediately and after-time, that the lack of central control results in:
    • major compatibility problems
    • messy feature overlap
    • inconsistent philosophies for code
    • inconsistent philosophies for documentation
    • a large number of agents to contact for different kinds of problem
    • no central authority for you to agree licensing with, should you need to do so (and this is not unlikely, as many projects flower to unexpected ends)
    • orphaned projects that die


Application Programming Interface: functions in libraries (in ocPortal's case, files under sources/) intended for common use by other code.
A system for documenting function APIs, based on Javadoc

See also