Introduction

The purpose of this article is to provide an example of using the Helium shared libraries feature.

The source code of most Helium releases can be imported for a DSL app by specifying the libraries to import as part of the app source code and using the repo and fetch-libs commands. When importing with fetch-libs the files are simply imported into the developers workspace which will be bundled into the built application when using the build, run or release commands.

Before getting started with this article please make sure you have read through and understand the concepts discussed in Using the HeliumDev Client and Deploying Apps.

Releasing a Library

As mentioned, most normal app releases can be used as a library. One specific requirement for releases that are to be used as libraries is that a web-app folder is included in the library. It is, however, also good practice to not import the source code for stand-alone DSL apps as libraries. Conventions, such as proper naming of releases, should be followed to make a clear distinction between releases representing libraries and releases representing stand-alone apps. Proper naming conventions should also be used to indicate the versioning of libraries.

As a summary of how to perform a release:

Set up your HeliumDev client config to an instance of Helium and a DSL project with valid project directory.
Use the release command to publish the source code. Take note of the name you entered for the release as this will be needed to import the release as a library.

For more details and general instruction on how to make use of the HeliumDev client please consult the documentation located here.

Releases used for libraries need to have a web-app folder included even if it does not contain any source code.

Be sure to use proper naming conventions for releases representing libraries such as including the phrase "lib" and also including versioning for the library in the name.

Specifying Releases to Import

In order to specify which releases should be imported into a DSL project, the libraries to import should be listed, by name, in a newly introduced shared-lib.list file. This file should be located in the project root folder. The file may contain multiple lines with each representing a library to import:

shared-lib.list

helium-shared-lib-v1
generic-validation-lib-v1
generic-string-manipulation-lib-v1

Entries in shared-lib.list are text values that matches the name provided when the release was published using the release command of the Helium Dev client.

Importing Libraries Using the HeliumDev Client

Once the libraries to import has been specified they can be imported using the repo and fetch-libs commands in the HeliumDev client. The following HeliumDev client commands are relevant for shared libraries:

Command	Explanation
`repo`	Initiates a prompt to enter the Helium server name to be used as a repo. The repo should be set to a value representing a previously configured server.
`fetch-libs`	Download libraries as specified in `shared-lib.list` into the `shared-libs` directory in your local project workspace.
`purge-libs`	Delete libraries that were imported into the `shared-libs` directory using `fetch-libs`.

For the example shared-lib.list file as shown in the previous section using the fetch-libs command will result in an attempt by the HeliumDev client to download the contents of three helium releases into the current workspace. If any of the releases can't be found on the repo an error will be thrown on the fetch-libs command.

In summary, the following steps can be followed to import a library into your local workspace for an app:

Create an empty file called shared-lib.list in the root of the child project.
Use the repo command using the name of the target server in your local HeliumDev client config as the value. Note that the value set when using the repo command is not validated against available server names in your HeliumDev config. If an incorrect value is set here, an error will only be generated during step 4 as discussed below.
Update shared-lib.list to include the name of the release you wish to include as a library.
Use the fetch-libs command to download the source code of the specified libs. This step will fail if step 2 was note completed or if an incorrect server name was set for the repo.
(Optional) Use the purge-libs command at any time to remove all locally imported library files from disk.

Shared library

model/       services/    shared-libs/ sql-scripts/ utilities/   web-app/
./model:
	persistent_objects/
./model/persistent_objects:
	HeliumSharedLibUserRole.mez
./services:
	HeliumSharedLibInviteUsers.mez
./shared-libs:
./sql-scripts:
	helium-shared-lib-script.sql
./utilities:
	HeliumSharedLibUtil.mez
./web-app:
	images/     lang/       presenters/ static/     views/
./web-app/images:
	module-icon.png
./web-app/lang:
	add.input  en.lang
./web-app/presenters:
	HeliumSharedLibUnit.mez     HeliumSharedStaticUnit.mez
./web-app/static:
	shared_static.css   shared_static.html  shared_static.js
./web-app/views:
	HeliumSharedLibView.vxml     HeliumSharedStaticView.vxml

"Base Project" importing a shared library

# Notice that the shared-libs directory contains the contents of included shared libs.
./model/*.mez
./services/*.mez
./shared-lib.list
./shared-libs/helium-shared-lib-v1/model/persistent_objects/*.mez
./shared-libs/helium-shared-lib-v1/services/*.mez
./shared-libs/helium-shared-lib-v1/sql-scripts/*.sql
./shared-libs/helium-shared-lib-v1/utilities/*.mez
./shared-libs/helium-shared-lib-v1/web-app/images/*.png
./shared-libs/helium-shared-lib-v1/web-app/lang/*.lang
./shared-libs/helium-shared-lib-v1/web-app/presenters/*.mez
./shared-libs/helium-shared-lib-v1/web-app/presenters/*.mez
./shared-libs/helium-shared-lib-v1/web-app/static/*.css
./shared-libs/helium-shared-lib-v1/web-app/static/*.html
./shared-libs/helium-shared-lib-v1/web-app/static/*.js
./shared-libs/helium-shared-lib-v1/web-app/views/*.vxml
./shared-libs/helium-shared-lib-v1/web-app/views/*.vxml
./utilities/*.mez
./web-app/email-templates/*.html
./web-app/images/*.png
./web-app/lang/*.lang
./web-app/presenters/*.mez
./web-app/static/*.css
./web-app/static/*.html
./web-app/static/*.js
./web-app/views/*.vxml

Using an Imported Library

Once a library has been imported into the local directory it can be used as though it is a normal part of the app source code:

Using an imported library

// In this example exampleFunctionWithParam is a function that exists 
// in the unit HeliumSharedLibUtil found in a shared library.
HeliumSharedLibUtil:exampleFunctionWithParam("Hello World");

The example above only shows the usage of a method provided. Any source files or resource that can be specified in a DSL app can be provided through a shared library. This includes images, lang files, views presenters and models.

Naming Standards to Avoid Compiler Issues

When a project is imported as a library it is included as regular DSL source code, this means it needs to be able to compile alongside all existing source code in the project. Therefore one cannot import objects, persistent objects, views or presenters from a library if there also exists a resource declared with the same name. While images and lang entries can be overridden, objects, persistent objects, views and presenters cannot.

Consider the example:

If a project being used as a library declares a persistent object called Farmer, this library cannot be used inside a project that declares a persistent object called Farmer. The library can be imported with the fetch-libs command, but will fail to compile.

To use shared libraries successfully the developer must carefully decide on meaningful naming conventions to allow multiple projects to be integrated together seamlessly. As with the helium-shared-lib example above, units, objects and lang entry keys are prefixed to be unique:

Lang entry

heliumsharedlib.view.title.Helium_Shared_Lib=View in helium-shared-lib

Unit declaration

unit HeliumSharedLibUtil;

Source code

An example repo is zipped and attached to this article, you can also find the source on Bitbucket:

Table of Contents

Introduction

Releasing a Library

Importing Libraries Into a DSL App

Specifying Releases to Import

Importing Libraries Using the HeliumDev Client

Directory Structures Resulting From a Library Import

Using an Imported Library

Images

Lang Entries

Naming Standards to Avoid Compiler Issues

Source code

Browser not supported