Features are used to add extra capability to Wookie widgets at runtime. Features typically inject scripts and stylesheets into widgets when they are viewed in the browser, for example to give access to a particular API or feature. Using features in your widgets will make them less portable across different platforms, so use them with care and, wherever possible, ensure your widgets degrade gracefully when an optional feature is not available.
Using features¶
A feature is enabled in a widget by adding a
Available features¶
Wookie provides a number of features out of the box. These include:
- camera - provides basic BONDI API access to a camera (camera example)
- jqmobile - provides JQuery Mobile (seed-widget example)
- oauth - provides an OAuth library (Facebook example, documentation)
- polling
- wave - an implementation of the Wave Gadget API (Chat widget example)
- wookie-ext - Wookie Extensions API
Create a feature¶
- Create a new directory in the Wookie /features directory for your feature
- Create any JavaScript (.js) or Stylesheet (.css) files you need in this directory
- Create a file called features.xml with the structure defined below.
Features.xml¶
A features.xml file must have <feature> as its root element, must contain a single <name> child element, and can have any number of <script> and <stylesheet> child elements.
The <name> element should contain an IRI identifying the feature - this is used to match against the <feature> element found in a widget's config.xml file.
The <script> and <stylesheet> elements should contain a src attribute with the filename to load. This must be relative to the folder for the feature - typically this is just the filename but you can also store CSS and JS files in subfolders within your feature directory if you wish.
Example features.xml¶
<feature> <name>http://jquerymobile.com</name> <script src="shared/jquery-1.5.min.js"/> <script src="shared/jquery.mobile-1.0a4-patched.min.js"/> <stylesheet src="shared/jquery.mobile-1.0a4.min.css"/> </feature>
Installing features¶
By default Wookie will look in its /features directory on launch and load any features it finds.
(There is currently no way to dynamically load a feature while Wookie is still running)
Configuring feature deployment¶
When you build and deploy Wookie using Ant, the features that are deployed are determined by two properties set in your build.properties file.
The default configuration looks like this:
# Uncomment to include Extra features include.extra.features # Uncomment to include Scratchpad features #include.scratchpad.features
If include.extra.features is not commented out, any features in the features directory of the working directory will be deployed.
If include.scratchpad.features is not commented out, any features in the scratchpad/features directory of the working directory will be deployed.
If both properties are commented out in build.properties then only the Google Wave Gadget API feature will be installed.
Adding scripts and styles to all widgets using the "widget" default feature¶
Wookie adds the default set of scripts and stylesheets to all widgets using a feature called "widget" which you can find in /features/widget.
Usually this is just the implementation of the W3 Widget Interface specification, plus some libraries needed for communicating with the server.
However, you can also use this to customize all the widgets, for example if you wanted to add a script for tracking, or to provide a common set of base styles, or a common shim for legacy browsers.
Just add your files to /features/widget and edit /features/widget/feature.xml to reference them, just like any other feature.