ocPortal Tutorial: Basic configuration

Written by Chris Graham, ocProducts

Once ocPortal is installed, there is some basic configuration to do before your website is ready to open.

During basic configuration, you will be familiarising yourself with ocPortal for the first time. Please be patient: there is a lot to ocPortal, but once you have a mental image of how things work, you will find it a very powerful and malleable system.

Table of contents

ocPortal Tutorial: Basic configuration

Things to do

Important note

Important note: Login using an administration username. If you installed using OCF (ocPortal's own forum system), the username and password will have been specified during installation (with the username being 'admin' by default).

When the installer finishes, you have a choice to either view your website, or run the Setup Wizard. The Setup Wizard link will direct you into the 'Admin Zone', which requires to login. If you choose to view your website, you are presented with a screen saying that the site is closed, with a login link. Once logged in, there is a link to the Admin Zone in your 'login block' (alternatively, you can always access your 'Admin Zone' directly by appending /adminzone to your website's URL).

The Setup Wizard

The first thing you will want to do after installing the software is to configure the name of your website, and other key details. The site wizard will do this for you in a few easy guided steps and thus it is strongly recommended that you use it at any early stage.

If you run the Setup Wizard, you may wonder later what it actually did, especially if you want to undo it. Everything in the Setup Wizard can also be achieved via other means. The Setup Wizard can perform the following behind-the-scenes functions:

Generating a "Theme Wizard" theme. You can access the Theme Wizard separately, from the "Style" section of the Admin Zone.
Generating a "Logo Generator" logo. You can access the Logo Generator separately, from the "Style" section of the Admin Zone.
Setting site options. You can access these from under the "Configuration" icon, in the "Setup" section of the Admin Zone.
Removing predefined content. Predefined content can be removed (e.g. default banners). Once this is removed you'd need to put it back manually, by adding it as you would any other content.
Setting redirects and setting guest access. The "single public zone" feature sets up some transparent redirects (Under the "Redirects" icon in the "Structure" section of the Admin Zone), as well as giving guests access to the Site Zone. The redirects map the site versions of 'start', 'panel_left', and 'panel_right', to the welcome-zone pages – in other words, binding them together as one.
Placing blocks. You can place/change blocks, via the "Edit in zone editor" links you see under panels when logged in under a staff account.
Copying rules. You can edit the rules page manually, from "Comcode pages" in the Content Management Zone.

Editing basic site configuration

The list of configuration sections

The most important area of the configuration

If you didn't use the Setup Wizard you will probably have noticed by now that many options are initially set to derivatives of 'ocPortal-?', but all these can all be changed to suit the content and theme of your website (ocPortal can be entirely debranded, nobody needs to know what software you are running for your site). When you visit the full configuration page to fine tune your configuration, you will see that configuration options are split into a number of subsections. Scroll down your browser window until you find the section entitled, 'General'. From this, you may specify the most important details. Once done, scroll to the bottom of the page and click the obvious button.

There are many more options in the main configuration, and the actual options available depend on which modules are installed.

Editing zones for header text

Editing a zone

If you chose not to use the Setup Wizard, you will see that 'Welcome to ocPortal-?' is still written in the title-bar of most user viewable pages. To change this, you need to edit your website's zones so as to give them new 'header text'. A zone is simply a collection of pages, accessible from a common 'URL sub-directory' (such as http://example.com/zone). The 'Admin Zone' is an example of a zone, as it consists of many different pages related to the administration of your site, all underneath 'adminzone' in the URL. The very base of your site, where sub-directories branch off from, is called the 'Welcome Zone' (this is equivalent to the base_url in the installation options).

The two zones you need to edit to specify your own header text are:

Welcome (this is to greet users and provide the opportunity to join)
Site (this is a zone where most pages are stored; by default it is only accessible to users who have joined, but you may change this by editing zone access permissions)

Editing zones may be carried out from the Admin Zone, as indicated in the screen-shots.

Editing default Comcode pages

The list of Comcode pages to be edited/deleted

A Comcode page is a page in the system that you can edit either via a WYSIWYG editor, or a very simple mark-up language called Comcode. If you want to write a page without any special formatting, you can just type it out in plain-text, and this will usually be valid Comcode and display as you would expect it to; you can also add 'tags' to identify things such as titles and links.

Editing a Comcode page

Comcode pages may be selected for editing from the Comcode pages editor in the Admin Zone. The list to choose from has them listed in 'zone:page-name' format, which is a very common naming convention in ocPortal that is a bit like an 'ocPortal URL' (it's called a 'page link'). The default Comcode pages are:

Zone	Page	Purpose
All	start	This is the default front-page of a zone
All	panel_left, and sometimes panel_right (and also any panel_ page may be added and used by a user, if a template such as GLOBAL.tpl references them)	Your actual menus, either side of your pages, are assembled by Comcode pages. Not all zones have menu pages, and there are other ones available that are un-used by default. They may also be turned off on a per-zone basis, by making a zone 'wide'.
Welcome	rules	Site rules, also shown when joining the forum.
Welcome	sitemap	The Site Map, which by default, is automatically generated using a special block.
Welcome	privacy	Privacy information.
Welcome	hosting-submit	This is linked to by a default banner, advertising web hosting. You may wish to delete the default banner and remove access to this page.
Welcome	feedback	This provides a feedback form, linked from the footer.
Welcome	donate	This is linked to by a default banner, advertising web hosting. You may wish to delete the default banner and remove access to this page.
Welcome	advertise	This is linked to by a default banner, advertising web hosting. You may wish to delete the default banner and remove access to this page.
Site	guestbook	This provides a simple guest-book, and is unlinked by default.
Site	help	Help for your site. Contains default information on points, etc.
Collaboration Zone	about	This describes the Collaboration Zone. I recommend that you don't edit this yet.

Tip

Using a combination of changing a zones start page, page redirections, and zone/page access permissions, you may change the front page of your site to any of your choosing. For example, you can change the front page to be in-line forums by:

editing the Welcome Zone to use 'forums' as the start page
creating a page redirection from '','forums' to 'site','forums' (because the 'forums' module isn't actually in the Welcome Zone)
changing your 'site' zone access permissions to grant guest access.

The documentation is in-fact provided in Comcode format itself, but you are not likely to want to edit this.

Editing logo theme images

Choosing theme images to edit

You will want to change your logo to give your site an individual identity. You may either do this manually, or by using the Logo Wizard; the rest of this section will assume that you are doing it manually.

When you change images, styling, or low-level HTML structure (defined in templates), you are editing the theme of the site. Therefore to do it, you should choose the 'Themes' link from the 'Style' section of the Admin Zone.
When you choose to manage images in the default theme, you will be warned against editing the default theme; for this simple task, the warning is irrelevant, and we therefore recommend you click 'ok'. If you are feeling adventurous, you could add a new theme, and continue sculpting your theme as you go.

Choose 'logo/-logo' (the logo for the Welcome Zone, and the logo for any zone that does not have its own) from the drop-down list presented. After clicking the button you will see the current image; all you need to do is create your own replacement on your computer (as a .jpeg/.jpg, .png, .gif or .png file) and choose to browse for it to upload. You do not need to erase the current URL, as your upload will replace it, and you definitely should leave the 'Name' field unchanged.

Editing a logo theme image

Your choice of image file formats:

Do not ever try and use '.bmp' files with ocPortal, as they do not have proper compression, and are designed for Windows only.
It is also ill-advised to use '.gif' files, as the format was encumbered by patents until recently that prevented its usage on most Linux installations, and hence if ocPortal ever needed to create a thumbnail for one, it is unlikely to be able to.
PNG files never lose quality, and are well compressed and supported.
JPEG files can be very small, if you reduce the quality, or acceptable quality and comparable to PNG files in file-size.

Editing menus

The left hand panel

The menu editor

In ocPortal, menus are placed on panels via an ocPortal feature called a 'block'; the panel consist of Comcode that can display blocks (those blocks are given parameters within that Comcode), of which one type is the menu-block.

You may wish to remove some of the links from the default menus on your installation. To do this, log in as an administrator and click the 'Edit menu' link. Using the menu editor is beyond the scope of this tutorial.

Default banners

If you are not running a community site, you will almost certainly want to delete the default banners. Three banners are added into the system by default, to give websites a 'leg up' and a working view of the banner rotation: but they may not be appropriate. If you ran the Setup Wizard then you have already been given a choice to remove these banners automatically.

Environment configuration

Your base-configuration

To change an option set during installation, you generally use the external "Installation Options editor". The Installation Options editor is completely separated from the main software, so that if your site ever breaks due to a misconfiguration in the info.php configuration file, you can fix it without having to hand edit the file. As a result of the separation, the Configuration editor does not support multiple languages, and will not empty the caches automatically for you when you change an option, so after using it you should use the cleanup tools to empty the caches.

Scheduling

In order for aspects of ocPortal that support scheduling to work it is necessary to set up a system level scheduling task for the 'data/cron_bridge.php' file on an every-minute basis. By doing this, you tie in ocPortal's scheduler with the server's scheduler. This cron_bridge.php file can either be run up by calling the URL, or by passing the PHP file through the PHP interpreter. Don't call up the URL by hand because if you do then ocPortal will start assuming the scheduler is working from then on which can make testing it a bit harder (once it is called once it is marked 'working' by the system – applicable features will become available, and the todo item will be removed from the checklist on the front page of the Admin Zone).

Specific advice for Linux

On Linux the following command might work for an ocPortal installation in the '/home/funkysite/htdocs' directory:

Code


			php /home/funkysite/htdocs/data/cron_bridge.php

On Linux, the system level scheduler is 'Cron', and the process of adding a task is known as 'setting up a Cronjob'. Many web hosting control panels allow you to do this.

Specific advice for Windows

On Windows the following command might work for an ocPortal installation in the 'c:\sites\funkysite\www' directory:

Code


			c:\php\php.exe c:\sites\funkysite\www\data\cron_bridge.php

On Windows, either the hosting control panel will provide a similar scheduler to Cron, or you can use the Windows' 'Scheduled Tasks' feature as described below (assuming you have access).

The following is a Windows Vista scheduler step by step process for scheduling the running of cron_bridge.php every 5 minutes to enable the scheduler:

Open up Windows Task scheduler
Click 'Create Basic Task'
Give it a name and a description
Click 'Daily'
Set the Time and to re-occur every 1 Day
Click 'Start a Program'
Under program/script add the location of php.exe on your system something like "C:\php\php.exe" – also include the double Quote Marks ("") surrounding the file location
Under 'Arguments' add the location to the cron_bridge.php file which for the example above would be "c:\sites\funkysite\www" (note how the PHP command is split across two parameters – step 7 having the php.exe path and step 8 having the PHP file path) – again surround in quote marks.
Click 'Next'
Tick (check) "Open the properties dialog for this task when I finish"
Click 'Finish'
Click 'Triggers' (top of window)
Double click the trigger from the list
Tick (check) 'repeat task every' box
Change the "1 Hour to 5 Minutes" for the duration of "Indefinitely"
Click 'OK'
Click 'OK'

This should have now added a schedule within windows scheduler to run the cron_bridge.php file every 5 minutes. This step by step was created using Windows Vista, the process may change slightly in other versions of Windows.

General advice

The above examples are very specific, assuming the path to the appropriate PHP executable file, and also the file system conventions of the server for where virtual-host websites are stored. The path to cron_bridge.php must be a filesystem path, not an FTP path.

ocPortal may be able to detect the command to use for you. Try opening up a URL like http://yourbaseurl/data/cron_bridge.php?querymode=1. The script should output a command for you to use.

A good test is to try running the command you end up choosing manually in a command prompt, to check it is correct.

You should schedule ocPortal's cron_bridge.php script to be loaded at least every 10 minutes.

Aspects of ocPortal that support scheduling include:

the calendar
newsletters
news
backups
welcome e-mails
XML sitemap generation
catalogue view reports and classified timeouts
stats cleanup
reminders for registration confirmation mails that were not ever actioned
newsletters (dripping out e-mails over a period of time, to stop resource spiking)

Help – my web host does not support CRON!

In the event your hosting platform does not allow you access to CRON, there are a number of options available to you.

At Home | My Free Web Cron Schedule Service you can schedule the CRON script to be called up to every 5 minutes for free. There are others on the market but this one seems to be the easiest to use and didn't fail at all during our testing. Simply Sign up and add the URL i.e. http://yourwebsiteaddress.com/data/cron_bridge.php to the scheduler and set how often you want it to run.
Other free options are FREE Cron Jobs - Reliable Web Cron service - Set Cron Job PHP (up to every 5 minutes but the schedule needs to be re-set every week) and Free cron jobs on demand (up to 5 jobs twice a day).

Closed site, and opening

Your site is initially closed

It's not advertised in the interface, but it is possible for a user to join a closed OCF-powered site if they have been given the URL to the join module (they can't see any panels in this event). Once they have joined they can't log in though unless they have subsequently been put in a usergroup with 'Access closed site' permission. The reasoning here is that the staff may give out the join URL and ask someone to use it, and then give special access because they want them to be able to get in early. If you do not like this behaviour, you can alter the join-module's permissions so that the Guest usergroup cannot access it.

Once you feel your site is ready for the general public, you will want to 'open the doors' so to speak. You can do this from the configuration: find the options in the Admin Zone, the Configuration page, the Site Configuration section, the 'Closed Site' subsection.

Concepts

.htaccess: A file used by the Apache web server to set configuration options that apply to the directory (and sub-directories thereof-) that the file is contained in
Main Admin Zone Configuration: The 'Configuration' module of the Admin Zone
Base-configuration: The Base-configuration for low-level settings such as database settings, available from config_editor.php

ocPortal Tutorial: Basic configuration

Things to do

Important note

The Setup Wizard

Editing basic site configuration

Editing zones for header text

Editing default Comcode pages

Tip

Editing logo theme images

Editing menus

Default banners

Environment configuration

Scheduling

Specific advice for Linux

Code

Specific advice for Windows

Code

General advice

Help – my web host does not support CRON!

Closed site, and opening

Concepts

See also

Is this tutorial insufficient?