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: 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. Of course, if you have a lot of content you wish to add, and customisation to do (such as making a new theme), there could be a lot more work to do; whether you wish to perform basic configuration and customise and add to your website once it's opened, or prepare it all before opening, or somewhere in between, is a decision you need to make yourself.

During basic configuration, you will be learning your way around the system 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

  1. ocPortal Tutorial: Basic configuration
    1. Things to do
    2. The Setup Wizard
    3. Editing basic site configuration
    4. Editing zones for header text
    5. Editing default Comcode pages
    6. Editing logo theme images
    7. Editing menus
    8. Default banners
    9. Environment configuration
    10. .htaccess
    11. Scheduling
    12. Opening
    13. See also

Things to do

Important note

Important note: Login using an administration username. If you installed using OCF, 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 go 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'.

The Setup Wizard

{!DOC_SETUPWIZARD}

Editing basic site configuration

Thumbnail: The list of configuration sections

The list of configuration sections
Thumbnail: The most important area of the configuration

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-?": there is no need to be alarmed, as when you are done there need be no obvious indication that the website is anything but your own unique work (unless you have not registered).
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 what modules are installed.

Editing zones for header text

Thumbnail: Editing a zone

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 site zones so as to give them new 'header text'.
At this point, you are unlikely to know what a 'zone' is. A zone is simply a collection of pages, accessible from a common 'URL sub-directory' (that is non-standard terminology, but I hope saying it in these terms makes it more clear to you). 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'.
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 is done from the Admin Zone, as indicated in the screen-shots.

Editing default Comcode pages

Thumbnail: The list of Comcode pages to be edited/deleted

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.

Thumbnail: Editing a Comcode page

Editing a Comcode page
At this early stage, you might want to quickly skim-read the "Legal and social responsibilities" tutorial, which will give you some idea of what to write into the Comcode pages that have been provided by default as place-holders. After you have given it some thought, I advise you write a basic version, in plain text, until you feel you are ready to come back and format the page attractively using Comcode tags, and also improve your writings.

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 this default banner.
Welcome feedback This provides a simple guest-book, and is unlinked by default.
Welcome donate This is linked to by a default banner, advertising web hosting. You may wish to delete this default banner.
Welcome advertise This is linked to by a default banner, advertising web hosting. You may wish to delete this default banner.
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. (available to enterprise version users only)


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 of 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), and 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

Thumbnail: Choosing theme images to edit

Choosing theme images to edit
You will want to change your logo, so as to give your site an individual identity, rather than it looking like an ocPortal installation. 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 about editing the default theme; for this simple task, the warning is irrelevant, and we therefore recommend you click 'proceed'. If you are feeling adventurous, you could add a new theme, and then edit all zones to use that theme: however we understand that this might be overwhelming.
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 not change the 'Name' for this.

Thumbnail: Editing a logo theme image

Editing a logo theme image
The topic of actually using a painting program, or what program to use, is beyond the scope of our tutorials. There are many programs available, including free ones (such as "The GNU image manipulation program" [GIMP]), and most computers will have a reasonably good one installed, as they are often bundled with scanners, or provided pre-installed; we do not recommend that the Windows 'paint' program, as this is extremely basic. 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 inadvisable to use ".gif" files, as it was encumbered by patents until recently that prevented it's 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, and JPEG files can be very small, if you reduce the quality, or acceptable quality and comparable to PNG files in size.

Editing menus

Thumbnail: The left hand panel

The left hand panel
Thumbnail: The menu editor

The menu editor
In ocPortal, menus are placed on panels via an ocPortal feature called a 'block'; the panel consist of Comcode that references and orders a number of blocks, by block name and block parameters (for example, the menu block is used by name and with parameters that name a specific menu to link to).
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

Thumbnail: Your base-configuration

Your base-configuration
{!DOC_BASE_CONFIGURATION}





.htaccess

If you are using the Apache web server (the norm on a Linux server), then you can try and get PHP and Apache to use an optimal configuration, via a special file named '.htaccess'. If you want the 'short URLs' option to be enabled, this step is necessary.
To try this, use FTP (or an equivalent tool) to rename the included 'recommended.htaccess' to '.htaccess'. This will tighten up your security where possible, and make sure ocPortal has certain PHP and Apache features turned on. Be aware that some web-hosts do not allow .htaccess files to be used to change PHP options, resulting in an error message: if this occurs, you will need to either rename the problem, or edit the file to resolve the problem.

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 a every-minute basis. By doing this, you tie in ocPortal's scheduler with the main system scheduler. This cron_bridge.php file can either be called up by calling the URL, or by passing the PHP file through the PHP interpretor.

For example, 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.
On Windows, either the hosting control panel will provide a similar scheduler to Cron, or you can use the Windows 'Scheduled Tasks' feature (assuming you have access).

Code

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

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.
A good test is to try running the command you end up choosing manually in a command prompt, to check it is correct.


Aspects of ocPortal that support scheduling include:
  • the calendar
  • newsletters
  • news
  • backups
  • welcome e-mails (the enterprise version of ocPortal only)

Opening

Thumbnail: Your site is initially closed

Your site is initially closed
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

See also