Module Developers Guide[Permalink]
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
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 moduleFor 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 ClassIn your modules directory, create a directory called "Hello". And in this directory, create a file named "Hello.php", with the following contents:
(So this file would be located at DATAFACE_PATH/modules/Hello/Hello.php)
Step 2: Implement the block__before_body methodWe 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.
Step 3: Activate the ModuleXataface 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:
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 ActionOur 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:
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 actionPerhaps 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.
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" roleIf 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:
Example 3: Using Module TemplatesXataface, 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 actionLet's modify our hello action to use a template that we are going to store and distribute with our module.
See Also=
|