Building a frontend class
From Site Foundry
When building a module, the class that takes care of and controls all front end functions are carried out by the frontend.class.php. When the Site Foundry core assignes a resource (module) to an area in the page object model, this class will be instantiated at the time of page rendering.
The following simple tutorial will take you through the basics of building the frontend.class.php of your module.
Contents |
Module basics
From our example in Building modules, you will remember that a module is, at it's most basic three files:
- /modules/module_name/config.ini - general settings for the module.
- /modules/module_name/frontend.class.php - the class that is instantiated by the page object model.
- /modules/module_name/backend.class.php - the class instantiated by the management section of the Site Foundry application to carry out any management functions.
Of course, this will be true in most circumstances, but depending on what you require the module to achieve, as long as you have the config.inc file, and at least one of the other class files, then the module will work. If you only require the module to carry out a management function then you only need the backend.class.php; and vice versa if you only require front end functions.
The usual hello world example
As usual with these things, we thought that the simplest place was to start with the tried and tested hello world example.
Create the files and folders
Create a folder in /modules/ with the name hello_world. In that folder you will need to create the following empty files:
- config.inc
- frontend.class.php
You should then have something that looks like this:
Set up config.inc
Open up the config.inc file in your favourite text editor, and add the following code:
[module_details] resource_name = hello_world menu_name = uri = hello_world management_inc = false direct_template = false front_end = true template_upload = false additional_templates = false templates = ""
And here's why:
- resource_name - this is the name of the folder, and the class contained therein.
- menu_name - leave this empty, as it's not going to appear in the module drop down.
- uri - needs to be the same as the resource_name
- management_inc - we don't want to include this module in the module drop down.
- direct_template - we don't need any direct edit functions.
- front_end - we want to be able to assign this module to the front end (hence requiring a frontend.class.php).
- template_upload - we don't need to upload any templates.
- additional_templates - no additional templates required.
- templates - so we can leave this blank.
Make the frontend.class.php return 'hello world'
The frontend.class.php is just a php class within a file that is instantiated, and the render method called to return content. So all we need is the usual class construct, with the same title as the resource_name above:
<?php
class hello_world
{
}
?>
This will run, but it won't do much. To test this out (and make sure that Site Foundry doesn't respond back with any errors), save the file and log into the management section of you installation.
- 1. Go to manage pages, and click on a page that you know you can use too test.
- 2. Assign your hello_world world module to an area on the page as follows:
- 3. Refresh your view of this page within the front end of the application to see any changes that you've made.
Hopefully you should see a blank page (unless you have other things assigned within the page object). This is a good thing, rather than bad.
So, to make it even better, lets add in a render method, and return something to the Site Foundry page renderer - and what else will you return but hello world:
<?php
class hello_world
{
function render()
{
return "Hello world";
}
}
?>
And for your moment of triumph, refresh your browser, and you should see hello world proudly displayed in your browser. Make sure you are running this from an fresh install of Site Foundry to avoid additional complication.
Extend your class
Generally it's good to extend your class so that you can have access to the methods available in the main frontend class. This is rather easy, just add extends frontEnd to your class as follows:
<?php
class hello_world extends frontEnd
{
function render()
{
$email = "myemail@domain.com";
if(parent::isValidEmail($email)) return "That email is valid!";
else
return "That email isn't valid";
}
}
?>
Please note that this is only regex match, it's not a complete domain check as windows doesn't support the function, and we didn't want to go down that path.
And there you go, it's all rather easy, that is as simple as the class needs to be. Next we'll move on to some other helpful function that you can add to your class to help you do things.
Doing more
Clearly you are going to want to do more than just echo out 'hello world' - so the following will guide you through the bits and bobs that you can use in your class to control your module.
The following block of code shows how to extend your class:
<?php
class newmodule extends frontEnd
{
/**
* Contains all module arguments
* @access private
* @var array
*/
private $moduleArgs = NULL;
/**
* Instance of Smarty
* @access public
* @var object
*/
private $smarty = NULL;
/**
* Page parameters
* @access private
* @var array
*/
private $params = NULL;
/**
* Constructor
* @param array $moduleArgs
* @param array $param
*/
function __construct($moduleArgs,$param)
{
// Assign arguments to the class
if(is_array($moduleArgs)) $this->moduleArgs = $moduleArgs;
else $this->moduleArgs = unserialize($moduleArgs);
// Assign all params to the class variable
$this->params = $param;
// Start smarty and assign useful data
$this->smarty = new Smarty();
$this->smarty->assign("FS_URI",FS_URI);
$this->smarty->assign("param", $this->params);
}
public function render()
{
debug($this->params);
debug($this->moduleArgs);
}
}
?>
So lets go through this bit by bit, so that we can understand what's going on.
Class member values
private $moduleArgs = NULL;
The moduleArgs are passed to the front end class at time of instantiation, containing the settings that the administrator has chosen in manage pages.
In this case you will have:
Array ( [resource] => newmodule [template] => )
Where the resource is the class/module that you are working with, and template (or mode as we said before) is something further selected by the administrator. Of course, you can save any data you like into the moduleArgs in the management of your module. This is a good place to put anything that is critical for one particular instantiation of your class, as it is always possible to assign any module to all areas available on a page. This means that you can create distinct modes for your module, selectable by the administrator using the application.
private $smarty = NULL;
Just creates a neat version of smarty for you to return to the main template.
private $params = NULL;
The params are a neatly formed up version of the URI that is being passed to the application - broken up into pages and wildcards.
In this case, if you're working with a fresh copy of Site Foundry, then you will have:
Array
(
[page] => Array
(
[0] => welcome_page
)
)
Try setting the page wildcards, and adding a few forward slashes to your URI (e.g. www.domain.com/welcome_page/one/two/three) - you will notice that you now have these passed as additional params in the form of wildcards:
Array
(
[page] => Array
(
[0] => welcome_page
)
[wildcards] => Array
(
[0] => one
[1] => two
[2] => three
)
)
Constructor
Inside the constructor, we sort out the moduleArgs and params for our object, as well as getting smarty instantiated, and passing it some useful bits of data.
Render method
You can see the use of the debug to output the values being passed to the object. In this way, the functions of the module can be controlled by the URI, and set up by the configuration of an administrator.
Thus, the options for working with the class are up to you - connect to as many external files as required, process user inputs etc - all rather easily.
