The HopKit

To use HopKit you need at least a working installation of Apache Ant. If you want to use HopKit's API documentation task you also need a working installation of Perl. *nix machines usually have that preinstalled, while on Windows machines ActivePerl is a good choice.

Internationalization

HopKit can be used to easily parse Helma application code and skins and create a "Portable Object" (PO) template file which can be used to translate applications for a number of locales. In addition HopKit offers a second task to compile a set of translation files into a JavaScript message catalog bundle which is used by the I18n module.

For more information about the tasks pot and messages please have a look at the documentation for the I18n module.

API documentation

HopKit contains a task to easily create the API documentation of Helma applications. In general this task first copies the whole application code into a working directory, prepares the code for documentation generation (by performing various string replacements inside .js files) and finally invokes the Perl based JSDoc framework for generating the API documentation. Therefor you need to have a working installation of the Perl interpreter on the machine where you want to use this HopKit task.

To use the API documentation task simply invoke it by entering the following on command line:

[path/to/HopKit/]build.sh docs

on *nix machines, resp. on Windows:

[path/to/HopKit/]build.bat docs

HopKit will first ask for the location of the application code:

[input] Directory containing the application code (./code):

By default it assumes that the code resides in the subdirectory code of the current working directory (following the "best practice" that an application directory contains subdirectories for code, skins, docs and optionally other things related to the application). To override this enter a relative or absolute directory path where the application code is located.

The next thing you will have to specify is the destination directory where HopKit should place the generated API documentation:

[input] Destination directory for the documentation (./docs):

Again, HopKit would by default place the documentation inside a subdirectory called docs. To override this enter a relative or absolute directory path.

Finally, you can specify a name for the project which will be used in the generated HTML pages containing the documentation.

[input] Name of the project:

This is optional, so you don't need to enter a project name. After hitting the Enter key HopKit will start to create the API documentation.

build.properties

The I18n and API documentation tasks of HopKit require entering data to be able finish correctly, which can be quite tedious if you need to run them over and over again. Therefor HopKit respects a file called build.properties located inside the application directory containing the "answers" to the questions of a HopKit taks. Eg. assuming that you have an application called myApp in the apps directory of your Helma installation, which structure looks like this:

helma/apps/myApp
helma/apps/myApp/code/ -> the application code
helma/apps/myApp/skins/ -> the skins needed by the application
helma/apps/myApp/docs/ -> the API documentation
helma/apps/myApp/i18n/ -> the directory containing the "Portable Object" (PO) files for internationalization

you can place a build.properties file inside the directory helma/apps/myApp containing the following property definitions:

###########################################
## Properties used by HopKit "docs" task ##
###########################################

## build properties for jsdoc api documentation
docs.source = ./code
docs.destination = ./docs
docs.projectName = My Application

##########################################
## Properties used by HopKit "pot" task ##
##########################################

## the name of the template file to create
## (including any relative or absolute path)
i18n.template     = ./i18n/messages.pot

## the directories to scan for gettext function
## and macro calls (separated with spaces)
i18n.scan         = ./code ./skins

###############################################
## Properties used by HopKit "messages" task ##
###############################################

## the directory containing the .po files
i18n.poDirectory  = ./i18n

## the path to the directory where to put the Javascript
## message catalogs bundle
i18n.destination  = ./code/Global/i18n/

## the namespace to use
i18n.namespace    = myApp

Of course, if your application doesn't need internationalization you can exclude the property definitions for the "pot" and "messages" task.

From then on you only need to change the working directory to where the build.properties file is located and call HopKit's build.sh (resp. build.bat on Windows) from there, and HopKit won't bother you with questions anymore.