FolderCMS User's Manual

Version 3.6

Introduction

FolderCMS is a bit different to other content management systems: there's no 'admin panel', and you edit your site's content by creating and modifying files directly. That means you'll need to read this document first. Don't be put off: the system is simple to work with once you get used to it.

Skip to Getting Started.

For more information or to get the latest version, visit http://www.generaldevelopment.com.au/foldercms

What's new in version 3.6

A minor update to add a global variable setting to toggle the menu item for the current page being formatted as a link.

What's new in version 3?

New global variables now allow the user to select what sort of tags should enclose menu items, and what CSS classes to use. This makes it even easier to make FolderCMS work with the many generic HTML/CSS templates available online.

When an active menu item is not a link (because it refers to the current page), FolderCMS now encloses the text inside an inner span element, enabling more flexible styling.

GD-CMS has been renamed to FolderCMS, to better describe the system.

Documentation has been converted to HTML, in line with our new internal guidelines for documentation.

Upgrading from GD-CMS version 1 and 2

This is not a drop-in replacement to previous versions. Global variable names and functions have changed to follow a consistent naming scheme, meaning you have to make a few changes to your index.php file to keep things working properly. The filename of gdcms.php has also changed to foldercms.php.

Terminology

directory - technical term for a folder on a computer's storage drive.

PHP - a scripting language that's commonly available on web servers for generating dynamic page content.

License

Copyright (c) 2010-2019 General Development Systems

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Getting started

Is your web server/web hosting up to it?

Your server needs support for PHP scripting. If your webspace is hosted externally (e.g. by your ISP or by a hosting company), you almost certainly have PHP support enabled. If you are hosting a site on your own server, you probably still have PHP support although it may be disabled by default. Look for an option relating to 'server-side scripting' in your server's configuration, and make sure it is enabled.

An easy way to test if you have PHP support is to create a file in your public web space called something like test.php (call it what you like, but make sure the filename ends with .php). Put the following PHP code inside that file: 

<?php echo 'Hello, world!'; ?>

Now navigate to the location of that test file on the web, through your web browser (don't just open the file's location on your local computer or you'll just see what you typed into the file). If you see 

Hello, world!
by itself in your browser window, the PHP script has been executed correctly and done its job. But if you see the whole line of PHP code as you entered it into the file, PHP isn't working on your server.

Installing FolderCMS

Find a convenient folder on your hosting server, perhaps your home directory, preferably outside the public HTML directory where you normally place publicly accessible web site files.

Copy the foldercms.php file you downloaded into this folder, and also create a new folder in the same place, called content. This is where you'll put the content that will make your web site informative.

Creating the template page

Now create the skeleton of a web page. Use any program you like, but leave spaces for menus, sub-menus, sub-sub-menus (depending on how deep you plan to go with your content), and of course the main body of your content. Non-trivial formatting like particular menu and heading styles will require you to define your own CSS styles for the items within those menus, although this is something you can deal with once you have everything else working.

Call your skeleton page index.php and place it in your server's public HTML folder. (Most servers look for either an index.html or index.php file as the default page on your site. You don't have to call it index.php if you don't want it to be the default page, or your server has alternative requirements, but the filename must end in .php for the PHP code you're about to insert to be recognised.

Now open your file in a plain text editor. Add the following to the very top of your file: 

<?php

include('../files/foldercms.php');
?>
But replace ../files/foldercms.php with whatever the path to foldercms.php is on your server. Note that ../ means 'parent folder.'
The <?php has to be at the very start of the file. That means no blank line or space before the <. Otherwise PHP will start sending premature page header information which will prevent FolderCMS features like page redirects and page-not-found errors from functioning correctly.

Specifying options (global variables)

There are some options you can specify above the include(....); line in your index.php file (but after the opening <?php): 

$foldercms_content_path = '[path to a content directory]';

This allows you to specify a custom path to your content directory. If omitted, the content directory is by default assumed to be named content and in the same directory as the foldercms.php file. (If you specify a custom path, it should be a full path on your server's filesystem, with / between each directory, and a trailing / at the end. 

$foldercms_href_prefix = '[a URL prefix]';

This allows you to specify a prefix for the menu links on your content pages. You won't need to worry about this unless you have specific requirements for how the links are formatted, or you use URL rewriting with all the content inside a virtual directory. 

$foldercms_url_rewrite = TRUE;

This option instructs FolderCMS to format menu links in a way that looks neater in the address bar. Instead of links like ?l1=Section&l2=subsection, FolderCMS will produce links like /Section/subsection. This won't allow FolderCMS to automatically recognise such links though. You'll still need to configure your server to translate the neat URLs into the ?l1=Section&l2=subsection style that FolderCMS expects. 

$foldercms_url_space = '[a single character to represent spaces in URLs]'

By default, FolderCMS uses the standard convention of using the '+' character for representing+spaces+in+page+URLs. You can specify an alternative character, such as a '-', to-be-used-instead. In this case, it is still safe to have page titles containing '-' characters, since FolderCMS automatically substitutes them with '+' characters instead.

$foldercms_url_lowercase = TRUE;

This option instructs FolderCMS to generate the dynamic part of the URL in all-lowercase characters, which some people think looks neater in search results. There are no side-effects in how these URLs are interpreted (will not break existing links) as FolderCMS interprets URLs in a case-insensitive way. 

$foldercms_double_encode = TRUE;

Some versions of Apache (web server) will lose symbols like '+' in your page titles if you use URL rewriting on your site, breaking menu links that use those symbols. Enable this option as a workaround if you use URL rewriting and this happens to you. 

$foldercms_auth_flags = 3;                     //...or, another example ...
$foldercms_auth_flags = array(1, 3, 99);

You can choose one or more numerical 'auth flags' to guard certain content with. For example, you might use the number 1 to guard pages that should only appear on the mobile version of your site, and number 5 for pages or categories that should only be available to users who have logged in to your website. (Note that adding user login functionality to your website requires extra PHP coding on your part.)
You can choose whatever flag numbers you like (the above examples are just arbitrary), but if you want to specify more than one flag at once, you need to place array( ... ) around your list of 'authorised' flags, as in the example above. 

$foldercms_menu_tag = 'span';                    //default setting
$foldercms_menu_class = 'menuitem';              //default setting
$foldercms_menu_active_class = 'menuactiveitem'; //default setting

By default, FolderCMS will wrap each menu item in a <span> tag, with CSS class specified as class="menuitem". The active menu item has an additional second class applied, which is menuactiveitem.

These can be used to style your menus using CSS rules. However, there are also many generic HTML/CSS templates available online which you might wish to use, and these might display menus using different CSS class names, or using <li> tags instead of spans. In this case, you can override FolderCMS's default settings by specifying the above definitions, but changing the values to be consistent with your template.

$foldercms_menu_current_page_link = FALSE;      //default setting

By default, a menu item that refers to the current page &endash; the menu item explicitly selected by the user &endash; will not be formatted as a link, but as ordinary text. The exception is where the current page was displayed due to being the default page for a particular parent category, but was not explicitly selected by the user.

Since the defaut behaviour can make styling a page more complicated (the CSS rules for custom menu styling would need to accomodate active menu items that do and do not contain links), this behavior can be overridden by setting this global to TRUE.

Setting this variable to TRUE causes all menu items to be formatted as links regardless of whether active or not. The active items can still be styled accordingly by writing CSS rules for the menuactiveitem class which is described above.

Adding placement code to your skeleton file

Now, inside the code of your index.php page, place the following... 
<?php foldercms_place_title(); ?>

anywhere you want the title of the current content page to appear. One good place is between the <title>...</title> in the head of the HTML code (so the correct page title appears in your web browser's title bar).

Also place 

<?php foldercms_place_content(); ?>
where you want the body of the content to appear.

For the menus, place 

<?php foldercms_place_menu(1); ?>
where you want the main (top-level) menu to appear, <?php foldercms_place_menu(2); ?> where you want the sub- (level 2) menu to appear, and so on. You can have as many levels of submenus as you like.

By default, menus are generated with a space in between each menu items. You can have anything you want between each menu item, by supplying an optional parameter; for example... 

<?php foldercms_place_menu(2, ' | '); ?>
...will cause FolderCMS to separate | items | like | this.
Similarly, placing <br /> (an HTML line break tag) between each menu item, will cause each menu item to be on a separate line.
Note: You can also use a CSS stylesheet to format your menus. Each menu item is given a unique ID (which you can inspect by viewing your page's source code) to give you fine-grained control.

If your content includes cascading template files, use the following to insert them into the appropriate place in your page code: 

<?php foldercms_place_template('[template title]'); ?>

If a particular template file isn't available, this function simply has no effect.

To add breadcrumb navigation to your site, use the following where you would like the breadcrumb navigation links to appear: 

<?php foldercms_place_breadcrumbs('[separator]'); ?>
...where [separator] is whatever symbol(s) or HTML code you want to appear between each link.

To help promote FolderCMS, use the following near the bottom of your site to add a short 'Powered by FolderCMS' message to your page (you don't have to, but we do appreciate it): 

<?php foldercms_place_promo(); ?>
Most of the above placement functions can also be used inside your content files and templates. Just avoid things that cause recursion, like placing foldercms_place_content(); inside the content itself.

Adding content to your site

Inside your content folder, create files and folders according to the following scheme:
Note: Your content pages can have any filename extension you like (not necessarily .txt). For example if you have a PHP code editor that you want to edit your content files in, you may find it more convenient to name your files, 1.Welcome.php, etc.

The number followed by the period represents a index number within the current folder. Each index can only be used once, and a category folder can't use the same content title as a content page within the same parent folder. The numbers represent the order in which the menu options are presented.

Writing your content

Within a content file, just write your content out using a text editor, using HTML markup tags for formatting 

<h1>Main heading</h1>
<p/>First paragraph
etc.
If you're new to HTML markup, refer to the included HTML markup reference file for a convenient one-page summary of basic formatting tags.

Special designators

You can place one or more of the following designators in your content filenames, directly after the index number, but before the first period '.' in the filename. Some designators allow you to omit the menu index number entirely. This means that the item won't appear in the menu, but you may still be able to access it with a direct link.

d – default

Using the d specifier means that item will be selected by default when the user clicks on the parent category. Naming a file d.Your title here.txt, without the menu index number, means that that content page won't show up in the menu separately, but instead will be treated as the default content page within its parent category.

h – hidden

Using h instead of (or after) an index number makes a content page or category hidden. It will not be displayed in menus, however users can still access the page or category if they know its URL.

r – redirect

This allows you to include links to external websites in your content menus (For example 4r.Blog.txt). Inside the file, instead of writing actual content, write (on a single line without spaces) the URL of the web page that you want that item to redirect to. Begin the URL with http:// if it's an external website.

a... – auth flag

a followed by a number allows you to specify that a content file should only be used if a particular auth flag is set. You can specify that more than one are required, for example, 2a1a3.Restricted Category will only be available and visible in the menu if auth flags 1 and 3 are set.

Using a without a flag number means the content will be available if at least one auth flag is set, regardless of the flag number.

If auth flags are set, content that requires auth flags will take priority over content that doesn't, so you can override default menu items with alternate content if required.

t – cascading template

You can provide things like extra layout code which apply to a particular category (and 'cascade' down to subcategories) in order to give one corner of your website a unique look, for instance. For example, you might have a t.header.txt file in your root content directory, and override it with a different t.header.txt file in a particular subcategory. To apply this particular template, you would use 
<?php foldercms_place_template('header'); ?>
in the appropriate place in your index.php file.

Cascading templates are only really needed if you have different layout requirements in different subcategories.

e401, e403 or e404 – custom error content

You can show users a custom content page when an error is generated. This must be a content file, not a folder or a redirect.

Other PHP-specific functions

foldercms_get_title([$level])

This function returns the title of the current page for use in PHP scripting, or takes an optional argument to return the title of the parent content at a different level, with 1 being the top level content in your website's content tree.