HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.
Proud to be a PHP Open Source CMS
Learn more

ocPortal Tutorial: Advanced configuration

Written by Chris Graham, ocProducts
This tutorial will cover various advanced aspects of ocPortal configuration.


Table of contents

  1. ocPortal Tutorial: Advanced configuration
    1. Configuration
    2. Pages
    3. Modules
    4. Permissions
    5. Base-configuration
    6. Clean URLS
      1. Apache
      2. IIS
      3. Domain structuring
    7. See also

Configuration

Many advanced configuration options are presented and described in the main Admin Zone configuration module. As these are self explanatory, they will not be explained here in depth.
Advanced configuration options include (but are not limited to):
  • Enabling and disabling cacheing (it is useful to disable this during development, if you like to edit files by hand)
  • Enabling and disabling the XHTML validator (it is useful to leave this enabled to maintain an accessible website, but you may wish to disable it if you have a slow server)
  • Setting up details for an external SMTP server, if PHP can not itself send e-mails
  • Configuring details for various optional ocPortal features, such as the point store and galleries
  • Configuring details for logging
  • Configuring the Admin Zone task assistant block

Pages

You may delete, and move pages using the Site-tree editor .

If you are moving a page from one zone to another, any page links to that page (for example, in the menus or via 'page' tags) will become invalid, unless they were specified as being in the zone named '_SEARCH' (which is used to create a link by dynamically searching all zones for the named page). You may wish to temporarily set up a redirection from the page as named in it's original zone, to the page as named in the new zone. Details of this are given in the "Creating Sub-communities" tutorial. Setting up a redirection is also advisable if the page being moved is already well-indexed on search engines.

Modules

Modules that are not locked may be un-installed and re-installed from a module management page that is burried underneath the add-on management page. This functionality is intended primarily for use with add-ons, rather than core ocPortal modules: instead of choosing to un-install these, it is recommended you simply remove menu links, and deny page permissions, to modules you do not want users to use. It is not a notable inefficiency having extra structure in your database, and module files on-disk, as the space taken up is very small compared to other concerns.
If you really insist on reinstalling an inbuilt module, you can get choice to do so by opening up the main "Module management" link with "&keep_module_dangerous=1" tagged on to the end of the URL. This is not something we recommend, and, and possibly could cause damage if used with certain modules (for example, doing it to the galleries module, download galleries will also be deleted, or if you do it to the admin_menus module, all menu customisation will be lost).

Note

Re-installing or un-installing a module will generally delete all data associated with it, including uploads and entries.
If a module has been upgraded (i.e. The on-disk file has been replaced with a newer version), you may upgrade it (to upgrade/create on-disk and on-database data) in 3 ways:
  • Simply use the module, and it will upgrade itself
  • Run the <base-url>/force_upgrade.php script, which will upgrade all modules on your site that need it, as well as clearing caches
  • Use the module management interface to upgrade the module
There is also a concept of a 'hacked' module (a module modified as a part of an unofficial add-on): the process of performing any upgrades an on-disk file needs for this is the same as for a conventional module upgrade.

Permissions

ocPortal has a rich, multi-layered, permission system. In creation of this system we have tried to strike a balance to keep all of these factors high:
  • power
  • ease-of-use
  • quickness of configuration

Thumbnail: Specific permissions are set like this

Specific permissions are set like this
ocPortal has two main types of permission:
  • specific permissions
  • access permissions (for defining what may be viewed)

Specific permissions allow the assignment of permissions to user-groups via check-boxes. By 'specific' we mean permissions that have a very specific meaning, rather than perform a higher level role of deciding whether something may be viewed.
Broadly, specific permissions are used to grant things like 'whether a member can access the site when it is closed', as well as to define sweeping permissions for content classes.
Sweeping permissions are there so that instead of making you specify who can control (edit/delete/etc) each content-item/type-of-content/category-contents individually, you can specify them by class.
The 'visibility' scheme is used to classify content according to it's prominence on the website. The following specific permissions may be set for user-groups for each of adding, editing and deleting content:
  • low visibility content (things people will probably not notice)
  • medium visibility content (things people might notice, like downloads)
  • high visibility content (things on the front page, like an active poll)
  • (for editing/deleting only) only their own low visibility content
  • (for editing/deleting only) only their own medium visibility content
  • (for editing/deleting only) only their own high visibility content

Access permissions are also configured by check-boxes. ocPortal supports a layered system of access permissions, where to access an entry, you need permissions to everything "above" the entry:
  • Zone access permissions
  • Page access permissions
  • Catalogue access permissions (catalogues only)
  • Category access permissions (where forums and galleries count as categories in this context)
To configure access permissions, you may edit the resource the permissions are for. For example, to edit zone access permissions, you need to edit the appropriate zone. Alternatively you can edit almost all permissions in a single tool: the Permissions Tree Editor.

As of ocPortal 3 you can now optionally override specific permission settings in almost all the places where you may set access permissions. This provides a far greater degree of control but is completely optional, because if you do not choose to do any overriding then the global specific permissions will be used as per previous versions of ocPortal.

Using the Permissions Tree Editor you may configure access and specific permissions for almost any aspect of the system, as well as make batch changes with great efficiency.

ocPortal uses a "best of" permission system, meaning that a member has the best possible access that the combination of all usergroups that they are in could give them. The one exception to this is when permissions are overridden for a page/catalogue/category the user will be limited by the override even if only a subset of their usergroup set is overrided at that level.

Base-configuration

If your core configuration permissions change, if you move servers for example, then ocPortal may discontinue to function. To ameliorate this, an external configuration editor is provided that can reconfigure the info.php that stores core configuration settings, such as database access details.
To launch the external config editor, you would normally click the 'Environment' link in the Admin Zone configuration box; however, if you are locked outside ocPortal, you will need to open up the <base-url>/config_editor.php URL manually.

The password to enter the config editor is the password you specified during installation. If you have forgotten it, you will need to edit info.php by hand.

Note

If you change servers you will also need to set file permissions. Please read the advanced installation tutorial for details on this. If you upload new themes, you will need to set permissions on the templates_cached/<lang> and *_custom directories after uploading.
You may use the config editor to:
  • Change the default site language
  • Change the database driver
  • Change the forum driver
  • Change the e-mail domain
  • Change the base-URL
  • Change forum and site database details
  • Change cookie details
  • Force "short URLs" to be disabled, if you enabled it, but it failed to function correctly, locking you out of ocPortal

Clean URLS

ocPortal supports clean URLs in Apache. These clean URLs can improve your search engine rankings in some cases. ocPortal can also do clean URLs on IIS, using an IIS server extension called IIRF.

Apache

a) Rename recommended.htaccess to .htaccess. If your site gives errors after doing this, try simple.htaccess instead. If you still get errors, your server probably doesn't have mod_rewrite available, which is required for this functionality to work.

b) If things go wrong, you can disable clean URLs via an emergency shut off option in the config_editor.php script. Make sure you see where it is before proceeding to the next step.

c) Enable clean URLs from your site options (Admin Zone, Settings section, Configuration icon, Site options, Advanced box).

IIS

This functionality has been added in a patch release and thus is not officially supported as the Apache functionality is.

You need to be a server administrator of your server, to install the free IIRF ISAPI module available from:
http://cheeso.members.winisp.net/IIRF.aspx

ocProducts cannot take responsibility or provide support for this feature. We're happy to answer questions, but fiddling with your web server is only for those in the know. It is best you try things out on a test website before your live one.

To install IIRF…

a) Copy IsapiRewrite4.dll into your Inetpub folder

b) In IIS manager add the dll as an ISAPI filter, but only to the website that runs ocPortal. This means that the IIRF plugin will only affect the ocPortal website, which is important because the IIRF configuration file is not modular – if it were applied to all websites on the server, it could cause serious problems.

c) Make an IsapiRewrite4.ini file in your Inetpub folder containing the following:

Code

RewriteRule ^(.*)pg/s/([^\&\?]*)/index\.php$ $1index\.php?page=cedi&id=$2 [U,L]

# These have a specially reduce form (wide is implied)
RewriteRule ^(.*)pg/galleries/image/([^/\&\?]*)/index\.php(.*)$ $1index.php?page=galleries&type=image&id=$2&wide=1&start=$3&max=$4&$5 [U,L]
RewriteRule ^(.*)pg/galleries/video/([^/\&\?]*)/index\.php(.*)$ $1index.php?page=galleries&type=video&id=$2&wide=1&start=$3&max=$4&$5 [U,L]
RewriteRule ^(.*)pg/iotds/view/([^/\&\?]*)/index\.php(.*)$ $1index.php?page=iotds&type=view&id=$2&wide=1&$3 [U,L]

# These have a specially blogging rules
RewriteRule ^(.*)pg/blogs/view/([^/\&\?]*)/index\.php(.*)$ $1index.php?page=blogs&news_filter=$2&$3 [U,L]
RewriteRule ^(.*)pg/news/misc/([^/\&\?]*)/index\.php(.*)$ $1index.php?page=news&type=misc&filter=$2&$3 [U,L]
RewriteRule ^(.*)pg/blogs/view/([^/\&\?]*)$ $1index.php?page=blogs&news_filter=$2 [U,L]
RewriteRule ^(.*)pg/news/misc/([^/\&\?]*)$ $1index.php?page=news&type=misc&filter=$2 [U,L]
RewriteRule ^(.*)pg/blogs/view/([^/\&\?\.]*)&(.*)$ $1index.php?$3&page=blogs&news_filter=$2 [U,L]
RewriteRule ^(.*)pg/news/misc/([^/\&\?\.]*)&(.*)$ $1index.php?$3&page=news&type=misc&filter=$2 [U,L]

# These are standard patterns
RewriteRule ^(.*)pg/([^/\&\?]*)/([^/\&\?]*)/([^\&\?]*)/index\.php(.*)$ $1index.php?page=$2&type=$3&id=$4&$5 [U,L]
RewriteRule ^(.*)pg/([^/\&\?]*)/([^/\&\?]*)/index\.php(.*)$ $1index.php?page=$2&type=$3&$4 [U,L]
RewriteRule ^(.*)pg/([^/\&\?]*)/index\.php(.*)$ $1index.php?page=$2&$3 [U,L]
# This one is weird... apache strips out // and turns to /, thus requiring an extra pattern...
RewriteRule ^(.*)pg/index\.php(.*)$ $1index.php?page=$3 [U,L]

# Now the same, but without any additional parameters (and thus no index.php)
RewriteRule ^(.*)pg/s/([^\&\?]*)$ $1index\.php?page=cedi&id=$2 [U,L]
RewriteRule ^(.*)pg/galleries/image/([^/\&\?]*)$ $1index.php?page=galleries&type=image&id=$2&wide=1&start=$3&max=$4 [U,L]
RewriteRule ^(.*)pg/galleries/video/([^/\&\?]*)$ $1index.php?page=galleries&type=video&id=$2&wide=1&start=$3&max=$4 [U,L]
RewriteRule ^(.*)pg/iotds/view/([^/\&\?]*)$ $1index.php?page=iotds&type=view&id=$2&wide=1 [U,L]
RewriteRule ^(.*)pg/([^/\&\?]*)/([^/\&\?]*)/([^/\&\?]*)/$ $1index.php?page=$2&type=$3&id=$4 [U,L]
RewriteRule ^(.*)pg/([^/\&\?]*)/([^/\&\?]*)/([^\&\?]*)$ $1index.php?page=$2&type=$3&id=$4 [U,L]
RewriteRule ^(.*)pg/([^/\&\?]*)/([^/\&\?]*)$ $1index.php?page=$2&type=$3 [U,L]
RewriteRule ^(.*)pg/([^/\&\?]*)$ $1index.php?page=$2 [U,L]

# And these for those nasty situations where index.php was missing and we couldn't do anything about it (usually due to keep_session creeping into a semi-cached URL)
RewriteRule ^(.*)pg/s/([^\&\?\.]*)&(.*)$ $1index\.php?page=cedi&id=$2&$3 [U,L]
RewriteRule ^(.*)pg/galleries/image/([^/\&\?\.]*)&(.*)$ $1index.php?page=galleries&type=image&id=$2&wide=1&start=$3&max=$4&$5 [U,L]
RewriteRule ^(.*)pg/galleries/video/([^/\&\?\.]*)&(.*)$ $1index.php?page=galleries&type=video&id=$2&wide=1&start=$3&max=$4&$5 [U,L]
RewriteRule ^(.*)pg/iotds/view/([^/\&\?\.]*)&(.*)$ $1index.php?page=iotds&type=view&id=$2&wide=1&$3 [U,L]
RewriteRule ^(.*)pg/([^/\&\?\.]*)/([^/\&\?\.]*)/([^\&\?\.]*)&(.*)$ $1index.php?page=$2&type=$3&id=$4&$5 [U,L]
RewriteRule ^(.*)pg/([^/\&\?\.]*)/([^/\&\?\.]*)&(.*)$ $1index.php?page=$2&type=$3&$4 [U,L]
RewriteRule ^(.*)pg/([^/\&\?\.]*)&(.*)$ $1index.php?page=$2&$3 [U,L]

d) Reset IIRF

e) Test a clean URL (e.g. http://mybaseurl/site/pg/downloads) – if it doesn't load, you've got a IIRF/IIS configuration problem.

f) If things go wrong, you can disable clean URLs via an emergency shut off option in the config_editor.php script. Make sure you see where it is before proceeding to the next step.

g) In OcCLE, type:

Code

:set_value('ionic_on','1');
to cause ocPortal to generate short URLs for links within the website.

Domain structuring

You can now make it so you have a single ocPortal site that runs across different subdomains. You can also make it so that zones appear to be structured hierarchically.

This is an advanced feature that is not fully supported by ocProducts. It requires server administration access to work (i.e. it's unlikely to work on most shared webhosts).

The procedure is as follows:

a) It is strongly recommended, for simplicity and user-friendliness, that you operate ocPortal from the root of your domain name.

b i) For multiple sub(domain) names, each representing a different zone…
Set up multiple website profiles in IIS manager (or the Apache configuration file, if you're using Apache). These profiles must all point to the ocPortal installation directory.

b ii) For complex hierarchies:
Set up virtual directories in IIS manage (or the Apache configuration file, if you're using Apache). These virtual directories must all point to the ocPortal installation directory.

c) ocPortal is now set up to receive requests on the various domain names / paths that you have configured. Extra stuff needs adding to the ocPortal info.php, to tell ocPortal how to map these individual source locations, into zone accesses.
Let's pretend we've added a new subdomain 'forum.mydomain.com' (for the forum zone), and a new virtual directory under our normal website entry, under 'example/path' (for the xyz zone). You would add this to info.php

Code

$SITE_INFO['ZONE_MAPPING_forum']=array('forum.mydomain.com','');
$SITE_INFO['ZONE_MAPPING_xyz']=array('mydomain.com','example/path');

d) Now ocPortal links point to the proper complex URLs, and the complex URLs are properly recognised as zones.




See also