JavaScript Packaging using Humax

Introduction

In a typical web applications development, we all aware of the issues with managing client side scripts files. We do not face managebility issues in server-side development. Most of the server side frameworks follow physical, logical or both combination to address and identify an object or method. In .NET, we can logically group types under a namespaces and physically by assemblies. And in Java, packages help us to group and manage types.

Humax introduces packaging system in version 0.2.1. This is a mechanism which enables you to organize script files into different directories according to their functionality as well as category they should belong to.

Do not map Humax package with Java package. In Java, a package is the only way to group types by logically and physically. However, Humax Package is used to group script files only by physically.

Features

• Physically organizing JavaScript files based on functionality as well as category
• Versioning
• Unified Script Reference

A Humax package is not mean for:

• A package does not logically group one or more script files as well as the functions and classes defined on these files like Java Package. For this, Humax uses namespaces.
• Unlike .NET assemblies, a Humax package does not contains meta information other than version.
• An absolute package name (like "lib.coreApp.Page1") cannot group more than one script files. Instead script files under a same directory share partial package name for example packages "lib.coreApp.Page1" and "lib.coreApp.Page2" share "lib.coreApp".

Creating a Package

To create a package, you choose a name for the package, and call Humax.declarePackage at the top of every script file.

Discipline #6. It is strongly recommended to call Humax.declarePackage on top of the script file.

Example,

Humax.declarePackage("lib.sample");

The basic reason of using Package is to avoid naming confliction. Humax recommends to use script file name as the last part of the package name. For versioning, Humax suggests to specify version information in the filename itself. In this case do not give the version information in the last part of package name.

The remaining part of the package should directly map to directories in your web project. In the above example, "lib" should map to a directory.

Code Base

What is the origin of starting a package name?

Let us assume that you are developing a web based patient management system named "PMS" for a company Husmoh. For a sake of simplicity, you maintain two set of client side script files one is for core functionality and another one is for UI functionality. For this, you have two directories named "core" and "ui" under "script" directory. You create two script files under "core" named "validator.js" and "common.js". There are two script files named "newpatreg.js" and "prescribedrugs.js" for new patient registration and prescribe drugs respectively under "ui" directory. The following image shows the directory structure of this:

As we discussed, the last part of the package name for files under "core" should be "validator" and "common" respectively. The debate would be the first part of the package name. As explained before, it should refers the corresponding directory hierarchy of the script file. In this above case, the directory hierarchy for "validator" is "E:\pms_project\scripts\core". But we cannot start with system specific drive name and directories as part of package name. The reasonable entry point would be "scripts" directory. But Humax strictly do not recommend this. The reason is it affects file managebility. For example, you have implemented a client side library for XML parsing which has numerous files and you plan to release under a directory "MyXml". In this case, you can start your package name from "MyXml" and actual package name for a file in the "Core" directory could be "MyXml.Core.Parser". Based on this, Humax recommends to follow below structure for grouping script files and which provides a clear cut package name for your script files.

(Excluding code base directory)<Header Directory>.<Zero or more Sub Directory>.<script name excluding version>

Based on the above structure, we can give the package name for "validator.js" as core.validator. And "scripts" should be the codebase for this project. For "validator.js", "core" directory acts as a header directory and there is no sub-directories required.

The header directory should be the "company name" and its immediate child directory should be the name of the project for medium and large scale applications, for example, husmoh.pms.core.validator. The decision should be taken by designer of this project.

Code Base and Humax

Humax decides a directory as a code base:

• If the directory should be declared as "codebase" in the Humax.AppConfig.
• If there is no directory has been specified as "codebase" in the AppConfig, it searches directories and/or files under the path where Humax is placed.

In the above example, there is no need to specify "script" as code base, because it exists along with "humax.js". Suppose the "husmoh" root directory is located under some other directory which is not existed along with humax installed path. In this case, you should specify the code base of all scripts as

Humax.AppConfig.codeBase = "husmoh"

Referencing and Using a Package

Humax introduces require() method to allow the use of types declared in a package into current script file.

Humax.require(<package name>, [version]);

For example,

Humax.require("husmoh.pms.core.validator");

Discipline #7. From v0.2.1 onwards, a package a.k.a Humax compatible script file should be referenced by Humax.require().

Versioning Package

The intend of package is designed to simplify and resolve versioning problems that can occur using different versions of same script files.

Issues with Versioning

Suppose you have developed a library called "NiceWidgets.js" which requires a particular third party xml library. Assume that NiceWidgets version 1.0, reference a particular version of the xml library say "MyXmlLib v2.3.2.js". The clients of "NiceWidgets.js" use this in their applications with no issues. You release "NiceWidgets v2.0.js" which actually uses "MyXmlLib v2.6.js". In a situation like one of your client who is developing a web site using "NiceWidgets.js", and now they want to use one new client side control introduced in "NiceWidgets v2.0.js". They do not immetiately want to migrate into "NiceWidgets v2.0.js" due to some breaking changes introduced in version 2.0. For them, they have to use version 2.0 in one of their page. But your library should load correct version of "MyXmlLib" because in the client side, they may have both "MyXmlLib v2.3.2.js" and "MyXmlLib v2.6.js".

Specifying Version

For resolving these kind of versioning issues, Humax introduces versioning for packages. You can specify the version information in the Humax.declarePackage(),

Humax.declarePackage("Husmoh.NiceWidgets", "1.0");

Discipline #8. Humax recommends that the version information would be in <major>[.minor[.revision]] format.

Requesting Package Version

The second optional parameter of require() method allows you to specify which version of the package you require.

Humax.require("MyXmlLib", "2.3.2");

The above command requests to load version 2.3.2 of MyXmlLib.

Requesting Version by Expression

You can specify relational expression in the version argument to load a version in the given range, for example, your library requires MyXmlLib version greather than 2.3.2. Then you can specify

Humax.require("MyXmlLib", "v>2.3.2");

The expression should start with letter "v" and has any one of the relational operator <, <=, >, >= and =.

File Name Pattern for versioned Package

Different version of same package cannot share same file name which is one of the very basic standard across all operating system. Humax do not recommend to maintain different version of same package under different directory as followed in .NET global assemblies. Instead, if you plan to develop and adopt package version, Humax recommends the following decipline.

Discipline #9. The file name pattern of versioned package should be in the format <package name>_v<major>[.minor[.revision]].js.

Based on the decipline #9, the file name of package "MyXmlLib v2.3.2" should be "MyXmlLib_v2.3.2.js".

You can use "MyXmlLib.js" as file name for version 1.0 or 0.1 of the package which will be based on your implementation strategy.

Loading non-Humax standard script files

If you want to adopt non-Humax standard script files as Humax package with versioning feature, you can use packages option in Humax.AppConfig. For example,

Humax.AppConfig.packages = 
[
    {name:"Husmoh.NiceWidgets", version:"0.9.1", file:"NiceWidgets.js"},
    {name:"MyOtherXmlLib", version:"2.5.6", file:"myotherxmllib 2.5.6213.js"},
    {name:"SomeValidatorScript", version:"", file:"some_validator_script.js"} 
];

Humax automatically verifies the version details and load the relevant script file. For example, you have declared the packages in the AppConfig, and one of your script file requires MyOtherXmlLib package with version greater than 2.0, Humax loads "myotherxmllib 2.5.6213.js".

For more details or your contribution in Humax web framework, visit http://humax.sourceforge.net or
write me to udooz@hotmail.com.