• Assumptions
• First Steps
• Installation Location
• Registering
• User Accounts
• Environments
• Data Types
• Media Folders
• Generating the Files
• Writing Definition Files
• Writing Transform Files
• Integrating your Site
• Final Steps

Assumptions

I am going to assume that you are competent in OOP and are familiar with design patterns such as MVC and Singleton. If you are not then you may struggle with some of the concepts required to setup Roddeh CMS.

I am also going to assume that you have access to a webserver either running locally or remotely and that you have access to deploy files to this webserver.

First Steps

Start by downloading Roddeh CMS from here and unzipping it into a working directory.

If you have a webserver running on your machine then the following steps will be easier if your working directory resides somewhere within the root directory of your webserver. If you don't have a webserver running locally then you now need to deploy the files to your remote webserver.

In a browser navigate to the location that you have deployed Roddeh CMS and open cms_info.php

For example: http://localhost/roddeh_cms/cms_info.php

You should see the following message displayed.

You have successfully installed Roddeh CMS

Your installation is currently: unregistered
Your registration code is:

0 users have been setup.

0 environments have been setup.

0 dataTypes have been setup.

0 mediaFolders have been setup (only top level folders are included).	

In your working directory you will see a file named config.php. Open this file in your preferred text editor as we will be modifying this file in the steps to come.

Installation Location

The first value we need to set in config.php is the installation location of the CMS. This is simply the location that you use to navigate to the CMS administration interface.

For example: http://localhost/roddeh_cms/

Be sure to include the trailing comma as this is used to determine whether your version of Roddeh CMS is registered or not and must be exact.

Registering

To use Roddeh CMS you are required to register your site here.

However, if you are running Roddeh CMS off your machine locally and you are using the hostname "localhost", you will not have to register. All other hostnames are required to register even if you are just trying Roddeh CMS out.

After you complete the registration you will be presented with a registration code. You need to copy this code and paste it in the appropriate place in config.php.

//	REGISTRATION_CODE

$registration_code = "";

To check your registration return to the cms_info.php and it should update the following line to read.

Your installation is currently: registered.

If you are having trouble registering your site please ensure that the url you enter into the registration page exactly matches the url you are using to navigate to the CMS interface, including "http://".

User Accounts

The next step is to create all the accounts for the users who will be administering the site using Roddeh CMS. This is done by modifying the contents of config.php. Look for the section that looks like this.

//	DEFINE THE USERS

$admin_user->name = "admin";
$admin_user->hash = "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8";

$users = array(
	//$admin_user,
);

By default there is an admin user with the password "password" created for you. However this user has been commented out. You will also notice that the password is represented as a hash rather than being stored in plain text. This is a security measure.

Start creating users by copying and pasting the admin_user code and modifying it appropriately. To generate the appropriate hash for any given password using the generate_hash.php page.

For example: http://localhost/roddeh_cms/generate_hash.php

Copy and paste the generated hash into the correct user in config.php.

When you are done your resulting config.php file may look something like this.

//	DEFINE THE USERS
$user_jack->name = "jack";
$user_jack->hash = "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8";

$user_jill->name = "jill";
$user_jill->hash = "f0e4c2f76c58916ec258f246851bea091d14d4247a2fc3e18694461b1816e13b";

$users = array(
	$user_jack,
	$user_jill,
);

You can check your progress by navigating to http://localhost/roddeh_cms/cms_info.php and ensuring that it now says "n users have been setup." where n is the number of users you defined in config.php.

Environments

Environments are used by site administrators to test the publication of new data before it is published to the world. A typical site may have a "live" environment and a "staging" environment but can have more if required. Environments setup like this enable the site administrator to make changes in the staging environment and preview them in the flash website (assuming it has been setup to allow displaying multiple environments). The administrator could then decide whether they want to push the changes from the "staging" environment to the "live" environment.

Setting up environments is again done by modifying config.php. By default a "live" and a "staging" environment have been setup for you but they have been commented out.

//	DEFINE THE ENVIRONMENTS
$live->name = "live";
$live->label = "Live";

$staging->name = "staging";
$staging->label = "Staging";

$environments = array(
	//$live,
	//$staging,
);

You will notice that each environment has two properties a name and a label.

The name is used to define the folder that will store the data and the media for that environment on the webserver. The value for name can contain any characters including a-z, A-Z, 0-9 and "_" (underscore).

The label is simply a cosmetic field that determines how the environment will be referred to in the CMS when the administrator sees it.

Data Types

Roddeh CMS saves and presents data in an object oriented manner. When you design your data types you should design with this in mind. If you have an understanding of the MVC design pattern you will find this all very easy. If not I would recommend you familiarise yourself with its concepts. Here is a reasonable place to start.

Basically for every model in your flash application you will want to define a corresponding data type in the CMS. You do this by adding data types to the config.php file. There are some examples setup already (they have been commented out).

//	DEFINE THE DATA TYPES	
$SingletonExample->name = "SingletonExample";
$SingletonExample->label = "Singleton Example";
$SingletonExample->singleton = true;

$AbstractExample->name = "AbstractExample";
$AbstractExample->label = "Abstract Example";
$AbstractExample->abstract = true;

$SubTypeExample->name = "SubTypeExample";
$SubTypeExample->label = "Sub-Type Example";
$SubTypeExample->extendsType = "AbstractExample";
$SubTypeExample->instancePrefix = "ste";

$NormalExample->name = "NormalExamle";
$NormalExample->label = "Normal Examle";
$NormalExample->instancePrefix = "ne";

$dataTypes = array(
	//$SingletonExample,
	//$AbstractExample,
	//$SubTypeExample,
	//$NormalExample,
);

You will notice that there are range of options for each type. They are explained below.

The name is used to define the folder that will store the data for each instance of that type on the webserver. The value for name can contain any characters including a-z, A-Z, 0-9 and "_" (underscore).

The label is simply a cosmetic field that determines how the data type will be referred to in the CMS when the administrator sees it.

This is a boolean field that determines whether the type is intended to operate as a singleton type. Singleton types are useful for things like site wide settings. For more information on the singleton pattern checkout this page.

A boolean field that determines whether the type is intended to be abstract or not. You will not be able to created instances of any type that is defined as abstract. They are intended purely to be sub-typed by other data types.

If you want a data type to extend another data type you can define its super-type in the "extendsType" field. The general rules for inheritance and OOP apply in Roddeh CMS:

• You can have as many levels of inheritance as you like (within reason).
• Do not create circular references of inheritance.
• I would not recommend using inheritance for singleton types nor would I recommend extending a singleton type.
• The type you extend does not have to be abstract.

Media Folders

Media folders are also defined in config.php. They are used simply to help you organise any media files that are uploaded for the site. For example you may want to separate videos from images, thumbs from full size etc. Some sample media folders have been added to config.php and commented out.

//DEFINE THE MEDIA FOLDERS

$images->name = "images";
$fullsize->name = "fullsize";
$thumbs->name = "thumbs";	
$images->children = array(
	$fullsize,
	$thumbs,
);

$videos->name = "videos";

$mediaFolders = array(
//	$images,
//	$videos,
);

Generating the Files

We have now setup all the high level concepts for your site. The next steps fill in all the details of the data is structured for your site and how that data will be presented and manipulated through the CMS interface. This is controlled by JSON files, two for each data type that you setup earlier. One file is named definition.json and controls the structure of the data. The second file is called transform.json and controls how that data is presented in the CMS interface.

You can manually create these files at any time. Alternatively you can run generate.php to automatically create them for you.

For example: http://localhost/roddeh_cms/generate.php

In the location where you installed Roddeh CMS there should now be a directory named definitions. Inside the directory there will be one sub-directory for each of the data types you defined earlier. And inside each of these there will be two files definition.json and transform.json

Writing Definition Files

Writing definition files can be though of as being like declaring the instance variables for your model. In Actionscript you may have written something like.

private var title:String;
private var description:String;
private var price:Number;

In the definition file this is done like this.

{
	"singleton":false,
	"abstract":false,
	"properties":{
		"title":{
			"type":"string"
		},
		"description":{
			"type":"string"
		},
		"price":{
			"type":"float"
		}
	}
}

Accepted Types

Roddeh CMS supports the following types when you are defining up your properties.

• string
• int
• float
• boolean
• object
• array
• reference

Some types allow for extra control as outlined below. It should be noted that all of the extra controls for the property are optional unless otherwise stated.

There are a few naming restrictions when using properties. Basically you can not use any of the reserved words of the Actionscript language. In addition do not us the word "id" as it is automatically used by the name that you give your instances when they are created in the CMS.

string

Specifies a series of legal values for the property.

Specifies the maximum allowed length of the property.

Specifies the default value of the property.

		
//	Example
				
"properties":{
	"ageRange":{
		"type":"string",
		"acceptedValues":[
			"0-19",
			"20-39",
			"40-59",
			"60+"
		],
		"default":"20-39"
	}
	"email":{
		"type":"string",
		"maxLength":20
	}
}

int/float

Specifies a range of legal values for the property.

Specifies the minimum of the range.

Specifies the maximum of the range.

Specifies the level of accuracy of the range.

Specifies whether to include the minimum and maximum values as part of the range.

Specifies the default value of the property.

		
//	Example
				
"properties":{
	"width":{
		"type":"int",
		"range":{
			"min":0,
			"max":120
		},
		"default":"0"
	},
	"alpha":{
		"type":"float",
		"range":{
			"min":0,
			"max":1,
			"increment":0.01,
			"inclusive":true
		},
		"default":1
	}
}

boolean

Specifies the default value of the property.

		
//	Example
				
"properties":{
	"featuredProduct":{
		"type":"boolean",
		"default":false
	}
}

object

The object type is a convenient way of defining more complex data for a data type without having to define an entirely new data type.

Specifies the properties of the nested object. This is a required field when using a property of type object.

		
//	Example
				
"properties":{
	"background":{
		"type":"object",
		"properties":{
			"colour":{
				"type":int
			}
			"alpha":{
				"type":"float",
				"range":{
					"min":0,
					"max":1,
					"increment":0.01,
					"inclusive":true
				},
				"default":1
			}
		}
	}
}

array

Specifies the maximum and minimum number of items for the array.

Specifies the minimum of the range.

Specifies the maximum of the range.

Specifies whether to include the minimum and maximum values as part of the range.

Specifies the type of array e.g. ints, strings etc. This is a required field when using a property of type array.

		
//	Example
				
"properties":{
	"backgroundGradientColours":{
		"type":"array",
		"arrayOf":{
			"type":"int",
		},
		"range":{
			"min":2,
			"max":5,
			"inclusive":true
		}
	}
}

reference

A reference is used to link together data types. For example, you may have a "Book" data type and an "Author" data type. The "Book" could have a property "author" that references the "Author" data type.

Specifies the data type that the property references.

		
//	Example
				
"properties":{
	"author":{
		"type":"reference",
		"references":"Author"
	}
}

Writing Transform Files

Now that we have setup the structure of our data types in the definition file we need to provide a transform for the definition. The transform.json file controls how the site administrator will control the instances of each data type in the CMS. It specifies which form controls (e.g. CheckBox, RadioButton, TextInput etc) to use when manipulating each of the properties.

For each of the properties specified in the definition a corresponding property and control should be specified in the transform.

The following definition.json and transform.json illustrate this concept.

definition

{
	"singleton":false,
	"abstract":false,
	"properties":{
		"name":{
			"type":"string"
		},
		"age":{
			"type":"int",
			"range":{
				"min":0,
				"max":120,
				"inclusive":true
			}
		},
		"gender":{
			"type":"boolean"
			"acceptedValues":[
				"Male",
				"Female"
			]
		}
	}
}

transform

{
	"singleton":false,
	"abstract":false,
	"properties":[
		{
			"name":"name",
			"label":"Name",
			"control":"TextInput"
		},
		{
			"name":"age",
			"label":"Age",
			"control":"ComboBox"
		},
		{
			"name":"gender",
			"label":"Gender",
			"control":"RadioButton"
		}
	]
}

For each property in the definition there is a corresponding object in the definition with three properties: name, label and control.

Specifies the name of the property that is being referenced.

Specifies the label to use when the control is rendered in the CMS.

Specifies the control to use to manipulate the data in the CMS.

You may have also noticed that in the transform.json the properties are specified as a JSON array. This enabled you to control the order in which they appear in the CMS.

Controls

Roddeh CMS supports a range of controls including the following:

• TextInput
• TextArea
• ComboBox
• List
• CheckBox
• RadioButton
• VSlider
• HSlider
• ColorPicker
• ObjectPicker
• FilePicker
• DateChooser
• DateTimeChooser

Not all combinations of data types and control combinations are valid. The following table outlines the combinations that can be used.

An object does not need a control as its controls are determined by its child properties.

The control chosen for an array should be determined by what type of array it is e.g. an array of ints, strings etc.

Integrating your Site

Everything at the CMS end has now been setup. You will now want to integrate your flash site with the CMS so that when the site administrator updates the site the changes are reflected in your site. This is actually a pretty easy step.

Generating the Models

Roddeh CMS comes with a script that will generate the models for your flash website based on the definitions that you have created for each data type. To run this script simply navigate to the generate_classes.php page in your browser.

For example: http://localhost/roddeh_cms/generate_classes.php?package=com.package

Where package is equal to the base package of your project. The classes will be generated and will automatically be placed in a models package within your base package.

When the models have finished being generated you can find them in the as_classes directory where you installed the CMS.

Using the Models and DataLoader

Included in the zip that you downloaded there is a file named roddeh_cms.swc. Place this file in a location that will allow is to be compiled into your flash website.

Included in data_loader.swc are the classes that take responsibility for the following tasks in the following order:

• Download all the content in the CMS.
• Create instances of the classes that you bind to the data types (more explained later).
• Connect all the references between instances of the data types that were connected in the CMS.

The following is Actionscript code that demonstrates the usage of the DataLoader class.

package cms.example{
	
	import cms.example.models.Book;
	import cms.example.models.Author;

	//	Import the necessary classes to integrate with Roddeh CMS.
	import com.roddeh.net.LoadEvent;
	//	DataLoader does all the heavy lifting of downloading your content, connecting references etc.
	import com.roddeh.cms.DataLoader;
	//	MediaLoader is just a helper class that assists with the construction of URLs for media that 
	//	is stored in your CMS.
	import com.roddeh.cms.MediaHelper;
	
	import flash.display.Sprite;

	public class CMSExample extends Sprite{


		public function CMSExample(){
			
			//	I would strongly recommend putting the integration code somewhere in the constructor of 
			//	the document class for your application.
			MediaHelper.initialise("admin/", "live");
			
			var dl:DataLoader = new DataLoader("admin/", "live");
			dl.bindClass("Book", Book);
			dl.bindClass("Author", Author);			
			dl.addEventListener(LoadEvent.LOADED, function(event:LoadEvent):void{
				var books:Array = dl.getObjects(Book);
				for each(var b:Book in books){
					//	Will trace the title of the book.
					trace(b.title);
					var a:Author = b.author;
					//	Will trace the name of the author of the book.
					trace(a.name);
					//	Will trace the relative path of the file that has been set as the 
					//	cover image of the book.
					trace(MediaHelper.getURL(b.coverImage));
					
					continueInitialisation();
				}
			});
			dl.load();
		}
		
		public function continueInitialisation():void{
			//	By the time this code is reached you will have all the data for the CMS sitting in memory.
			//	You can now start rendering the interface.
		}
	}
}
		

Final Steps

Everything has now been setup and you are ready to start using the CMS and seeing the results displayed in your flash site.