1. AsyncRequest
  2. Captcha
  3. Database
  4. Date
  5. DnsClient
  6. Form
  7. History
  8. HopObject
  9. HtmlDocument
  10. I18n
  11. ImageFilter
  12. IndexManager
  13. ListRenderer
  14. Mp3
  15. PodcastWriter
  16. RemoteContent
  17. Rss20Writer
  18. Utilities
  19. XmlRpcRequest
  20. XmlWriter

Description and usage of the Jala modules

AsyncRequest

Warning: This module is marked as ''deprecated'' in version 1.2 of Jala. It probably will be removed in a future version of Jala. Its functionality can easily be replaced with Helma's built-in app.invokeAsync() method.

This module provides a neat way to process time-consuming tasks which otherwise would pose the risk of a request timeout. Instead of fiddling around with scheduler or cron methods, you simply call the desired method from within a client's request. AsyncRequest then starts the method and immediately returns from the method call. Thus, the response can be quickly sent back to the browser - of course without stopping the running method.

Example: 

global.hare = function(msg) {
   var n = 0;
   while (n++ < 100000) {
      app.log(msg);
   }
   return;
};
var async = new jala.AsyncRequest(global, "hare", ["Zzzz!"]);
async.evaluate();
res.write("...he saw the Tortoise had reached the goal, and was comfortably dozing after his fatigue.");

Captcha

The module jala.Captcha requires the JCaptcha package. Due to license restrictions you need to manually download the JAR file providing the package and install it in Jala's lib directory.

A  captcha (an acronym for "completely automated public Turing test to tell computers and humans apart") is a type of challenge-response test used in computing to determine whether or not the user is human.

Example: 

Root.prototype.jala_action = function() {
   res.write('<form action="validate" method="post">');
   res.write('<img id="captcha" src="image" border="1" /><br />');
   res.write('<input type="text" name="input" />');
   res.write('<input type="submit" name="submit" />');
   res.write('</form>');
   return;
};

Root.prototype.image_action = function() {
   session.data.captcha  = new onLib.Captcha();
   session.data.captcha.renderImage();
   return;
};

Root.prototype.validate_action = function() {
   if (session.data.captcha && 
       req.data.input && 
       session.data.captcha.validate(req.data.input)) {
      res.write("OK.");
   } else {
      res.write("KO.");
   }
   return;
};

Database

The Jala Database module provides functionality to create in-memory or on-disk databases from within a Helma application plus various methods for basic database manipulation. In addition it also features a database server with which embedded databases can be accessed from outside using JDBC connections.

Date

jala.Date contains a Calendar prototype for rendering an XHTML calendar based on a HopObject collection, and methods for rendering a simple Html date editor component.

DnsClient

jala.DnsClient is your nifty helper when it comes to querying domain name server records.

Example: 

var dns = new jala.DnsClient("68.12.16.25");
var record = dns.query("zombo.com");
res.write(record[0].ipAddress);

Form

The Jala Form module eases setting and processing the basic cycle of HTML form rendering, validation and storing. A flexible and extensible type of form elements called components provide hooks to enable custom rendering, any kind of validation and storing properties at any custom location.

History

This module is an implementation of a Browser-like history stack suitable to use in any Helma application. The difference to a Browser's history is that this implementation ignores POST requests and checks if URLs in the stack are still valid to prevent eg. redirections to a HopObject's url that has been deleted. Plus it is capable to create new "intermediate" history-stacks and this way maintain a "history of histories" which is needed for eg. editing sessions in a popup window that should use their own request history without interfering with the history of the main window.

HopObject

This Jala module extends Helma's core HopObject prototype with the getAccessName method which can be used to find a free name "slot" in a HopObject's collection. Just think about a file upload which is going to add a named node to the collection. To prevent overwriting a node (or, even worse, a HopObject method) this method evaluates the desired name and potentially alters it with a traling number.

In the following example, a HopObject is assigned a property named "foobar". Then, the getAccessName method is called with "foobar" which returns "foobar1" because there is already a property with that name. Thus, it is now safe to add or set the property with the resulting name, without the risk to overwrite any property which is already set.

Example: 

var collection = new HopObject;
var desiredName = "foobar";
collection[desiredName] = true;
var resultingName = collection.getAccesName(desiredName);
res.write(resultingName);
collection[resultingName] = true;

HtmlDocument

This module provides easy access to the elements of an arbitrary HTML document. By using TagSoup, Dom4J and Jaxen even invalid HTML can be parsed, turned into an object tree and easily be processed with XPath expressions.

Example: 

var mime = getURL("http://zombo.com");
var doc = new jala.HtmlDocument(mime.getText());
var links = doc.getLinks();
var i, l;
for (i in links) {
   l = links[i];
   res.write('<a href="' + l.url + '">' + l.text + '</a><br />');
}

I18n

Jala I18n is a JavaScript library providing functionality to internationalize Helma applications. It is compatible with  Gnu gettext in that it produces standard PO files for translation purposes and converts PO files into JavaScript message catalog files that can be used within Helma applications.

Being compatible with the widely used GNU gettext format means first of all that translation messages will appear in a readable manner in code and skins of a Helma application, so instead of needing to define more or less cryptic message keys like user.login.error you can put the localized message directly into the application code or skins, eg. "The login failed. Please make sure to specify the correct username and password". As an additional benefit Jala I18n supports parameter substitution, which allows to add dynamic content to translated messages (eg. the current date formatted in a locale specific way, or values formatted using the appropriate currency symbol).

Internationalization based on Jala I18n is done in six steps:

  1. Include the library into your application
  2. Mark messages that should be translated with specific method calls and/or macros.
  3. Use Jala's HopKit to generate a PO template file (.pot) containing all messages that should be translated.
  4. Translate the messages using a standard PO file editor (eg.  PoEdit) for the desired locales.
  5. Convert the PO files containing the translations into JavaScript message catalog files using Jala's HopKit.
  6. Include the message catalog files in the application.

ImageFilter

This module provides several Jpeg image manipulating methods. Most of this filter library is based on filters created by Janne Kipinä for JAlbum. For more information have a look at  http://www.ratol.fi/~jakipina/java.

Example: 

var filter = new jala.ImageFilter("/tmp/image.jpg");
filter.gaussianBlur(2, 10);
var img = filter.getBytes();
res.contentType = "image/jpeg";
res.writeBinary(img);

IndexManager

This module basically sits on top of a helma.Search.Index instance and provides methods for adding, removing, optimizing and rebuilding the underlying index. All methods except rebuilding are executed asynchronously using an internal queue that contains jobs created for each call of add/remove/optimize. Rebuilding is somehow different as it puts this manager into rebuilding mode where all following calls of add/remove/optimize are queued, but the queue is not flushed until rebuilding has finished. This ensures that objects that have been modified during a rebuilding process are re-indexed properly afterwards.

ListRenderer

The ListRenderer module eases the rendering of arbitrary lists. Such lists can be represented by HopObject collections or Arrays of HopObjects. Various arguments provide customization of the number of items per page, the maximum of pages and so on.

Mp3

jala.Mp3 is the successor of jala.Mp3Info and provides various methods not only for retrieving but also storing metadata in ID3 Version 1 or Version 2 tags of an arbitrary mp3 file.

PodcastWriter

A module to create, modify and render standard-compliant RSS 2.0 feeds including support for  Apple's Podcast specification. Please refer to the XmlWriter module for more information.

RemoteContent

API to define, fetch and update content from a remote site. In a basic setup the fetched remote content is stored in an XML file for caching purposes in case of re-retrieval.

The RemoteContent prototype is an extension of the helma.Http module. Thus, all the HTTP options provided by the latter are available in RemoteContent instances, too.

Example: 

Root.prototype.main_action = function() {
   var remote = new jala.RemoteContent("http://zombo.com");
   remote.setHeader("X-RemoteContent-Host", req.data.http_host);
   remote.setInterval(Date.ONEMINUTE);
   remote.update();
   res.write(remote.toString());
   return;
};

global.scheduler = function() {
   jala.RemoteContent.exec(function(remoteContent) {
      if (remoteContent.needsUpdate()) {
         remoteContent.clear();
      }
      return;
   });
};

Rss20Writer

A module to create, modify and render standard-compliant RSS 2.0 feeds. Please refer to the XmlWriter module for more information.

Utilities

This module contains a set of utility and helper methods which do not fit anywhere else (and actually are not complex enough to fit a module on each own). The current methods are

  • createPassword
  • diffObject
  • patchObject

Examples: 

// Creating a password only containing letters (8 characters), e.g. "oramazep"
res.write(jala.util.createPassword());
// ...mixing letters and numbers (15 char's), e.g. "obezoyi3yejeboh"
res.write(jala.util.createPassword(15, 1));
// ...mixing letters, numbers and symbols (20 char's), e.g. "everizuvoh%epadi1rex"
res.write(jala.util.createPassword(20, 2));

// Patch an object with the result of an object diff
var obj1 = {a: 1, b: 2, c: 3};
var obj2 = {a: 1, b: 0, d: 5};
var diff = jala.util.diffObjects(obj1, obj2);
jala.util.patchObject(obj1, diff);
res.write(obj1.toSource()); // {a: 1, b: 0, d: 5}

XmlRpcRequest

XmlRpcRequest is a JavaScript re-implementation of the built-in Helma XmlRpc client, featuring the following additions:

  • changeable encoding (due to the underlying  Apache XmlRpc library version 2 coming with Helma) there are only UTF-8 and ISO-8859-1 available)
  • the ability to define a HTTP proxy to use for the request
  • HTTP authentication
  • setable connect and read timeouts
  • a special debug mode where the XML request and response source are stored as part of the result object
  • due to the different structure compared to the Helma XmlRpc client method execution can also be done using JavaScript methods apply() and call()

XmlWriter

The XmlWriter module defines a generic interface to write arbitrary and validating XML source code. This is done by first applying data objects onto template objects, both in a specified format. Then, the resulting object tree is transformed into XML. Moreover, template objects can be extended with other template objects to provide full flexibility in inheriting subclasses.