Module Developers Guide

Why Write a Xataface Module?

Xataface modules are components that can be used to extend Xataface's functionality in a generic way so that it can be used on multiple applications. If you find yourself trying to add the same functionality in multiple applications, you might consider writing a Xataface module so that you can share the functionality more easily.

What can you do with a Xataface Module

• Create custom authentication handlers.
• Provide custom actions and templates.
• Implement blocks and slots for existing templates.
• Respond to certain application triggers.

Where do I place a Xataface Module?

Xataface modules can be placed in the xataface/modules directory (i.e. DATAFACE_PATH/modules). As of Xataface 1.3 they can also be placed directly in your application's modules directory (i.e. DATAFACE_SITE_PATH/modules).

Your first module

For our first module, we're going to create a simple module that adds "hello world" at the beginning of every page.

Step 1: Create the Module Class

In your modules directory, create a directory called "Hello". And in this directory, create a file named "Hello.php", with the following contents:

<?php
class modules_Hello  {
}

Step 2: Implement the block__before_body method

We are going to add the phrase "hello world" before every page of our application. The easy way to do this is to fill the before_body? slot of the Dataface_Main_Template.html? template. We do this by implementing the block__before_body method in your module (just as we would if we were trying to fill this slot from the Application Delegate Class.

<?php
class modules_Hello  {
    function block__before_body(){
        echo "hello world";
        return true;
    }
}

Step 3: Activate the Module

Xataface only loads the modules that have been enabled in the conf.ini. We can enable our module by adding the following section to the conf.ini file:

[_modules]
modules_Hello=modules/Hello.php

All this does is tell Xataface that the module class modules_Hello can be loaded from the location modules/Hello.php.

Now if you start up your application, you should see the phrase "hello world" written at the top of each page.

Example 2: Adding a Custom Action

Our first module shows an example of filling blocks and slots using a module. Let's now extends that to include a custom action that displays Hello World on its own page.

Complete the following steps:

1. Add an actions directory inside our new module directory. i.e. modules/Hello/actions
2. Add a file named hello.php inside the actions directory with the following contents:

   <?php
   class actions_hello {
       function handle($params){
           echo "Hello World";
       }
   }

3. Go to index.php?-action=hello To see the results of your action. It should say "Hello World" on a blank page.

From here on you can improve this action just as you would if you defined the action inside the application's actions directory. You can go on to restrict access to this action using permissions, or you could decide to use a template to display the action.

Defining a Custom "hello" permission for our action

Perhaps we want to create a special permission for our action so that regular users won't have access to this action unless they are specifically granted this permission. Let's create a "hello" permission with which to limit access to our action.

1. Create a file named "permissions.ini" inside your modules/Hello directory with the following contents:

   hello = Permission to access the hello action

Now if you try to access your action (and you haven't been assigned ALL() permissions) you should receive either a login prompt or a permission denied message.

If you want users to be able to access your action, you will need to explicitly add this permission to one of the user's assigned roles or return it as part of the list of authorized permissions in the getPermissions() method.

Granting the "hello" permission to the "READ ONLY" role

If we want the default READ ONLY role to have access to the "hello" permission we can actually modify the READ ONLY role inside the permissions.ini file that we created inside the Hello module:

hello = Permission to access hello action

[READ ONLY extends READ ONLY]
    hello=1

Example 3: Using Module Templates

Xataface, by default, stores its templates in the DATAFACE_SITE_PATH/templates and DATAFACE_PATH/templates directories. However if you are writing a module you probably want to keep templates that are used by the module inside the module directory so that you don't break dependencies when you use the module in different applications.

You can use the df_register_skin method to register additional directories for Xataface to look for templates in. This will allow you to add a templates directory inside your module directory for use by your module's templates.

It is probably best to register this directory on demand (i.e. as part of individual actions) rather than register it globally.

Using a Template from the hello action

Let's modify our hello action to use a template that we are going to store and distribute with our module.

1. Create a directory named "templates" in the modules/Hello directory.
2. Create a file named "hello.html" inside the templates directory with the following contents:

   {use_macro file="Dataface_Main_Template.html"}
       {fill_slot name="main_section"}
           Hello World
       {/fill_slot}
   {/use_macro}

   Notice that we are extending the Dataface_Main_Template.html template (which is located in the main Xataface install) so that our hello action can now take on the look and feel of the rest of the application.
3. Modify the modules/Hello/actions/hello.php file to look like this:

   <?php
   class actions_hello {
       function handle($params){
           df_register_skin('hello theme', dirname(__FILE__).'../templates');
           df_display(array(), 'hello.html');
       }
   }

   Notice that we call the df_register_skin function to register the templates directory that we created in the previous step. Then we call df_display() to display the template.

See Also=

• modules - A list of existing Xataface modules that you can download and install.
• block__blockname - A list of some of the available blocks that can be filled in the default Xataface templates.
• Customizing Xataface's Look and Feel with Templates - A tutorial on how to use Xataface's built-in smarty template engine. It has some sections on using delegate classes to override blocks and slots.
• Changing Xataface's Look and Feel - Part of the Getting Started tutorial that shows how to use slots and blocks to customize the Xataface look and feel.