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"