Building modules
From Site Foundry
Building modules in Site Foundry is rather easy (it may look daunting now, but once you understand the principals... we'll stop that train of thought there; there's no point in going into a patronising explanation of what you will/will not be able to do). This part of the documentation will focus on getting you up and running, with both explanations, and tutorials on how to achieve the best application for your client.
To start with, it would be a good idea to look over the how it works section for more information on the Page object model is rendered, and the idea of creating resources to be used by the Site Foundry core.
Following, is a little more information about the rationale behind a module, its purpose and how they are implemented.
Contents |
What's a module?
A module is simply a resource (class) that is instantiated by the Site Foundry core at runtime to produce data (e.g. HTML, XML etc) that is applied to an area of the page. This data can be predefined, or user defined (by the URI string or GET, POST and SESSION variables) each time the page is refreshed. Is is possible to have as many of these as you like, and assign as many of them as you like per page - you're only restricted by usability and the site of your server.
Each time a page is requested (e.g. www.domain.com/a/reference/to/a/page), the page object that is associated to this URI will be rendered. This page object (as distinct from other page objects referenced to other URI's within Site Foundry) will call (instantiate) each resource (class), and place it in its relevant area. In this way, each page can be made up from any number of modules, or the same module displaying distinct items of data.
In it's simplest form, a module is three files:
- /modules/module_name/config.inc - 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.
In the process of the following example, we will endeavour to explain the roles of each of these files.
An example
Lets imagine that you need to write a module that displays news articles. On the surface this may seem rather simple, but your client is looking to not only display a nice list of news stories, they also want to categorise the articles and create further associations to contributors. With Site Foundry, there is quite a simple methodology available to tackle this problem. The following items stand as a guide:
- Understand how many states you require the module to fulfil
- Will the module require any interaction from the user?
- How will this data to be displayed
- And finally, how will your client administer this process?
Module states
Firstly, lets tackle states.
The state or mode of a module could be defined as a template. When coding for Site Foundry first started, we thought about states/modes as templates; but as the software developed the idea of the template has faded as the it doesn't really convey exactly what's going on. Unfortunately, the moniker stuck, so we have to use it.
So for our example, our module will need to display:
- The news
- Latest news
- News categories
- A news category
- A contributors news stories
Each of these will need to be a distinct state of the same frontend.class.php inside the module folder. These states will form the basis of the main procedural part of the module inside the frontend classes render method, passed from the template value for this resource via the page object model. Each of these states will be set by the administrator when they allocate the module to an area, and then set the template.
The following is an example of the logic that you could use:
<?php
switch($this->moduleArgs['template'])
{
case "latest_news":
// Return a list of the latest news items
break;
case "news_categories":
// Return a list of links that enable a user to browse all items in a category
break;
default:
// Return the main list of full news items, and an individual item
break;
}
?>
Of course you can link to other classes etc, its just a place we usually start with in defining the state of the module, each time it is instantiated. As long as you are returning formatted (rendered) data to be placed inside the main template, then you can do whatever you need to do.
Interaction
For our example, we have no interaction (incoming user submitted data), though we will have requests for individual news stories. We find that it is best to do this with a URI safe string, rather than an ID. In this way, there is more meaning in the way that URI looks. Thus, the incoming URI will look like:
www.domain.com/news/a_great_news_story
You can see above that a page called news is being requested - which will then have the news module assigned to an area (with wildcards turned on); a_great_news_story will then be passed as a wildcard to the all modules rendered within the current page object - but only our module will do something with it. This is why it is always important to cover the states of a module first, so that what is being passed from the moduleArgs will dominate anything the module returns.
Now that the wildcards are defined, then you can see that it's rather easy to retrieve that matching record, format it, and return it via the render method. The most important thing to remember is that you can only have one main function per page that is interacting with user input - unless you have a number of functions that will perform different actions based upon the same data - perhaps a user selecting an article, that will then pull out a video file based on that selection.
Display templating
As each modules templates are independent of the main page template, it is possible to create states that can return data formatted up as XML, HTML etc. These choices are as simple as deciding what format you want the data output to be, then creating a state (and hence calling a different template).
So if we wanted an XML feed for our news module, we would create an XML state, create an XML template, and retrieve the appropriate data to push into the template.
Administration
Often this is the most difficult part of the module, as the management of Site Foundry is much more restrictive that the front end. To familiarise yourself with the way that the backend works, it would be advisable to have a look around our example site at The Big Media Company.
The Site Foundry core works around a consistent process of overview then item display. In this way, we have found that you can manage complicated tasks simply. Of course, you can do whatever you want within the display of the management tool (see figure below):
The reasoning behind the core workflow is based on a simple data organisation hierarchy. Most of the time, modules are based on a main table (in our example, a table of news articles) then on any connected data stored in any number of other tables. If this is the case, then it's rather easy for an administrator to navigate to a page linked to the module, view a list of items (essentially every row in the main table - paginated if you want it to be) - and then provide a way of viewing the data in each of these rows, connecting to the server via AJAX to speed things up. We have found that this method works in the vast majority of cases, and makes it conceptually easy to manage complicated database tasks.
Site Foundry provides a number of AJAX functions for passing data back and forth from your server, as well as locations to carry out any administration tasks. The following list outlines these locations:
- Main window - This is accessed from the main menu, with your module title shown in the modules drop down.
- Direct Edit - In the manage pages section of the management of the application; located alongside the assign template areas dropdowns, each area has it's own direct edit link that will allow for any customisation directly for that area.
- Template manager Direct Edit - This works the same as direct edit, but instead of the editor just being for the one page object, the changes will be saved globally for any page using that template (unless you override it in manage pages).
Using these locations will allow you to offer comprehensive tools to administer your module.
So back to our example - we will want to:
- Edit the news articles - which we will do in a main window, displaying the list of articles, then clicking through to show the data for each row.
- Choose a category to display in an area - do this in the template manager, and manage pages using direct edit. In this way we can assign our module to an area, and then using direct edit, further refine what is displayed.
That concludes our little example. The best place to go to now would be to do the tutorial below, building the example module.
Building a module
To build a module, we offer the following information - it also stops this one from becoming colossal
Some background information
- The configuration file
- Table naming conventions
- Available constants
- Methods available in the main frontend class
- Methods available in the main backend class
- Available global functions
Tutorials
If you need more help, please don't hesitate to get in contact with us.
File downloads
To help you get going, and have a place to start for the above tutorials, all the files you need for a simple module are here. These are in no way comprehensive, but if you do the tutorials above, then you will be well on your way to creating module.
