Jozza.net

Developer Documentation

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.

Setup Guide

Setting up the system is dead easy, but this information is here for your guidance in case you're scared it won't work.

System Requirements

The requirements are very simple:

  • A web server (Apache recommended, IIS untested)
  • PHP 5 installed (Default configuration will do)

File Permissions

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:

<?php
...
$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.

Data types

These are PHP classes that define how data is displayed and rendered on the website. Default data types include:

  • String
  • Text
  • HTML
  • Date
  • Number
  • File
  • Image
  • Select

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

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:

<type>
	<name>Content</name>
	<fields>
		<field name="Title">
			<type>string</type>
			<description>Title of the page</description>
		</field>
		<field name="Description">
			<type>text</type>
			<description>Description of page</description>
		</field>
		<field name="Keywords">
			<type>string</type>
			<description>Keywords for search engines etc</description>
		</field>
		<field name="Content">
			<type>html</type>
			<description>Content of page</description>
		</field>
	</fields>
</type>

A default-content.xml file would look like this, note that layout defaults are also defined:

<content type="content">
	<fields>
		<field name="Title"></field>
		<field name="Description"></field>
		<field name="Keywords"></field>
		<field name="Content"></field>
	</fields>
	<options>
		<layout>default</layout>
		<placeholders>
			<placeholder name="main">
				<view path="main/title_and_text.php" />
			</placeholder>
		</placeholders>
      <active>1</active>
	</options>
</content>

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

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.
  • getRootURL();
    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

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.

Views

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

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:

<?php
require_once( getRootPath() . "/modules/controller.php" );

$params = array();
$params["PAGE"] = $PAGE;

Controller("[module-name]", "[default-mode]", "", $params); 
?>

Extending the system

Paths

Paths are defined in /flatCMS/config/paths.php.

Data Types

To create a new data type, simply create a new php file that contains the class for the type.

Content Types

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.