System Manual

[Crise]

This manual has three parts.
1. History: Covers brief history of this and the original system, highlighting all the notable differences.
2. The Basics: Covers the standard system features and limitations (standard & required pages and basic rules)
3, Under the Hood: Covers advanced features, extensions and configuration files

[Crise]

The original system was created on 2006 (manual was written on 16th of June) and was named XionCMS after the site which it was made for (Xion++, later AirDC++). It's basic functionality was pretty much the same and was later later patched with more features and fixes, most of which were somewhat Xion specific.

The downsides of the old system included that it had been put deep in the phpBB core through both installed and custom made modifications, so for anyone apart me to upgrade the forums was out of question. However the biggest flaw of it was probably that it actually used a greatly modified version of phpBB wrapper function suite called phpBBFetchAll for most of it's backend, which was impractical because it created twice as much work for php due to many unnecessary loops that had not been properly optimized.

Just like the old system this new system also got named after the site which it was originally made for (ClickPeer -> ClickCMS). Even though I call this system new it actually has existed for many months now, but was now redeployed here due to original site being pretty much left to rot. This new site (adcportal.com) gave me good reason to take the code out and fix any remaining bugs as well as add missing functionality. After all it would have been a shame if all the work I did would had just ended up gathering dust on my hard drive somewhere.

What makes the new system ultimately superior to the old one is the fact that it has been entirely rewritten (no code has been copied over) for only it's own needs and no 3rd party mods have been used in it nor have any original phpBB files been modified. It also manages content more efficiently (and I actually had a design when I started to code it, unlike before) and utilizes better all the resources phpBB grants to us.

It also introduces something that the old system knew nothing about, and that is somewhat reusable components and complete separation of php from html.

[Crise]

The basic idea of the system is to make site maintenance a task that does not involve editing of any physical files on server. To put it short you create, update and remove site content by doing the respective actions to topics under the Site Pages forum (from here on, the forum).

Basic rules:

1. The title of the topic created is not the actual page title (it's used as an identifier)
2. The title of the topic is to be one word and one word only
3. You will avoid replying to topics in the forum
4. Don't use too many code or quote tags in one page
5. Preview your pages, but also see the final result through main site afterwards

Special Topics

In the forum we have two special or required topics, without these the site will refuse to function entirely and return you with message:
"ClickCMS: Invalid configuration!"

Menu Topic
This one of the required topics is definitely more tricky as it has a specific syntax it must follow, always!

Code: Select all

page id, bbcode link
page id, bbcode link
etc.

Note: page id for main site index is always Home

"Home" Topic
Site index doesn't have an id it could rely on, so in the forum Home is equivalent of site index. Site index also has a static alias assigned to it on the main site which is 'idx' (see below).

Accessing Standard Pages

For main site we generally have two ways to access pages, and they are the following:

Code: Select all

http://www.example.com/?id=1
http://www.example.com/?id=blah
http://www.example.com/?id=idx <- alias for main site index and thus a reserved name, so it can't be used as a page name.

The first access method (where parameter is numeric) is based on topic id. The second access method (where parameter is alphabetic) is based on topic title instead. These are the two link formats that should be used when linking stuff inside the forum.

Hiding Page Temporarily

Simply lock the topic and it's no longer viewable through main site, yet still have it recorded on the forum. (to completely delete page simply delete it)

[Crise]

This section is covered in two parts. First talks about modules (not to be confused with the modules in phpBB) and then we go through the configuration options for the script.

Modules

Modules is simply a name for the reusable components I mentioned before, currently there is three of them: BasicSearch, Categories, RssSyndication. Two out of three function independently, thus there really is no need to cover their usage in this text (because this manual is not intended to talk about development).

BasicSearch
The search backend for the site. It is much more efficient when compared to phpBB's search because it is so simple and only does basic searching based on topic title from an array of forum id's. Which is really everything the main site needs. Security checks such as flood interval and search load are preformed as in phpBB.

Categories
Perhaps the most visible module of them all, because it is pretty much the main user of the two other modules. The basic function of this module is to fetch and display a chunk of forums, which usually is otherwise hidden from end users. All basic rules covered in the 2nd part of this manual apply to forums and content under this module, with the notable exception of rule number 2. Currently the module is set to display sub-forums under Site Pages, and just as with standard pages you create, update and remove content by doing the respective actions either to the sub-forum (category) or the topic (entry).

When creating new categories however there is one rule that must be kept, even though regular users are not allowed to see, read or post to the actual forum they must be allowed to download attachments from it. (this also applies to the Site Pages forum as well). To ease this task you can use a permission role named "CMS Access (non-editors)" for all of the non editor groups or simply copy permissions from already existing category (this is preferred to avoid setting in correct permissions).

Category visibility on main site can be restricted to certain user group(s) by adding the prefix [group:id,id,id,...] to category name, here id is the numerical id of the user group allowed to see the category.

RssSyndication
This module is quite self-explanatory and to put it short it's a copy of the news system suitable for RSS feeds. This module has two important options first is ttl (time to live) of the feed which by default is 30 minutes, and the second is the count of items displayed in feed (by default 10). The amount of items in feed is also able to be specified by the end user by appending &limit=x to the url of the feed.

Configuration file

Code: Select all

// phpBB constants (on deployment version, debug related constants should not be defined)
define('DEBUG', true);
define('DEBUG_EXTRA', true);
define('PHPBB_ROOT_PATH', './forums/');

// Template config
$CFG['style_path'] = './styles/default/';
$CFG['template_cfg'] = array($CFG['style_path'] . 'templates', 'ClickCMS');

// Meta data
$CFG['site_keywords'] = 'peer, DC++, p2p, dc, direct, connect, network, download, links, fast, speed';
$CFG['site_copyright'] = 'Copyright - 2007 © ADCPortal';

// Others
$CFG['forums_url'] = 'http://www.adcportal.com/forums/';

// Options
$CFG['format_names'] = true;             // Let phpbb format user names
$CFG['format_attachments'] = true;       // Format attachments, disable where not needed
$CFG['use_span_pages'] = false;          // Use pagination (set per page)
$CFG['cache_time'] = 61;                 // Seconds to keep mysql queries cached (by default keep 0 = off)
$CFG['news_forum'] = 10;                 // Forum where news are taken
$CFG['rel_parent'] = 2;                  // Category, which is used by categories module
$CFG['cms_forum'] = 2;                   // Forum where site content is stored in
$CFG['menu_topic'] = 1;                  // Topic used for building menu
$CFG['max_load'] = 10;                   // Max server load in %
$CFG['search_min_length'] = 3;           // Min length for search that is processed         

Above explains most configuration options quite well or then they are self-explanatory or not needed to be edited. However there are two configuration options which I feel as necessary explain a bit further.

$CFG['cache_time'] = x;
Setting x here to any other than 0, means that it may take up to x seconds for changes to be visible on the site itself

$CFG['max_load'] = x;
This means that if servers total CPU usage goes above x% the site will no longer server requests but displays a simple page informing user to come back later. I am aware that phpBB too has a similar feature built in, but mine is different because it also tries to work on windows based servers.