Xataface Application Framework
The previous sections have been laying the foundation for this section, in what will be our first "useful" module. Xataface comes with a set of built-in widgets that are quite useful, but once in a while, you will likely find yourself in need of a widget that doesn't yet exist. The internet is full of jQuery plugins that can easily be converted into Xataface widgets with very little effort.
The general strategy for creating a widget is:
For this tutorial we will be creating a Color Picker widget based on the eyecon colorpicker.
Xataface forms are based on HTML_QuickForm for its base set of widgets, but it uses a Widget Handler as a wrapper around these widgets as a means of configuring them. These wrappers are known as Widget handlers and they are managed by the Dataface_FormTool class.
A widget handler has to be able to do at least three things:
In most cases you can get by with only defining a single method (buildWidget()) in the widget handler and let Xataface just use its default handler to load and store the values in the widget.
There is no set place where the widget handler needs to go. Let's just add it to the root directory of our module, and call it
colorpicker_widget.php. Add the following content to this file:
The above widget handler doesn't do anything fancy yet. It simply creates a plain text field. After we have our widget working as a plain text field, we'll go back and transform it into a color picker.
Before we can use our new widget, we need to register the widget handler with the form tool. We'll make use of the
Dataface_FormTool::init event that is fired when the form tool is first created. This allows us to avoid loading the FormTool into memory unnecessarily. We'll do all of this in our module class's constructor as this is guraranteed to be executed at the beginning of every request that the module is enabled for.
Now that we have registered our widget, we should be able to use the widget. Let's set up a simple table in the database for this purpose:
And we'll create a fields.ini file for this table in the
We will use our new colorpicker widget as the widget for both the
Now that all of the pieces are in place, let's load up a new record form for the
color_profile table and see what it looks like.
color_profiletable by pointing your web browser to your application's index.php page with the GET parameters
If everything is working correctly, you should see regular text fields for the
background_color fields. This may be slightly disappointing, but this is what we want. We'll convert these into more interactive color-picker widgets in the next few steps. At this point we just want to be sure that our custom widget handler is working.
We start by downloading the Color Picker source files from the EyeCon website. After unzipping the ZIP file we should have the following directory structure:
So we have 3 types of content to contend with:
jquery.jsbecause we have our own version of jQuery with the Xataface distribution that we'll be using instead.
Similarly, we'll add the CSS files in a namespaced directory structure so that we can reference them uniquely. We'll place both the
images directories inside the
When we're done copying these files, the directory structure of our module will look like:
colorpicker_widget.php) in order to accommodate this:
All we've done here is create an
$atts array where we specify a
class attribute that is to be added to all color picker fields. We then add this as the 4th parameter of the
$factory->addElement() call (a call to HTML_QuickForm::addElement).
In short, all this does is add the css class
js directory. We'll place it at
Place the following code inside this file:
There isn't much in ths bootstrap file, but there's a lot going on.
registerXatafaceDecoratorfunction so that it will be executed for any part of the page that is added even after page load. This is important if you want your widget to work properly inside compound widgets like the grid widget.
ColorPicker()jQuery plugin to all elements with the
css directories are registered with the application when necessary. Otherwise our import won't work.
js directory. However we only did this inside the
hello_world action. This code is only executed for that one action and won't be executed for the
edit form or other Xataface actions that may require the colorpicker widget to be rendered. A simple solution would be to perform this registration inside our module's constructor, but then we may be adding unnecessary overhead to our application since most of the application has no need for our scripts.
To succinctly rephrase, our problem is:
Properties of the ideal solution to this problem are outlined in the wording of the problem itself. Namely, the ideal solution should:
To achieve this goal we will encapsulate the code that registers these files into our module's class as a method, and use a flag to ensure that they are loaded at most once.
Now if you reload the new record form for the
color_profile table and click on one of the colorpicker fields, you should see something like:
If you don't see anything like this, there see module_developer_guide_widget_troublueshooting
If you get really stuck, the best thing to do is seek help in the forum.
You can download the source for this module here.