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, which is now in beta. ocPortal 9 will be 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: Integration of ocPortal and other installed scripts/applications

Written by Chris Graham, ocProducts
This tutorial will provide details on how to integrate ocPortal with another web system (known henceforth as the 'other system') installed for your website.

Please note that many systems, especially complex ones, will not easily integrate without reprogramming. In this event, you may wish to hire ocProducts for commercial assistance.
Even the kinds of integration here usually require a high level of skill in web technologies and ocPortal technologies.


The simplest form of integration is by simply placing a link on your menu. There is nothing stopping you having multiple systems installed on your website as long as they do not have conflicting file/directory structures.

Embedding a simple HTML page

If you don't need to integrate a full web application, just a simple HTML page, this can be done without much trouble.

The careful way

The two main issues that present themselves are:
  • HTML files tend to have associated data files, and the path these are read from when integrated into ocPortal will not be the same as the path of the HTML file itself (as page files are located in a different location to where the index.php file that handles the page request is located)
  • HTML files contain surrounding mark-up that must be stripped, because ocPortal already provides it


Relative URLs are normally read relative to the path the referencing page is in. However, this behaviour can be changed using an HTML tag 'base', but ocPortal does not use this by default; you may place a 'base' into ocPortal in HTML_HEAD.tpl if you wish, to create a common location for relative-URLs to be relative to. This is possible in ocPortal as ocPortal itself only uses absolute URLs.

The best way I can explain how to integrate an HTML page is by presenting a simple scenario.

In this scenario, a HTML page named mypage.html has been made in an editor, and it contains a file myimage.png that is referenced by a relative URL with no path (i.e. it is assumed to be in the same directory as the mypage.html file).

Imagine mypage.html contains…


      <title>This is my page</title>
      <img src="myimage.png" />

To integrate this page as site:mypage, the following steps would need to be taken:
  • Strip down the file to only contain <img src="myimage.png" />.
  • Place myimage.png in the 'site' directory (this assumes that 'short URLs' is turned off – if you have short URLs enabled then it is best to just use absolute URLs instead)
  • Rename the file to mypage.htm (HTML pages in ocPortal must end .htm, not .html or anything else)
  • Place mypage.htm in site/pages/html_custom/EN/

The magical way

ocPortal can actually handle most things for you if you want to defer control to it:
  • Copy any .htm files into the pages/html_custom/EN/ directory (.html files should be renamed to .htm files)
    • Unless the file is meant to be located in a subdirectory and ocPortal has a zone with the same name as that subdirectory. In this case, you'd place it in the equivalent directory of that zone so that ocPortal can better automatically rewrite any links to the page:
      • For example, don't upload pages/html_custom/EN/example/test.htm if you have a zone named 'example'. Put the file in example/pages/html_custom/EN/
      • If the directories go more than one level deep, ocPortal will translate '/' to '_' when matching against a zone name (e.g. site/more would be considered a zone named site_more)
  • Copy any non-.htm files (images, etc) into uploads/website_specific
  • Your pages should then show up as normal ocPortal entry-points in the menu editor
  • Go through the pages in ocPortal to find any broken links and adjust them so that they work. ocPortal can't perfectly fix your links for you every-time, but it does do a pretty good job. Read on for more information how link rewriting works.

ocPortal link alternation works by replacing simple patterns to local relative links. For example, a link "site/mypage.htm" would go to the ocPortal "site:mypage" entry point. If the mypage.htm file had been correctly copied to pages/html_custom/EN/ then ocPortal would actually load it up as intended.
A link "mypage.htm" would go to the ocPortal ":mypage" entry point.

As ocPortal can only rewrite the simple links, the process of fixing broken links is often a matter of simplifying them. For example:
  • http://mybaseurl/mypage.htm could not be fixed by ocPortal, because it is not a local link. Change it to mypage.htm.
  • ../mypage.htm might be used from a page located in a subdirectory. Unfortunately ocPortal can't realistically recognise this, so it can't translate this link. In this case, you would need to replace the link with the proper ocPortal page link.

To clarify, the following linking situations confuse ocPortal:
  • full links to local pages
  • page trees that go more than one level deep
  • links that go back up a page tree


If you wish for the other system to appear directly inside ocPortal, much like an ocPortal page, this is a lot more awkward.


Thumbnail: Creating a new Comcode page to place the iframe

Creating a new Comcode page to place the iframe

An iframe is an HTML construct that allows you to place one site inside a region ('frame') of another. There are a few main drawbacks with frame based approaches however:
  • the browser back button will send the whole ocPortal site back, not the embedded site. In other words, if you have made clicks inside the embedded system, and then click 'back' in your browser, ocPortal will move back, with the likely result being the embedded section is no longer the display ocPortal page
  • sometimes web browser bugs can cause rendering problems, especially when it comes to scrollbars
  • the title-bar titles would not be reflected in the browser title-bar

To place an iframed system into ocPortal, the easiest way is to make a new Comcode page which will contain the frame, link that onto your menu, and place the following Comcode into the page:


<iframe frameBorder="0" scrolling="no" title="whatever the embedded system is" src="whatever the system URL is" style="width: 100%; height: whatever height you want px;">whatever the embedded system is</iframe>

Where the following are appropriately replaced:
  • whatever the embedded system is (e.g. 'Something web system')
  • whatever the system URL is (e.g. '')
  • whatever height you want (e.g. '900')

If the embedded system has a non-predictable height, then under normal circumstances, an extra set of scroll-bars would be rendered around it when your pre-set height is exceeded. In order to avoid this without needing to choose an excessive default height, special code must be written that will regularly resize the iframe element placed in ocPortal so it has the same height as the actual contents of the frame – hence eliminating the need for a vertical scrollbar. Note that if you do this, the embedded system must be on the exact same domain as ocPortal, or web browser security will prevent the height detection from working.


<script type="text/javascript">
// <![CDATA[
function resizeEmbeddedFrame()
   var frame=document.getElementById('frame');
   if ((frame) && (top.frames['frame'].document.body))
      if (top.frames['frame'].document.body.offsetHeight+'px'!
   } else clearInterval(tid);

<iframe frameBorder="0" scrolling="no" title="<whatever the embedded system is>" name="frame" id="frame" src="<whatever the system URL is>" style="width: 100%; height: 900px;"><whatever the embedded system is></iframe>

<script type="text/javascript">
// <![CDATA[
   var tid=window.setInterval(function() { resizeEmbeddedFrame(); },500);

The draw-back on relying on this auto-resizing method is that it is somewhat computationally intensive on users' web browsers (doing a check twice a second). It is likely that users will not notice, however. When ocPortal does its own iframes it actually ties in a bit of code to anything that would change the frame height, to make it resize on demand, rather than routine checking – but this is not really very easy to do if you are working with someone else's code.


The most preferable method of getting the other system to display inside ocPortal is to 'port' it to ocPortal, as a properly constructed module, minimodule, block or miniblock. This would be very possible for most systems, but also a very significant programming effort.

The quickest way is to use minimodules/miniblocks. These are simplified equivalents to the normal ocPortal blocks and modules- anything echoed out is put into the output stream in the place you'd expect. They are placed in the correspondingly named directories in ocPortal's file-system, and then you can just use them as normal pages/blocks.

ocPortal is written so that it treats 'PHP notices' as fatal errors. This is a part of our quality standards. Some poorly written PHP code, however, is designed for PHP configurations that suppress these notices. To work around this we turn off a lot of our standard checking settings when minimodules or miniblocks are loaded.

Third-party APIs (for developers)

If you are using a third-party API with ocPortal, you can upload all the PHP files to the sources_custom directory.

Before calling the third-party code it is advisable to call these lines of PHP code:



These lines will turn off a lot of ocPortal strictness, and allow include-paths to work better (many PHP files will make assumptions that they are running from inside the include-path).

To load up them use either normal PHP code, or like require_code('example'); (for sources_custom/example.php).

Code-based relay

A compromise between a naturally ported system and a framed system would be to actually write an ocPortal module that loads the web pages from the other system and puts their output directly into ocPortal's output stream. ocPortal has a special API for this, in the 'integrator' source file.
There are two major problems with this approach:
  • The embedded system would always see the server's IP address instead of the clients; this could lead to security issues if it uses IP addresses as a part of its security model
  • It would be ugly (e.g. mixed visual styles), unless extra work was done to clean things up


If you are trying to integrate a system that is non-interactive, and outputs all important information in either the RSS or Atom families of feed formats, you may be able to perform an integration by simply using the 'main_rss' block in combination with the feed URL (or if it is date based information, overlaying the feed URL onto the calendar).
This form of integration is most appropriate for news and calendars, although other forms of information do sometimes fit it well.

Integrating Javascript libraries

If you're integrating it to your own new PHP code

For a library called example.js, copy it to themes/default/templates_custom/JAVASCRIPT_EXAMPLE.tpl. Use the non-compressed version, as ocPortal will automatically compress it anyway, and this way is it less likely the Tempcode parser will accidentally try and interpret parts of the code as Tempcode variables.

To include that library in PHP code, you would run require_javascript('javascript_example'); from screens you need to use it on.

If you're using it for your own theme, not new PHP code

Edit the JAVASCRIPT_CUSTOM_GLOBALS template and paste all the Javascript in there.

Alternatively, if keeping the filenames matters, edit the HTML_HEAD or GLOBAL_HTML_WRAP template to include it in the normal documented way for the Javascript library, and upload the files. The canonical place to put extra files in ocPortal is uploads/website_specific and reference them from there, but you can put them somewhere else if you prefer.

Integrating CSS

The easiest way to integrate CSS is simply to edit the global CSS file for your theme and paste new code in there.

Look and feel

The other system is unlikely to naturally fit in with your ocPortal theme: therefore you may need to make an effort to make them look alike. This would either involve changing ocPortal, changing the other system, or changing both to coalesce visually.

It is important to understand that it is impossible for two web systems to 'share' a theme, as themes are designed to theme specific content structures. It is so unlikely as to be essentially impossible by chance, for two different systems to have compatible layout structure.

Sharing members

It can be a bit tricky to share members between ocPortal and another system. There are four general ways to go about it:
  1. Make/have-made an ocPortal forum driver that is for the other system (as ocPortal can support different member systems through a forum driver). This is only appropriate if either the other system actually is the forum you will be using, or you are not actually wanting a forum for your site
  2. Reprogram the other system so that it uses the same member system that ocPortal uses (be that ocPortal's own, or that of a third party system); you might be able to find a modification for the other system that does it already (for instance, if you are using a widespread forum like phpBB, and want to integrate an external system, it is possible that the other system already has a modification to allow it to tie itself to phpBB)
  3. Disable joining of members in the other system, and make it so that login checks against whatever member system ocPortal is using; maintain a separate member database in the other system, but effectively tie it in to whatever ocPortal is using
  4. Use LDAP or HTTP-auth for all systems, with each setting up their own separate 'extra' member information scheme; ocPortal supports LDAP and HTTP-auth, but systems that do are in the minority so it may be a lot of work bringing other involved systems 'up to speed'
  5. Manually synchronise via CSV imports from one system to another
  6. Use the user_sync non-bundled addon to progmatically import from one database to another (requires some limited PHP programming to customise it)
  7. Use the user_simple_csv_sync non-bundled addon to tie together CSV import/export between ocPortal and another system (requires some limited PHP programming to customise it)

These are all very technical tasks, so we do not expect that many users will have the experience to easily carry them out themselves.


A portion of the main web page that encloses another web page (with its own URL)

See also