In this tutorial we will create a simple module that merely prints "Hello World" at the top of all pages in the site.

Step 1 Create An Application

Creating a module is boring if you don't first have an application to test it out in. So before moving onto the rest of this tutorial, make sure that you have an application available to enable your module in.

If you don't know how to create an application, please refer to the Xataface Getting Started tutorial.

Attention: For the remainder of this tutorial we will assume that we have created an application and it is located at
/var/www/myapp/

Step 2 Create A "modules" Directory

If your application doesn't already have a modules directory, create one now. i.e. Create the directory:

/var/www/myapp/modules/

Attention: This assumes that your application is located at /var/www/myapp/ . Change the path accordingly for your application's installation location.

Step 3 Create a Directory For Your Module

We're going to call our module "Hello World" so we'll name the directory hello_world. The directory is located at:

/var/www/myapp/modules/hello_world

Step 4 Create Module Class

All modules need to have at least a base class that serves as an entry point for the module. This class should be located in a file named modulename%.php and the class name should be modules_modulename% . E.g. The file should be located at /var/www/myapp/modules/hello_world/hello_world.php and the class file should contain the following contents:

class modules_hello_world {
}

Step 5 Implement the before_header Block

We want to display "Hello World" at the head of every page in the site so we'll implement the before_header block in our template. Modules allow you to implement blocks and slots the same way as you can implement them in table Delegate classes and Application delegate classes.

class modules_hello_world {
    function block__before_header(){
        echo "<h1>Hello World</h1>";
    }
}

See Also: ModuleClass::block__blockname(); DelegateClass::block__blockname(); ApplicationDelegateClass::block__blockname()

Step 6 Activate the Module

At this point, the module is inactive because we haven't told our application to use the module. To activate the module all we need to do is add a [_modules] section to the application's conf.ini file (if it doesn't yet exist), and add the following line:

modules_hello_world=modules/hello_world/hello_world.php

(The full modules section would look like:

[_modules]

modules_hello_world=modules/hello_world/hello_world.php

)

Step 7 Load the Application in the Browser

Now point your web browser to your application and notice that "Hello world" is displayed in large print at the beginning of each page.

Help with Slots

This tutorial leverages Xataface's built-in block/slot system that allows use to embed content into various locations of the templates. You can always get a full list of the blocks and slots in a given template by turning on debug in your application. The interface will then be rendered with the available blocks and slots rendered.

For more information about blocks and slots see The wiki page for block__blockname or one of the following additional tutorial links dealing with Xataface user interface customization:

Troubleshooting

I Don't See Hello World

If you don't see "Hello World" at the top of each page and there are no error messages, there are a few possible problems:

Your block function is not named correctly. Ensure that your function is named exactly block__before_header . Note the two underscores between block and before_header.
Your [_modules] section is named incorrectly.
You have two [_modules] sections defined in your conf.ini file and one is overriding the other. You can have at most one [_modules] section.

Some Example Module Classes

Since every Xataface module must have a module class, there are plenty of examples of the structure of such classes from existing modules. The following are links to documentation pages for some module classes already in existence. Some use more features than others. Later tutorials will cover all of the possibilities of this class in more detail:

Return to Module Developer's Guide
Next: Creating a Module With an Action