ocPortal Tutorial: The ocPortal programming framework

Written by Chris Graham, ocProducts

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

ocPortal has a well documented API (dev-guide generated from code)

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.

Table of contents

ocPortal Tutorial: The ocPortal programming framework

Open source

ocPortal is open source (it meets the Open Source Definition). It is not 'free software', as it is commercially developed for retail, with certain actions prohibited unless a registration is purchased, and it is not generally re-distributable in modified form.

This means that it is a lot easier to customise ocPortal as opposed to a system you might buy from a company such as Microsoft or even IBM.

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 dev-guide, which is built dynamically from the ocPortal install that the source code is running of, via the ocPortal main_code_documentor block. The dev-guide also 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 ways.
These ways 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

A block file is missing: Module (sources/blocks/Module.php or an overridden equivalent to this path)

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

ocPortal templates for the tester mod

As a part of testing ocPortal 2.5, 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 user-group. 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.

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, user-groups, 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 these basic steps:

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).
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)
The shell for the main module was written, based on that which all other modules (other than minimodules and abstracted AED modules) uses.
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).
Install and uninstall functions were written for the module, according to the database schema.
Add, edit, and delete backend functions were written for the data of the module.
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 modification]).
The screens for the main interface were written.
The module was tested, and then deployed.

ocPortal module for the tester mod

The new module, approximately 1000 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).
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.

Addons

Exporting an addon (1)

{!DOC_ADDONS}

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.

We used to use the term 'mod' to refer to an addon, but since version 3 we have not.

Importing an addon (2)

Importing an addon (1)

You will only be able to export files into a modification 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

A password is obviously needed to use the code editor

Choosing a code file to edit

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

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 dev-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 breadth 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 add-on 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

Concepts

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