Some documentation on the state of "Helpers"/Gadgets/Widgets etc. is at Helpers and Gadgets within Sakai. This page describes a particular implementation strategy for the markup-based "AHAH"-style helpers which are described there, which make use of RSF and the EntityBroker. This strategy for navigation interception is also known as Hijax.
Neither RSF nor the EntityBroker are required to adopt this strategy, nor need it particularly refer to "helpers" which are hosted within the Sakai server at all. RSF is illustrated because it is a technology which is now popular for new development in Sakai, and in which these techniques are quite easy. The EntityBroker is used, since as described on the Helpers, it is a good scheme for achieving short, semantically meaningful and architecturally decoupled URLs for application segments in Sakai, which are also meaningful when dispatched outside it. Use of the EntityBroker does not imply the use of RSF, but there is a standard framework integration between these technologies.
All of the code described here is present in contrib SVN at entity-broker-test. In order to be run correctly, it requires the EntityBroker and TestRunner to both be deployed into the Sakai installation. These should run in any Sakai later than 2.2.0, but will only be particularly well supported in 2.4.x versions.
Setting up an entity for the helper
To take control of part of the global URL space for the helper, you need to define an entity to represent it. Since this particular entity has no function other than being the target for a URL dispatch, this only requires 2 lines of code in the impl. It is conventional to use a "tag API" at the Sakai shared API level to provide easy access to the name of your entity. TestHelperProvider looks like this:
The implementation TestHelperProviderImpl for this interface simply represents that any entity ID will be permitted for dispatch (typical for a helper) and that it registers this prefix:
These parts of the process are independent of the presentation technology used.
Creating a webapp to host access to the helper
The helper webapp will be used to be the target of HTTP accesses to the helper. This need not be a dedicated webapp - it may be a webapp which is a traditional Sakai tool, as well as simply being a "pure Servlet" as in this case. It may also be a webapp which is being used to host any number of other helpers.
In RSF, the Spring definitions used to register a handler for a particular helper access look as follows (in applicationContext.xml):
where the implementing bean appears as
There is nothing special about this registration, since a "helper" of this form is really identical with any other form of Entity URL host within RSF. A special page on this topic is at Entity URLs in RSF.
The views forming the "helper space" are then defined as normal within the webapp, with the default view being the one nominated above as
Invoking the helper from a tool or other helper
This test application demonstrates accessing the helper from a different Entity space (
/direct/testentity which in itself is essentially another helper. If it were invoked directly from a tool, the Sakai portal CSS and JS would correctly resize the overall frame. The crucial "glue" needed to perform the client-side processing is in the file ahah.js which invokes standard JS functions within the RSF framework file
rsf.js. More of
ahah.js will be folded into the framework with RSF 0.7.3, but its essential code currently looks as follows:
This function accepts a DOM element ID and a URL (which need not form part of Sakai), and will initiate an initial AHAH fetch request at the URL whose contents will be written into the DOM node, with all navigation primitives "AJAXified" to themselves perform further submits via AHAH etc. Thus this DOM node from here on forms a self-contained "AHAH navigation world" in which navigation primitives rather than performing top-level navigation, simply rewrite the contents of the node.
Then we simply set up the peer for the target DOM node (the
The peering markup in testentity.html (which also has some limited behavioural preview functionality) in the markup template looks as follows:
Note that since as with all RSF templates, this "preview" definition is essentially functional, it also serves as a template for those who want to achieve the same effect in other presentation technologies (e.g. Velocity, JSPs, XSLT, etc.)
Limitations and future work
Currently the use of AHAH helpers within Sakai involves multiple server requests on the initial page load, in order to populate each helper's
<div>. In RSF version 0.7.3, a new dedicated component
UIDimensionalLink, as well as general framework reentrancy, will enable complex helper views, so long as they are dispatched solely within Sakai, to be aggregated on initial load within a single request, if the originating request is from an RSF webapp.