Flat CMS differs from other web based content management systems in that it features:
- Very low memory footprint
- No need for a clumsy (or even a non-clumsy) database management system.
- Simple, uncomplicated administration
- Very low setup time
- Mild learning curve
It came out of the development of a framework for building web applications, not web sites. In some areas, the terms 'node' and 'page' can be used interchangeably. Also, notice that the administration is very user-focused. Creation of layouts, views, and content types is all up to the developer.
Setting up the system is dead easy, but this information is here for your guidance in case you're scared it won't work.
The requirements are very simple:
- A web server (Apache recommended, IIS untested)
- PHP 5 installed (Default configuration will do)
Because FlatCMS uses the file system to store content, it does need write access to certain folders. However, for security purposes access should be restricted to read-only for all other folders.
At the time of writing, FlatCMS only needs write/create/modify access to the /content/ folder.
Installing the system
Simply extract the zip file that you downloaded from the FlatCMS download page to a directory on your webserver. Then, access that directory on your server via a web browser.
A default site should appear in your browser. To log into the administration area, access the /admin/ folder beneath your website.
Setting the administrator password
There is only one level of users: administrators. No roles system that no-one uses most of the time anyway.
The default user account is U: admin / P: yay
To configure the user accounts, open the file /flatCMS/config/users.php. It should look something like this:
$aryUsers = array();
// enter user accounts here - a new line for each user
// e.g. $aryUsers = array("username", "password");
$aryUsers = array("admin", "yay");
To change the password, simply modify the line highlighted above - change "yay" to whichever password you wish to use. Alternatively you could add a new line for each user you want to add, as noted in the comments. However it is strongly recommended that you change the administrator password anyway.
Developing the site
The framework for FlatCMS was developed to be as unrestrictive as possible. It should give you the freedom to develop your site in whichever way you want. However, there are some patterns you will have to follow:
- Data types: These are PHP classes that define how data is administrated and displayed on the website.
- Content types: These are XML files that define fields, field types, and settings for content.
- Layouts: These are base templates for wrapping the heater, footer, and navigation elements in your template.
- Placeholders: These are areas within each layout for placing views.
- Views: These allow page content to be displayed differently, and can also be used to display forms, modules, custom components, etc.
- Modules: These are modules implemented using the modules framework.
These are PHP classes that define how data is displayed and rendered on the website. Default data types include:
Each data type exists of a class that extends the DataType class (defined in /flatCMS/classes/core/DataType.php). The base class is composed of the following functions, all of which can be extended:
- edit(string $name, string $id, string $value) : string
Returns a string that represents a field with name $name, id $id, and value $value, or any interpretation thereof, e.g. a select box will have the option with value $value selected, even though its text might be different.
- render(string $value) : string
Returns a string that represents the value for display on the page. This usually just returns the value, but for cases such as images or files it may return an image or link tag.
- process(string $name, string $value) : string
Returns the true value for storage after processing. In the case of a file or image, it will upload and store the file but return the path to the file as the value.
- validate(string $value) : boolean
Returns a true/false representation of whether the value passed was valid.
The best way to see how this works is to try editing a data type. All types are located under /flatCMS/data-types/ (this is configurable by editing /flatcms/config/paths.php).
Content types are defined using XML. The XML files are stored in the folder /flatCMS/types/[typename]/, [typename] representing the actual name of the type, e.g. "content".
There are two xml files:
- schema.xml: Defines the name and fields of the type
- default-content.xml: Contains the default values for fields of the type, and also default layout
A typical schema.xml file would look like this:
<description>Title of the page</description>
<description>Description of page</description>
<description>Keywords for search engines etc</description>
<description>Content of page</description>
A default-content.xml file would look like this, note that layout defaults are also defined:
<view path="main/title_and_text.php" />
Note: The best way to create a default-content.xml file is to create a new page that uses the type, and then copy it's content.xml to the content type folder, and rename it accordingly.
Layouts are located in the /flatCMS/layouts folder. These are simple php files that define the structure and style of the website. You can pretty much add whatever you want to these files, but it's recommended to keep them pretty simple and use includes and/or modules to display functionality generated by PHP.
There are a couple of functions which are instrumental to integrating your templates with FlatCMS:
- LayoutHelper::renderField(Page page, string field);
This returns a field for the page object, rendered according to the data type. Note that field names are case sensitive.
- LayoutHelper::renderPlaceHolder(Page page, string name);
This defines an area in the page in which to render views that can be selected by admin users. See placeholders section below.
- UrlHelper::getURL(string path);
This gets the URL for the current page, according to rules set up on the website.
This returns the root url of the website. Useful when adding assets such as images and CSS.
There are two templates included in the default installation:
- Home: This displays a two-column layout with two placeholders: 'main' on the left, and 'side' on the right
- Content: This displays a two-column layout, with one placeholder, 'main' on the right, with a sub-level navigation on the left.
Placeholders define different content areas on the template. For each placeholder, there are views that can be selected by administrators. These views are located in /flatCMS/views/[placeholder_name]/. If the folder is not already in existence, you will need to create one. Note that names are also case sensitive, so keep them in lower case when referenced in your template.
In the default installation, there are two placeholders:
- Main: This should be the largest and/or most prominent area in your layout. Some default views exist for displaying content in a rather generic way.
- Side: This is designed to show less prominent content. Currently, there is only a view for displaying latest items.
These are simple PHP files that render content. For the most part, you will only need to use the following methods:
- LayoutHelper::renderField(Page page, string field);
- require_once( getRootPath() . "/modules/controller.php" );
... Controller(string moduleName, string defaultMode, string modePrefix, array $params);
Modules are made using the modules framework and are stored in the /modules/ folder. You can then call them from your view by adding the following lines:
require_once( getRootPath() . "/modules/controller.php" );
$params = array();
$params["PAGE"] = $PAGE;
Controller("[module-name]", "[default-mode]", "", $params);
Extending the system
Paths are defined in /flatCMS/config/paths.php.
To create a new data type, simply create a new php file that contains the class for the type.
To create a new content type, copy the schema.xml and default-content.xml from an existing content type and place it in a new directory. then, modify the XML to set up your new fields.