Search the Manual:

8.0 Developing New Modules for Bistro

This section of the Online Manual is currently being revised. For any questions on how to develop your own custom Bistro modules, we recommend you contact Lewis Media directly.

This section assumes that you are reasonably comfortable programming in PHP, that you are familiar with the concepts of Object Oriented Programming, and that you are comfortable with writing your own SQL queries. The files described in this section can also be downloaded for comparison from the distributors' website. For more information about these files or to obtain access to the distributor's site, contact Lewis Media.

8.1 Module Basics: Hello, World!

In this section we will walk you through the process of creating a simple module that will introduce you to all of the basic elements of module creation. This introduction is not a comprehensive guide to the Bistro module system, but it will provide you with sufficient information that with basic PHP skills, you should be able to begin developing your own modules.

Our Hello World Module will allow Admins to specify a one-line phrase that is stored in a database, a public page that will display the one-line text, and an AutoStuff tag that will allow Admins to post the text elsewhere on the site. Additionally, it will provide Admins with a basic configuration page where they can choose the colour of the text to be displayed, by entering a colour name or a hex code value.

8.1.1 The Module Skeleton

Before we get started, there are a few files that we need to setup to get the basic module functionality: the folder for the module, a module class file, and a module.php include.

So, to get started,

At this point your file structure should look like this:

Next, open up module.php, paste in the following code, and save the file.

You'll notice in the above code snippet, that we first check to make sure that someone isn't trying to execute code maliciously, then we include HelloWorld.php file that we created earlier (which is still empty) and then we identify the name of the module.

All modules have a file like this, and if you create a module in the future, you'll need to create one for that module too. Everything above that last line can be modified, but be sure you finish off by assigning a new instance to the variable $thisModule.

Next, open up HelloWorld.php, paste in the following code, and save it.

Basic Hello World File Contents

 

Looking at the above code snippet, there are a few lines worth noting:

Line 12

class HelloWorld extends AbstractModule

Within Bistro there is a pre-defined module called the AbstractModule which stores a default set of behaviour. The above line says that this module should use the default module to perform any actions that we don't define manually.

 

Lines 16 - 18

$this->settings = array(

'textColor' => 'red',

);

The above lines indicate that there is a variable for this module called textColor, and that we should store a value of "red" as the default value in the database. Although we could add any attribute to the class, by using the $this->settings attribute, the AbstractModule can automatically create the editing and saving screens for this setting.

 

Line 21

$this->details = new ModuleDetails('HelloWorld', '1.0', 'May 1, 2007');

This lines says that this module is called "HelloWorld", that it's version 1.0 and that it was released on May 1, 2007.

 

Line 25

$this->databaseTablesPrefix = 'hw_';

This line tells Bistro that the name of every database table that we create for this module should have the letters ‘hw_' added to the front of the name. This is valuable, as we can allow users to install more than one of copy of a module. We don't currently have any tables in this module, but for example, if users want two Page Manager modules, we can simply modify one to have a database table prefix that's different from the other, and both can reside in the same database.

 

Line 28

parent::__construct($paramaterArray);

This line tells Bistro to run all the initialization stuff that is defined in the AbstractModule. This holds very important instructions for your module, so remember to include it.

At this point, you can install your Hello World Module. To do this, log into Bistro, click on "Admin" and "Manage Your Modules". From there, find your module in the list of Modules to Install and click "Install". The page should refresh and show you an updated list, with your new module in the list of installed modules. To configure the module, click on the name of the module. This will bring you to a page as shown below:


Note, that we did not have to create this configuration screen; it was automatically generated by Bistro and the abstract module.

And there, we have the basic skeleton of a module. Once a module is created it can be easily installed and automatically integrated into any Bistro base license install.

8.1.2 Installation & Uninstall

When a module is installed, Bistro calls the install() method which returns true on a successful installation, and false on an unsuccessful installation. It also captures any HTML printed by the method and displays it to the screen. Similarly, when a module is uninstalled, Bistro calls the uninstall() method which returns true on a successful uninstall or false on an unsuccessful uninstall. If your module does not define these methods, then the default methods in the abstract module are used.

For most modules, allowing the abstract module to catch the call to these methods should be sufficient.

If you have any database entries that you would like have added to the database upon installation, add them to a file in your module's folder called install.sql.php, and add any sql queries for the uninstall process to a file called uninstall.sql.php. The abstract module's install() and uninstall() method look for these files, and processes them accordingly. For this example module, create these two files, copy their contents from below, and save the files.

install.sql.php File Contents

uninstall.sql.php File Contents

These install.sql.php and uninstall.sql.php will create and delete a mySQL table that has two columns (textName and textValue) and has one record: a record identified by the name "text1" and which has a value of "Hello, World!" Although we don't really need a full, dedicated table for this one value, we are using one to demonstrate how to interact with tables for this tutorial.

Looking at the above code snippets, you'll notice that the table is named databaseTablesPrefixHelloWorldText. What this actually means is that the table is named HelloWorldText but that it is being prefixed by the unique prefixes created by Bistro. The total prefix is a combination of the Bistro database prefix, and the module database prefix.

So, for example, if during the installation of Bistro Step 4 of the section 2.2.3. Running the Install Wizard you had specified a database prefix of "wa5h8_" and if we're using the prefix defined earlier in the Basic Hello World File Contents: Basic HelloWorld.php, then the actual table name in the database would be wa5h8_hw_HelloWorldText. This approach to database table naming makes it easier to install and uninstall modules, and to maintain a large set of modules in your Bistro installation.

Next, to make it easier to reference this table later, we're going to add a line to the end of the _construct() method in HelloWorld.php. Add the following line to the __construct() method as the very last line in the method:

$this->tableText = webAdminDbPrefix . $this->databaseTablesPrefix .'HelloWorldText';

At this point, double-check the install and uninstall process to make sure everything is still going smoothly.

8.1.3 Administration Screens

A key element of any module, is the ability for an Admin to interact with it, and to save changes. Here, we're going to setup our module so that an Admin can modify the text we have in our database.

When you click Site Content in WebAdmin, then click on the module name, the method that is called is the module's mainAdmin(). Typically, we will use this method as a controller, and use supplementary methods to actually generate output. So, open HelloWorld.php and add the following methods to the class:

 

8.1.4 Public Output

Ultimately though, we need to be able to print the output to the on the public side of the website, so we need to implement a method called mainPublic that will define the way Bistro prints out data. To do so, copy and paste the following code snippet as another method in the HelloWorld.php file.


At this point, you should be able to visit the public page of your module to see your coloured text. If you look at the address of your browser when looking at the admin side of your module, you should see an address similar to

http://www.mysite.com/admin/index.php?moduleId=0YFbGgTx

If you modify the URL to remove the /admin, then you will get something like

http://www.mysite.com/index.php?moduleId=0YFbGgTx

The above URL should be the public view of your module, which will allow you to test the functionality of your mainPublic() method.

8.1.5 AutoStuff and Responding to Hooks

The final part of this tutorial, involves getting your module to export an AutoStuff tag for other modules to use, and to export a link to the main public page of the module so that Admins can create links to the module when using a WYSIWYG editor.

To make this possible, we are going to respond to three hooks:

  1. returnLinks: this hook asks for a list of links available from this module
  2. returnAutostuff: this hook asks for a list of AutoStuff tags
  3. processAutostuff: this hook asks a module to replace any relevant tags with values

To respond to these hooks, we need to create the necessary hook methods (in this case we need three different ones) then we need to modify the constructor of our module to let WebAdmin know that we have hooks to work with.

To create the hook methods, copy and paste the following methods into your module's class in HelloWorld.php (note, for more information on how Hooks work, see section 8.2 Using Hooks).

Hook Methods

Every module has an attribute called myHooks that maintains a list of hooks that we have created. To modify this attribute in your new module, add this code snippet to the end of the constructor for your HelloWorld class

At this point you have completed the process of creating a new module that allows you to edit content in the database, to configure it, as well as to manage the hooks it publishes.

For more detailed information contact Lewis Media directly to register for the next Developers Seminar or obtain access to the distributor resource site.