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 contact us to see if we can provide commercial assistance.

Table of contents

ocPortal Tutorial: Integration of ocPortal and other installed scripts/applications

Linking

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 old, more robust, way

Note

Relative URLs are normally read relative to the path the referencing page is in. For example, if an HTML file is loaded directory, relative URLs that file references would be relative to the path of the HTML file. 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 HEADER.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 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.

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…

Code


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

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 it isn't, see the 'Note)
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 new, quicker, way

As of version 3, ocPortal can handle most things for you.

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.
  - If the directories go more than one level deep, ocPortal will translate '/' to '_' when looking for the 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.
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

Embedding

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

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 of another. There are two main drawbacks with frame based approaches however:

the browser back button will send the 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:

Code


			[html]
<iframe title="<whatever the embedded system is>" frameborder="0" marginwidth="0" marginheight="0" src="<whatever the system URL is>" style="width: 100%; height: <whatever height you want>px;"><whatever the embedded system is></iframe>
[/html]

Where the following are appropriately replaced:

<whatever the embedded system is> (e.g. "Something web system")
<whatever the system URL is> (e.g. "http://ocportal.com/somethingwebsystem/")
<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.

Code


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

<iframe title="<whatever the embedded system is>" frameborder="0" marginwidth="0" marginheight="0" 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">
<!--
   var tid=window.setInterval('resizeEmbeddedFrame()',500);
// -->
</script>
[/html]

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.

Naturally

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.

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.
There are two major problems with this method however that make it unlikely to function adequately for most systems:

Unless significant code was written for ocPortal to relay cookies, cookies would not work. In effect, ocPortal would need to be programmed to act as what is known as a 'transparent proxy' for all but the simplest situations.
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 it's security model.
Work would be needed to clean up the HTML of the embedded system so it could sit inside ocPortal, with ocPortal still having valid mark-up. This could be done in one of two ways:
- By editing the embedded system so as to only produce HTML fragments that nest cleanly inside ocPortal
- By programming the ocPortal linking module to automatically select the appropriate HTML fragment (i.e. throw away the header and footer)
If the embedded system did not support XHTML as ocPortal does, then ocPortal's own mark-up would be compromised,
System links would need to be modified so as to pass through ocPortal.

RSS/Atom

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.

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

If you want to share members between ocPortal and another system, this can be tricky. There are four general ways to go about it:

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.
reprogram the other system so that it uses the same member system that ocPortal is (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)
disabling 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
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"

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

Concepts

iframe: A portion of the main web page that encloses another web page (with it's own URL)

ocPortal Tutorial: Integration of ocPortal and other installed scripts/applications

Linking

Embedding a simple HTML page

The old, more robust, way

Note

Code

The new, quicker, way

Embedding

iframe

Code

Code

Naturally

Code-based relay

RSS/Atom

Look and feel

Sharing members

Concepts

See also