GD-CMS USER'S MANUAL
Version 2.2
==============================================================================


1. Introduction

Thank you for downloading GD-CMS.
For more information or to get the latest version, visit
http://generaldevelopment.net/gdcms

1.1 What's new in version 2.2?

- This is a final maintenance release of version 2. Version 3 has been 
  renamed to FolderCMS and has different PHP code binding prefixes. Unless 
  you are upgrading an existing website, you should go straight to version 3.
- Fixed a fault where content indices greater than 9 were being sorted 
  alphanumerically (e.g. 10 came before 2) rather than numerically.

What's new in version 2.1?

- $gdcms_href_prefix now requires prefix slash "/" to be explicit when using
  URL rewriting.
- New function: gdcms_place_breadcrumbs() allows you to place breadcrumb
  navigation anywhere on your site.

What's new in version 2.0?

- Old placement functions that were deprecated in version 1.3 have been removed
- Names of global variables have changed to follow a consistent naming scheme.
- Auth flags introduced. These allow you to provide alternate and additional 
  content only if particular flags are set.
- Cascading templates introduced. These allow you to apply particular
  formatting or content to an entire subcategory of content.
- Custom error content

1.2 Upgrading from version 1.x

This is not a drop-in replacement to version 1.3. Global variable names 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 gd-cms.php has also changed to gdcms.php.

1.3 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.


2. License

Copyright (c) 2010-2012 General Development

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.



3. Getting started

3.1 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.


3.2 Installing GD-CMS

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 gdcms.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.


3.3 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 
directory. (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/gdcms.php');
?>

Just replace '../files/gdcms.php' with whatever the path to gdcms.php is on
your server.

| 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 GD-CMS features like page         |
| redirects and page-not-found errors from functioning correctly.              |


3.3.1 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'):


$gdcms_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 gdcms.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.


$gdcms_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.


$gdcms_url_rewrite = TRUE;

This option instructs GD-CMS to format menu links in a way that looks neater
in the address bar. Instead of links like '?l1=Section&l2=subsection',
GD-CMS will produce links like '/Section/subsection'. This won't allow GD-CMS
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 GD-CMS expects.


$gdcms_double_encode = TRUE;

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


$gdcms_auth_flags = 3;                     //...or...
$gdcms_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, 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.



3.3.1 Adding placement code to your skeleton file

Now, inside the code of your index.php page, place the following...

<?php gdcms_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.
Also place

<?php gdcms_place_content(); ?>

where you want the body of the content to appear.
For the menus, place

<?php gdcms_place_menu(1); ?>

where you want the main (top-level) menu to appear,

<?php gdcms_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 gdcms_place_menu(2, ' | ') ?>

...will cause GD-CMS 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 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 gdcms_place_template('[template title]'); ?>

If a particular template file isn't available, this function simply does 
nothing.


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

<?php gdcms_place_breadcrumbs('[separator]'); ?>

...where [separator] is whatever symbol(s) or HTML code you want to appear 
between each link.


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

<?php gdcms_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    |
| gdcms_place_content(); inside the content itself.                            |



3.4 Adding content to your site

Inside your content folder, create files and folders according to the following
scheme:

- To make a new site category, create a folder called "1.Name of category",
or "2.Name of category" if slot 1 is already taken. Obviously, replace "Name
of category" with your own category title. You may use spaces and various other
symbols.

To add a page of content, name the file in a similar way:
"1.Content title.txt".

| 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.



3.4.1 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 summary of tags to use.



3.4.2 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 home 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. 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 gdcms_place_template('header'); ?>'
in the appropriate place in your index.php file. Headers 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.


==============================================================================
