This is the Wookie templating system that can be used to create consistent user interface widgets. Using this system you can create a widget with just a few lines of code and then, in order make a change to the UI of all widgets, simply change the template. By using these templates you will ensure that your users have a consistent experience but also have an accessible experience since these templates are designed with accessibility in mind. * Installation To use these templates you need to install Apache Ant. Note, that if you install Ant on Ubuntu using apt-get you will also need to install ant-options (this is included on other platforms). * About Templates The templates directory contains all the wookie templates. There are, at the time of writing, two types of template, those that use JQuery Mobile and those that use Enyo. Enyo templates have names in the form of "enyoTemplteName" and JQueryMobile have no precursor to their name (at some point in the future we will probably make the JQuery Mobile templates conform to the same nameing standard, e.g. "jqmTemplateName". In all cases the appropriate "base" template of is the root of all templates using that framework. Any edit to the template will be reflected in all widgets that are generated after the edit (excpet where the edited behaviour has been overridden by a child template). ** Status The Enyo templates currently use Enyo 2.0 which does not yet have any UI components. Therefore the Enyo templates are pretty think on the ground with respect to styling. You can, of course, style everything using CSS but since the Enyo project predicts a release of the UI components in "about a month" (from launch in mid Jan 2012) it's probably best to wait. The JQuery Mobile templates have been used to build a number of widgets. They are fairly flexible but the current Ant based build system presents some limitations and unneccessary complexity. Furthermore, JQuery Mobile is designed for use only on mobile platforms. This can present some issues when being displayed on a desktop machine. Moving forwards we intend to continue experimenting with both the Enyo and JQuery Mobile templates. At this stage both implementations should be considered Alpha quality. * Creating Widgets from Templates Regardless of which framework you use the basic techniques for building widgets is the same. Of course, when you start building real widgets you will be using techniques specific to the chosen framework, but for the purposes of this introduction we will not be addressing these details. ** Building your first template based widget This section describes how to build your widgets. We start off with a simple hello world widget and then work through a number of customisations. *** Hello World Widget In this example we will create a simple widget that says hello to the world (what else would the first widget be?) * cd WOOKIE_HOME/widgets/templates/widgets * NB if you want to build your widgets elsewhere then see the advanced topic section below. * mkdir helloWorld * create a file called "./widget.properties * open widget.properties in your favourite editor and add the following lines (not including bullets): * template.name=base * widget.shortname=HelloWorld * widget.name=Hello World * widget.description=A very friendly widget to demonstrate how easy it is to build a widget from templates. * widget.id=http://www.apache.org/widgets/HelloWorld * Create a file called "content_primary.html" and the following content *
Hello World!
That's it, you have built your first template based widget. Now you need to generate and deploy it: * Ensure that Wookie is running locally * cd [WOOKIE_HOME]/widgets/templates/widgets * ant generate-all-widgets -Dwidget.include=helloWorld * take a look at your new widget in your local instance of Wookie ***Note:*** while this example creates the widget in the source tree of Wookie you should not develop your widgets here under normal circumstances. Instead you should define your own directory for widgets within your own project directory, see Advanced Topics, below. **** What did we just do? This section describes in some detail what you did above. ***** Widget properties Widgets are defined by a set of properties. The first set of properties are used by all widgets and are defined in "widget.properties". You created a widget directory and defined these properties by copying the default properties provided by the template system. Most of these properties should be self explanatory, with the exception of the "template.name". This is the name of the template your widget will be based on, for this demo we left that unchanged and defined a few of the basic properties that are used to ensure the user knows what a widget is when looking at the widget store. ***** Widget content The default widget properties configures the widget, but do not tell the template what content to display. Widget templates are intended to be self-documenting. You can find out what content a template expects to be provided by reading the appropriate files in the template. At some point in the future we will generate real documentation from these template files, but for now you need to do the leg work. To discover what properties are available to the template we look in "/templates/base/template_build.xml" and examine the "_init_template" target. You may see entries such as:Hello World
* cd .. * ant generate-all-widgets * Now take a look at your new widget in Wookie *** Javascript This is what you need in your "scripts/helloworld_controller.js" file: var ${widget.shortname}_user_controller = { init:function() { name = prompt("Please enter your name","Your Name"); $('#name').html(name); } }; $('#home').live('pageshow',function(event) { ${widget.shortname}_user_controller.init(); }); *** What did we just do? Files in the script folder that end with a "_controller.js" are added to the "controller.js" files provided by the templates being used. In this file you can define the controller for your widget. Note that you must use the ${widget.shortname} token and add a widget unique string to the object name in order to ensure the controller object is given a unique name. We also register an action to take when the page is loaded. In this case we define function in the controller that prompts for the users name and replaces the word "world" in the content with that name. Note that you can add additional libraries to your widget by placing them in a "lib" directory in the root of the widget directory. Be sure to add any copyright notices and licenses to a "NOTICE" file and "legal" directory respectfully. *** Overriding Template functionality The scripts provided by your widget implementation can override the functionality provided by the template. For example, the message template provides a simple interface for creating and sending messages. However, there is no way the template can implement the message send functionality since each widget will use a different delivery mechanism. For this reason the ${widget.shortname}_message_controller provides the following function: send:function(subject, message) { alert("Send message:\n\n" + subject + "\n\n" + message); } If you want to implement a true message widget you need to override this function in your widget javascript. To do this you simply add code such as the following to your widgets WIDGET_controller.js file: ${widget.shortname}_message_controller.send = function(subject, message) { // message send code here } ** Tiled Templates The Base Template provides functionality that allows it to provide a separate view that is used when the viewport is below a certain size. This view can provide reduced information and is designed for use in views that have multiple widgets on display at the same time. By default the maximum height and widget for a tiled viewport is 310 pixels. That is, if the viewport is 311 or more pixels in both width and height it will display the content defined in the #home div of the page definition. If the viewport is 310 or less pixels in either height or width then the content in the #tile div will be displayed. To customise the tile content your widget should provide a content_tile.html file. To customise the maximum viewport size for the tile view set the properties "widget.tile.max.height" and "widget.tile.max.width" (both default to 310). ** Common Files When building a family of related widgets you are likely to provide a set of common files that will be reused by multiple widgets. These can be placed in a directory called "common" in the same directory as your widget definitions. All files in this folder will be copied, with token replacement, into each widget. Because we use token replacement in these files too, it is possible for each widget to customise the common files appropriately. ** Advanced Topics *** Your own widgets directories You can create a widgets directory anywhere you want it. To create your own directory for widget definitions simply create the directory and copy [WOOKIE_HOME]/widgets/templates/widgets_build.xml into your new directory with the name build.xml. Now edit your build.xml file so that the value of the "wookie.root.dir" property so that it points to the root of your Wookie folder. You should also edit the name property of the root project element. Each of your widget definitions will then be contained in a sub-folder of the directory you created above. That is, you will have a directory structure like this: +- widgets | +- build.xml +- widgetDefinition1 | | | +- widget.properties | +- ... | +- widgetDefinition2 | +- widget.properties +- ... *** Multiple widget directories You can, optionally, have multiple widget sub-directories in your main widget directory, each of which can be deployed individually or as a whole. In order to do this create your additional widget directories and then edit your build.xml file in your main widgets directory to ensure that they all get built when calling the target "generate-all-widgets". There is an exmple in the build.xml file you created above. *** Deploying to alternative locations You can change the location widgets are deployed to by setting the property "widget.deploy.dir" in the command line or in the widgets build.xml file. *** Deploying in compressed or expanded form By default widgets are deployed in compressed ".wgt" files only. However, if you want to deploy in uncompressed (expanded) format you can do so by setting the propery "widget.deploy.expanded" in the command line or in the widgets build.xml file. To supress deployment in compressed form it is not quite so easy. You must first override the widgets_build.xml file (see "Your own widgets directories" above). In this file you will need to comment out the following line:Welcome to the ${widget.name}
You can also call methods in javascript provided by any of the templates used to create the widget, for example: