EXPLAINERS Javascript Build Scripts

1. Introduction

The UIZE JavaScript Framework provides a system for developing build scripts that can be run by Windows Scripting Host, for automating build tasks.

This document describes the build script system, as well as the various build scripts that come bundled with the download of the UIZE JavaScript Framework.

1.1. What They Can Do For You

Build scripts are a powerful means for automating the otherwise tedious processes that are part of the building of a Web site project.

Among other things, build scripts let you...

automatically scrunch down all JavaScript files inside a Web site project into smaller, obfuscated files using the UIZE JavaScript Framework's Scruncher
automatically find all JavaScript library (.library.js) files inside a Web site project and build a version of the file for production/deployment that combines all the JavaScript modules referenced in the library file
automatically build JavaScript template modules from all JavaScript template module source (.js.jst) files contained inside the JavaScript modules folder
audit all the string literals in all the JavaScript files throughout a Web site project, to aid in internationalizing your JavaScript code
automatically build documentation from comments contained inside your JavaScript modules
automatically build all Wikitext-like Simple Doc (.simple) documents into attractive HTML documentation files
automatically build all Simple Data (.simpledata) data files into HTML files using JavaScript template (.jst) files
and much more...

1.2. Where You Will Find Them

The build scripts are located at the root of the UIZE JavaScript Framework Web site (ie. in the UIZE-JavaScript-Framework folder).

The build script files are JavaScript files (with the .js extension) with names that all start with a "_" (underscore) character, as in...

_build-jst-modules.js (Build JST Modules)
_build-pages-from-simple-data.js (Build Pages from Simple Data)
_build-pages-from-simple-doc.js (Build Pages from Simple Doc)
_build-scrunched.js (Build Scrunched)
_build-strings-audit-report.js (Build Strings Audit Report)
_run-unit-tests-scrunched.js (Run Unit Tests (Scrunched))
_run-unit-tests-source.js (Run Unit Tests (Source))
_uize-site-build-pages-from-source-code.js (UIZE Site Build Pages from Source Code)

Not all the build scripts will necessarily be useful for your own Web site project. In particular, the Build Pages from Simple Doc and UIZE Site Build Pages from Source Code build scripts are intended primarily for the uize.com Web site, although you are welcome to hack them to meet your needs or use them as a reference when Writing Your Own Build Scripts.

1.3. Where They Should Go

To use the build scripts in your own Web site project, you should copy them from the UIZE-JavaScript-Framework root folder into the root folder of your project.

1.3.1. Must Have the Build Script Setup

Be sure to copy the _build-script-setup.js file along with the desired build scripts (for more info, see the section Build Script Setup).

1.3.2. Must Have the Build Environment Variables

Be sure to copy the _build-env.json file along with the desired build scripts (for more info, see the section Build Environment Variables).

1.3.3. Must Have the UIZE Modules

Note that the build scripts make use of modules of the UIZE JavaScript Framework, so your Web site project must be set up with a folder containing these JavaScript modules before you can use the build scripts.

Also note that the moduleFolderPath build environment variable that is defined in the _build-env.json file (see the section Build Environment Variables) should be correctly set so that the UIZE JavaScript modules can be located by the module loader that is defined inside the Build Script Setup file.

1.4. How You Can Run Them

Once you have copied the build scripts to the root folder of your Web site project, and once you have configured the Build Environment Variables appropriately, then the build scripts can be run by simply double-clicking on the script files, or by selecting them in Windows Explorer and pressing the Enter key.

1.4.1. Windows Script Host

The build scripts are JavaScript files intended to be run using Microsoft's Windows Script Host technology that is built into Windows systems.

This means that no extra software needs to be installed on a Windows machine in order to use the build scripts. It does, however, mean that you need to run them on a Windows machine. Hopefully, even the most staunch Mac or Linux developer will be able to find a sad and dejected Windows machine lying in a dusty corner of their office somewhere. It doesn't take a very powerful machine to run the scripts. Failing finding a Windows machine that can be connected to the network to access the Web site project's root folder, Virtual PC (or some other comparable virtualization software) can be used in order to run an instance of Windows on a non-Windows machine.

WSH AND ANTI-VIRUS SOFTWARE

Depending on the configuration of the Windows machine you use, there may be anti-virus software installed that may be a bit overzealous in preventing any scripts from running using WSH. You may be prompted by such software to agree to let the script be run. Depending on the anti-virus software, you may be given the option to grant permission for a given build script for all future execution, without having to be prompted each time. If such permission is granted, such software will likely prompt again in future if the script's contents is modified (a hash of the contents may be stored by the software for the sake of detecting modifications).

1.4.2. Built for Speed

The build scripts are quite fast to run and will recurse through the folders of a Web site project in good time.

Also, most of the build scripts are coded to only rebuild files if the source file was updated since the previous build (ie. the modification date of the source file is later than that of the built file). This makes it quite manageable to run the build scripts repeatedly between incremental updates to a single file. In cases where you want to force the scripts to rebuild all the files they would normally build, you can set alwaysBuild to true (see the section Build Environment Variables).

TIP

To improve the speed of the build scripts even further, be sure to use the doNotEnter build environment variable to prevent the scripts from entering folders that are known to contain nothing to build (but, more on that later).

1.5. Build Script Log Files

In order to keep you from being left completely in the dark as to what a build script does, the files that are processed by a build script are conveniently listed in one or more log files.

1.5.1. Most Build Scripts Have At Least One Log File

Most (but not all) build scripts will output at least one log file once they have completed execution.

Some build scripts may generate multiple log files. For example, the Build Scrunched build script generates one log file that lists the JavaScript files that were scrunched, and another log file listing the JavaScript library (.library.js) files that were built. There are also some build scripts that don't output any log files at all.

1.5.2. Log File Naming

For many build scripts, the name of the script's associated log file is simply the name of the build script with the .js file extension replaced by a .log extension.

In the case of build scripts that generate multiple log files, the log files will typically be named with the build script name (sans .js extension) as a prefix, and then some identifying suffix to distinguish the different log files in the group from one another. For example, the _build-scrunched.js (Build Scrunched) build script generates the two log files named _build-scrunched-js-files.log and _build-scrunched-libraries.log.

OVERWRITE BEHAVIOR

Every time a build script is run, the previous copies of its associated log files are overwritten. If you care about them (why would you?), you should make copies before running the script.

1.5.3. Summary Info

Some build scripts simply list the files that were built, while others may also list summary information for the build operation for each file along with the file listing.

1.5.3.1. Basic Log Summaries

Some build scripts simply list the files that were built, with basic information about the source file path, the target (generated / built) file path, a reason why the file was built (eg. DIDN'T EXIST, WAS OUT OF DATE, ALWAYS BUILD), and the duration for the build process.

The snippet below shows some of the log file generated from running the Build JST Modules build script...

LOG FILE SNIPPET

***** C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Templates.Calendar.js.jst
  TARGET FILE: C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Templates.Calendar.js
  BUILT (WAS OUT OF DATE), BUILD DURATION: 16ms

***** C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Templates.Collection.js.jst
  TARGET FILE: C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Templates.Collection.js
  BUILT (DIDN'T EXIST), BUILD DURATION: 0ms

C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Templates.CollectionItem.js.jst
  TARGET FILE: C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Templates.CollectionItem.js
  no action, file is current

***** C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Templates.HashTable.js.jst
  TARGET FILE: C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Templates.HashTable.js
  BUILT (WAS OUT OF DATE), BUILD DURATION: 15ms

NOTES

For files that were built, the source URL is prefixed with a series of asterisks to make these entries stand out from the rest of the log file's contents. This makes it easier to scan the file with your eyes for build actions.
The summary info for each file that was built is indented under the source file path. For developers using text editors that support indent-based "folding", this makes it easy to collapse the log file down to just a list of source file paths, and then progressively expand folds to dig deeper into the summary info.

1.5.3.2. Detailed Log Summaries

Some build scripts provide additional summary info for files that were built, that appears right below the basic summary info.

For example, the Build Scrunched build script provides a Scruncher report for every JavaScript file that was scrunched. The snippet below shows some of the log file generated from running this build script...

LOG FILE SNIPPET

***** C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Color.js
  TARGET FILE: C:\~uize\UIZE-JavaScript-Framework\js\Uize.Color.js
  BUILT (DIDN'T EXIST), BUILD DURATION: 156ms
    Unique Identifiers Scrunched: 46
    Incidences of Identifiers Scrunched: 193
    Savings From Scrunched Identifiers: 1518
    Savings From Removed Whitespace: 906
    Total Comments Removed: 18
    Savings From Removed Comments: 8185
    Savings From Removed Linebreaks: 329
    Supposed Total Savings: 10938
    Real Total Savings: 10938

    FINAL SIZE: 1777

***** C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Comm.Ajax.js
  TARGET FILE: C:\~uize\UIZE-JavaScript-Framework\js\Uize.Comm.Ajax.js
  BUILT (WAS OUT OF DATE), BUILD DURATION: 47ms
    Unique Identifiers Scrunched: 15
    Incidences of Identifiers Scrunched: 83
    Savings From Scrunched Identifiers: 660
    Savings From Removed Whitespace: 493
    Total Comments Removed: 5
    Savings From Removed Comments: 1079
    Savings From Removed Linebreaks: 169
    Supposed Total Savings: 2401
    Real Total Savings: 2401

    FINAL SIZE: 1269

C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Comm.Iframe.js
  TARGET FILE: C:\~uize\UIZE-JavaScript-Framework\js\Uize.Comm.Iframe.js
  no action, file is current

2. The Build Scripts

The UIZE JavaScript Framework download comes bundled with a score of convenient, ready-to-go build scripts that will immediately be useful to your project built on top of the UIZE JavaScript Framework.

2.1. Build JST Modules

The Build JST Modules build script (implemented in the file _build-jst-modules.js) generates JavaScript template modules from all the JavaScript template (.js.jst) files that it finds in the modules folder.

The folder that contains the UIZE JavaScript modules (as well as your own JavaScript modules built on top of the UIZE JavaScript Framework), and that is pointed to by the moduleFolderPath build environment variable, may contain JavaScript templates that are to be compiled to JavaScript template modules. Once compiled to regular JavaScript modules, they can then be used and required by other JavaScript modules - just like any module.

The Build JST Modules build script provides a convenient way to automate the compilation of JavaScript template modules. If you look through the UIZE-JavaScript-Framework/js/~source folder in the download of the UIZE JavaScript Framework, you will notice a number of .js.jst files under the UizeSite.Templates namespace. Many of these JST modules are HTML generators for widgets. Others are used by build scripts, such as, for example, the UizeSite.Templates.IndexPage.js.jst JavaScript template, which is used by the build scripts that build the various index pages for the UIZE Web site.

The files generated by this script are JavaScript modules that can then be scrunched - along with all other JavaScript modules - by the Build Scrunched build script. For this reason, after making a change to any JavaScript template (.js.jst) files, one should first run the Build JST Modules build script before running the Build Scrunched build script, or otherwise your scrunched JavaScript template modules will not be up-to-date.

For more information on JavaScript template modules, consult the explainers JavaScript Templates and JavaScript Modules.

NOTES

the core of the intelligence of the Build JST Modules build script can be found in the Uize.Build.CompileJstModules module

2.2. Build Pages from Simple Data

The Build Pages from Simple Data build script (implemented in the file _build-pages-from-simple-data.js) recurses through all folders of a Web site project, building pages from all the Simple Data (.simpledata) files that it finds.

Simple Data is a data file format that is even more human readable than XML (how could this even be possible!?!?) and that uses indentation to indicate structure (so, kind of like Python, but for data). This build script finds all these files and builds pages from them, by processing the data in each file using an accompanying JavaScript Template (.jst) file.

2.2.1. File Naming Scheme

The filename for the JST file and the target (ie. built) file are determined by a simple file naming scheme that associates the two files with the Simple Data source file.

According to this scheme, the filename for the JST file is the filename of the Simple Data file with the .simpledata file extension replaced with the .jst extension, and the filename of the built file is the filename of the Simple Data file with the .simpledata file extension stripped off. Consider the following example...

FILE NAMING EXAMPLE

       built file > credits.html
JST template file > credits.html.jst
 Simple Data file > credits.html.simpledata

In the above example, the file credits.html.simpledata is the source Simple Data file, the file credits.html.jst is the JavaScript template that should be used for processing the data in the Simple Data file, and the file credits.html is the built file that contains the output of the template processing operation.

Based on this file naming principle, the desired file extension for the built file is put before the .simpledata and .jst extensions. This means that the Build Pages from Simple Data build script can build any type of text file from Simple Data files it encounters, and, in fact, the UIZE Web site project uses it to build a few HTML pages as well as an RSS (.rss) file.

NOTES

the core of the intelligence of the Build Pages from Simple Data build script can be found in the Uize.Build.BuildSimpleDataPages module
the behavior of this build script is not affected by the values of the buildFolderPath and sourceFolderName build environment variables
the summary info for this build script is output to the log file _build-pages-from-simple-data.log

2.3. Build Pages from Simple Doc

The Build Pages from Simple Doc build script (implemented in the file _build-pages-from-simple-doc.js) recurses through all folders of a Web site project, building pages from all the Simple Doc (.simple) files that it finds, as well as building HTML reference documentation pages from all JavaScript modules that it finds in the modules folder.

2.3.1. Phases

This build script is made up of two phases...

2.3.1.1. PHASE 1: Build Pages From Simple Doc (.simple) Files

An HTML page is generated for each Simple Doc (.simple) file.

The build script recurses through all the folders, finding Simple Doc (.simple) files. For each file, it builds an HTML page from the Simple Doc document, using the ~SIMPLE-DOC-TEMPLATE.html.jst template file that is contained inside the same folder as the Simple Doc file. The built HTML page is then output to the same folder as the Simple Doc file, where the filename of the built file is the filename of the Simple Doc file with the .simple file extension replaced with the .html extension.

FILE NAMING EXAMPLE

javascript-build-scripts.simple --> PRODUCES --> javascript-build-scripts.html

The summary info for this phase of the build script is output to the log file _build-pages-from-simple-doc.log.

2.3.1.2. PHASE 2: Build Pages From Simple Doc in JavaScript Modules

An HTML reference documentation page is generated for each JavaScript module contained inside the modules folder.

The build script iterates through all the JavaScript modules contained inside the modules folder (as specified by the moduleFolderPath build environment variable). For each file, it extracts all the Simple Doc comments, stitches all those comments together into a single Simple Doc document, and then builds an HTML page from that document, using the ~SIMPLE-DOC-TEMPLATE.html.jst template file that is contained inside the reference/ folder of the UIZE Web site project. The built HTML reference documentation page is then output to the reference/ folder, where the filename of the built file is the filename of the JavaScript module with the .js file extension replaced with the .html extension.

FILE NAMING EXAMPLE

js/~source/Uize.Widget.js --> PRODUCES --> reference/Uize.Widget.html

The summary info for this phase of the build script is output to the log file _build-pages-from-simple-doc-in-js-modules.log.

For more information on Simple Doc - such as its rules on document structure, inline formatting, etc. - refer to the explainer JavaScript Documentation System.

NOTES

the behavior of this build script is not affected by the values of the buildFolderPath and sourceFolderName build environment variables

2.4. UIZE Site Build Pages from Source Code

The UIZE Site Build Pages from Source Code build script (implemented in the file _uize-site-build-pages-from-source-code.js) is intended primarily for the UIZE Web site, and builds HTML pages for viewing the source code of JavaScript modules and examples pages.

2.4.1. JavaScript Module Source Code Pages

A source code page is generated for every JavaScript module in the modules folder.

The build script iterates through all the JavaScript modules contained inside the modules folder (as specified by the moduleFolderPath build environment variable), builds a source code page for each module using the JavaScript template ~SOURCE-CODE-TEMPLATE.html contained inside the reference/source-code folder and places the built source code page inside that folder, where the source code page's filename is the name of the module with the file extension .html appended (eg. Uize.Widget.html for the Uize.Widget module).

2.4.2. Example Source Code Pages

A source code page is generated for every example page contained inside the examples folder.

The build script iterates through all the example pages contained inside the examples folder, ignoring experimental examples prefixed with a "~" (tilde) character, builds a source code page for each example using the JavaScript template ~SOURCE-CODE-TEMPLATE.html contained inside the examples/source-code folder and places the built source code page inside that folder, where the source code page's filename is the same as the example page's filename.

NOTES

the summary info for this build script is output to the log file _uize-site-build-pages-from-source-code.log

2.5. Build Scrunched

The Build Scrunched build script (implemented in the file _build-scrunched.js) recurses through all folders of a Web site project, automatically scrunching down all JavaScript files into smaller, obfuscated files using the UIZE JavaScript Framework's Scruncher.

The Build Scrunched build script provides a convenient way to obfuscate and reduce the size of all the JavaScript files in your Web site project, not just those written explicitly to use the UIZE JavaScript Framework. The scrunched versions of JavaScript files are output to a location that is determined by the two related buildFolderPath and sourceFolderName build environment variables.

2.5.1. Phases

This build script is made up of two phases...

2.5.1.1. PHASE 1: Build Scrunched JavaScript Files

The build script recurses through all the folders, finding JavaScript files and building scrunched versions of them which are then saved to a target location.

The summary info for this phase of the build script is output to the log file _build-scrunched-js-files.log.

2.5.1.2. PHASE 2: Build Scrunched Library (.library.js) Files

The build script recurses through all the folders, finding JavaScript library (.library.js) files and building scrunched versions that combine the scrunched versions of all the JavaScript modules referenced in the library file.

The summary info for this phase of the build script is output to the log file _build-scrunched-libraries.log.

2.5.2. Source Not Overwritten

JavaScript files that are scrunched are NOT overwritten by their scrunched versions.

Among other things, this means that JavaScript files that are not well suited to scrunching (perhaps they're missing semi-colons at the end of statements) are still available in their unscrunched form and can be accessed just as they always were. At any stage, there may be some JavaScript files that are not accessed in their scrunched form when a site is live - this is entirely up to you. Leaving the source unmolested also means that you can switch back and forth between using the scrunched and unscrunched code in order to troubleshoot problems.

2.5.3. Head Comments

document...

NOTES

the core of the intelligence of the Build Scrunched build script can be found in the Uize.Build.AutoScruncher module

2.6. Build Strings Audit Report

The Build Strings Audit Report build script (implemented in the file _build-strings-audit-report.js) recurses through all folders of a Web site project, harvests all the string literals from JavaScript files, filters them into different buckets depending on their likelihood of internationalizability, and produces a report with summaries for all the JavaScript files.

The Build Strings Audit Report build script groups the literal strings it finds inside a JavaScript file into four buckets...

2.6.1. NON-INTERNATIONALIZABLE STRINGS

This category includes strings that are recognized by certain patterns as being non-internationalizable strings, including: DOM event names (eg. click), very JavaScript specific keywords (eg. function), HTML specific attribute names (eg. href), sufficiently distinctive HTML tag names (eg. div), file extensions (eg. .gif), strings that are only whitespace, strings that have no letter characters, hex formatted RGB color values (eg. #ff0000), module names (eg. Uize.Widget.Bar), any string starting with "Uize", underscore delimited identifiers (eg. button_big_disabled), Changed.[propertyName] events (eg. Changed.value), the Changed.* event, sufficiently distinguishable URL paths (eg. myfolder/mysubfolder/myfile.html), camelCase identifiers (eg. languageSortAscending).

2.6.2. LIKELY NON-INTERNATIONALIZABLE STRINGS

This category includes strings with only one letter character (eg. a), and strings that look like short url snippets (eg. myfolder/mysubfolder).

2.6.3. POSSIBLY INTERNATIONALIZABLE STRINGS

This category includes strings that are not filtered out into either the NON-INTERNATIONALIZABLE STRINGS, LIKELY NON-INTERNATIONALIZABLE STRINGS, or LIKELY INTERNATIONALIZABLE STRINGS categories.

2.6.4. LIKELY INTERNATIONALIZABLE STRINGS

This category includes strings that are not filtered out into either the NON-INTERNATIONALIZABLE STRINGS or LIKELY NON-INTERNATIONALIZABLE STRINGS categories and that contain three adjacent, space separated words, where the middle word is all lowecase.

Below is a snippet from the log file after the Build Strings Audit Report build script was run inside the UIZE-JavaScript-Framework folder of the UIZE Web site project...

LOG FILE SNIPPET

***** C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Widget.TableSort.js
  TARGET FILE: C:\~uize\UIZE-JavaScript-Framework\js\~source\Uize.Widget.TableSort.js
  BUILT (ALWAYS BUILD), BUILD DURATION: 188ms
    NON-INTERNATIONALIZABLE STRINGS
       --- 92,101,189
      TD --- 54
      TR --- 142,249,274
      Uize.Node --- 22
      Uize.Widget.TableSort --- 21
      headingLitClass --- 346
      headingOverClass --- 342
      languageSortAscending --- 350
      languageSortDescending --- 355
      click --- 292
      rowOverClass --- 360
      updateUi --- 339

    LIKELY NON-INTERNATIONALIZABLE STRINGS

    POSSIBLY INTERNATIONALIZABLE STRINGS
      TH --- 55
      tbody --- 50
      thead --- 272

    LIKELY INTERNATIONALIZABLE STRINGS
      Click to sort in ascending order --- 352
      Click to sort in descending order --- 357

A few things to notice about the format...

the strings are listed in ASCIIbetically sorted order
to the right of each string is a listing of all the line numbers on which the string occurs

THIS ONE'S SLOW

Be warned: this build script can be quite slow to run, especially if you have a large project with many folders and many JavaScript files. It could take a few minutes to process all JavaScript files in a large project. You'll know when it's done running by the modified date of the associated log file, or you can watch the WSCRIPT.EXE process in the Windows Task Manager.

NOTES

the core of the intelligence of the Build Strings Audit Report build script can be found in the Uize.Build.AuditStrings module
the summary info for this build script is output to the log file _build-strings-audit-report.log

2.7. Run Unit Tests (Scrunched)

The Run Unit Tests (Scrunched) build script (implemented in the file _run-unit-tests-scrunched.js) runs the unit test suite for the UIZE JavaScript Framework, using the scrunched versions of the JavaScript modules.

2.8. Run Unit Tests (Source)

The Run Unit Tests (Source) build script (implemented in the file _run-unit-tests-source.js) runs the unit test suite for the UIZE JavaScript Framework, using the source versions of the JavaScript modules.

3. Build Script Setup

The Build Script Setup (implemented in the file _build-script-setup.js) implements a module loader, specific to Windows Script Host, that is used by The Build Scripts that come bundled with the UIZE JavaScript Framework, and that can also be used when Writing Your Own Build Scripts.

3.1. Using the Build Script Setup

The Build Script Setup is used in a build script by adding a few lines of "boilerplate" JavaScript code.

This "boilerplate" JavaScript code is the minimum amount of code necessary in every build script in order to bootstrap the process, as shown in the following example...

EXAMPLE

/*** boilerplate setup code for WSH build scripts ***/
  var _setupFile = new ActiveXObject ('Scripting.FileSystemObject').OpenTextFile (
    '_build-script-setup.js',1
  );
  eval (_setupFile.ReadAll ()) ();
  _setupFile.Close ();

/*** your build script code follows ***/
  // ... ... ...
  // ... ... ...
  // ... ... ...

In the boilerplate block, the statement eval (_setupFile.ReadAll ()) (); reads the contents of the _build-script-setup.js file, evaluates its code using the JavaScript eval function, and then calls the function that is returned by the eval call (the _build-script-setup.js file actually defines a function that returns a reference to the actual setup function). In this case, we are not passing any parameters to the setup function. This is the typical usage for build scripts that reside in the root folder of a Web site project (ie. the same folder as the _build-script-setup.js file) and that are to run using the source versions of the JavaScript modules. Optional parameters for the setup function allow the module loader to be configured for Loading Scrunched Versions of Modules and for Running Scripts Outside a Project's Root Folder

3.1.1. Loading Scrunched Versions of Modules

The module loader defined in the _build-script-setup.js file can be configured to load the scrunched versions of JavaScript modules.

This is done by specifying the value false for the optional useSource property of the optional params object that is passed when calling the setup function. Consider the following example...

EXAMPLE

/*** boilerplate setup code for WSH build scripts ***/
  var _setupFile = new ActiveXObject ('Scripting.FileSystemObject').OpenTextFile (
    '_build-script-setup.js',1
  );
  eval (_setupFile.ReadAll ()) ({useSource:false});
  _setupFile.Close ();

Uize.module ({
  required:'Uize.Build.Util',
  builder:function () {Uize.Build.Util.testAllModules ()}
});

In the boilerplate block, the statement eval (_setupFile.ReadAll ()) ({useSource:false}); calls the setup function, passing a params object with the value false specified for the useSource property. When no params object is specified, or when the useSource property is omitted from the params object, then this property is defaulted to true. Explicitly specifying the value false causes the module loader defined inside the _build-script-setup.js file to load the scrunched versions of the JavaScript modules.

3.1.2. Running Scripts Outside a Project's Root Folder

The module loader defined in the _build-script-setup.js file can be configured for scripts that are to be run in a folder other than the root folder of a Web site project.

This is done by specifying a string value for the optional pathToRoot property of the optional params object that is passed when calling the setup function. Consider the following example...

EXAMPLE

/*** boilerplate setup code for WSH build scripts ***/
  var _setupFile = new ActiveXObject ('Scripting.FileSystemObject').OpenTextFile (
    '_build-script-setup.js',1
  );
  eval (_setupFile.ReadAll ()) ({pathToRoot:'UIZE-JavaScript-Framework\\'});
  _setupFile.Close ();

Uize.module ({
  required:'Uize.Build.Util',
  builder:function () {Uize.Build.Util.testAllModules ()}
});

In the boilerplate block, the statement eval (_setupFile.ReadAll ()) ({pathToRoot:'UIZE-JavaScript-Framework\\'}); calls the setup function, passing a params object with the value 'UIZE-JavaScript-Framework\\' specified for the pathToRoot property. When no params object is specified, or when the pathToRoot property is omitted from the params object, then this property is defaulted to '' (empty string). In this example, explicitly specifying the value 'UIZE-JavaScript-Framework\\' causes the module loader defined inside the _build-script-setup.js file to prepend the path "UIZE-JavaScript-Framework\" to the path for every module that it loads. Assuming that the folder "UIZE-JavaScript-Framework" contains the UIZE JavaScript Framework, then the above configuration of the Build Script Setup would be appropriate for a script that resides in, and is to be run from, a parent folder of the "UIZE-JavaScript-Framework" folder.

4. Build Environment Variables

You may have to configure the build scripts to work in your Web site project's environment by modifying the build environment variables.

The build environment variables are set inside the _build-env.json file that sits alongside the build scripts at the root of your Web site project. This file contains an anonymous object formatted using JSON syntax, with properties for the various supported build environment variables, as shown in the example below...

EXAMPLE

{
  alwaysBuild:false,
  moduleFolderPath:'js\\~source',
  sourceFolderName:'~source',
  doNotEnter:/\\(css|images|OLD|photos|source-code|Uize.*)$/
}

The following build environment variables are supported by the build scripts...

4.1. alwaysBuild

A boolean, specifying whether the files that would be built by the build scripts should always be built, or if they should only be built if the source file has been modified since the last build.

Most of the build scripts are coded to only rebuild files if the source file was updated since the previous build (ie. the modification date of the source file is later than that of the built file). In cases where you want to force the scripts to rebuild all the files they would normally build, you can set alwaysBuild to true.

For some scripts, such as the Build Strings Audit Report script, the alwaysBuild build environment variable has no meaning. Also, the library builder portion of the Build Scrunched script always builds all library (.library.js) files, regardless of the modified dates of the source file or the modified dates of the various JavaScript modules listed in the library file.

4.2. buildFolderPath

A string, specifying the path - relative to the folder containing the build scripts - to a folder into which built files should be placed.

When a value is specified for this optional build environment variable, built files will be populated into the specified build folder in a folder hierarchy that mirrors the folder hierarchy of the Web site project. For example, if the build scripts are in a folder myproject, and if the value bld is specified for the buildFolderPath variable, and if the JavaScript file myproject/javascript/MyCompanySite.Page.js is then scrunched by the Build Scrunched build script, then the scrunched version will be located at myproject/bld/javascript/MyCompanySite.Page.js.

New folders are created inside the build folder as needed in order to house the built files. After the build scripts have run, the folder hierarchy inside the build folder will only match the folder hierarchy of the Web site project if at least one file was built from every folder of the Web site project, since folders are only created as needed for the built files. Of course, the build folder won't contain itself, since the build scripts don't consider the files inside the build folder as source material for building files (which is a good thing).

For an explanation of how this variable relates to the sourceFolderName build environment variable, consult the section buildFolderPath vs sourceFolderName.

NOTES

if a value is specified for the related sourceFolderName build environment variable, then the buildFolderPath variable has no effect

4.3. doNotEnter

An array or regular expression, specifying folders that should not be entered by the build scripts.

For example, the regular expression value /\\(css|images)$/ would prevent the build scripts from entering folders named css or images, and would be equivalent to the array value ['css','images']. The benefit of a regular expression is that you can write matching rules to catch a host of different folders that you may wish the build scripts to avoid. As an example, the regular expression /\\\.[^\\]*$/ would prevent the build scripts from entering folders that are prefixed with a "." (period character), which may indicate private or hidden system folders (eg. the Subversion source control system adds .svn folders to your project).

When a build script encounters a folder that the doNotEnter build environment variable indicates should not be entered, then the build script will not consider the files in that folder and will also not recurse deeper into the folder's subfolders. Such "do not enter" folders are, therefore, effectively dead ends. In addition to folders specified by the doNotEnter variable, the build scripts will also not enter any folder specified by the buildFolderPath build environment variable, so the build folder is implicitly a "do not enter" folder.

4.4. dryRun

A boolean, specifying whether or not the build scripts should save built files.

By default, the build scripts will save the built files to the location determined by the values of the buildFolderPath and sourceFolderName build environment variables. In cases where you just want to see what build actions are taken by a particular build script without having any files be modified, you can set dryRun to true.

When a build script is doing a dry run, it will still build the files and do everything that it normally would, except that it won't write the built files to the target location. A summary of all that would be done is output to a build script's associated log file(s), just as would be the case if you weren't doing a dry run. So, for example, in the case of running the Build Scrunched build script, the log files would contain all the Scruncher report information and the listings of all the library files that would be built. Doing a dry run and viewing the log files might be a good way to check that the target file paths are correct before doing a genuine build that would write files to the system.

4.5. moduleFolderPath

A string, specifying the path to the folder in your Web site project within which the unscrunched / source UIZE JavaScript modules are located.

The build scripts make use of modules of the UIZE JavaScript Framework. Also, some build scripts actually build files from the JavaScript module (.js) files and JavaScript template (.js.jst) files inside the modules folder. In order for the build scripts to know where to load these files from, the moduleFolderPath build environment variable should be modified, if necessary, to correctly point to the location of the JavaScript modules folder.

4.6. scrunchedHeadComments

document...

4.7. sourceFolderName

A string, specifying the folder name for folders that contain source (ie. unscrunched) JavaScript files.

When a value is specified for this optional build environment variable, scrunched JavaScript files will be populated into the parent folder of the folder containing the source JavaScript files, and the name of the source folder must match the value of the sourceFolderName variable. For example, if the value of this variable is '~source', then the JavaScript file with the path js/~source/Uize.Color.js will be scrunched because it is inside a folder named ~source, and the scrunched file will be placed in the parent folder and have the path js/Uize.Color.js.

For an explanation of how this variable relates to the buildFolderPath build environment variable, consult the section buildFolderPath vs sourceFolderName.

NOTES

if a value is specified for this variable, then the buildFolderPath build environment variable has no effect

4.8. buildFolderPath vs sourceFolderName

For certain build scripts - such as the Build Scrunched and Build Strings Audit Report build scripts - the location for unscrunched and scrunched JavaScript files needs to be known.

You can take one of two approaches in your Web site project...

4.8.1. The buildFolderPath Approach

You can locate your source JavaScript throughout the folder structure of your site and then have the scrunched JavaScript be output to a separate build folder that contains a mirror of your site's folder hierarchy.

This is the buildFolderPath approach, and with this approach you would have a folder structure something like...

js/Uize.Color.js
js/Uize.Comm.Ajax.js             <-- source files
js/Uize.Comm.Iframe.js
js/Uize.Comm.Iframe.Upload.js
... ... ...
bld/js/Uize.Color.js
bld/js/Uize.Comm.Ajax.js         <-- scrunched files
bld/js/Uize.Comm.Iframe.js
bld/js/Uize.Comm.Iframe.Upload.js
... ... ...

Here, buildFolderPath is set to 'bld', while sourceFolderName is set to '' (an empty string).

4.8.2. The sourceFolderName Approach

You can locate your source JavaScript throughout the folder structure of your site in a specially named folder, where the scrunched version of JavaScript files in such folders are output to the parent folder.

This is the sourceFolderName approach, and with this approach you would have a folder structure something like...

js/~source/Uize.Color.js
js/~source/Uize.Comm.Ajax.js     <-- source files
js/~source/Uize.Comm.Iframe.js
js/~source/Uize.Comm.Iframe.Upload.js
... ... ...
js/Uize.Color.js
js/Uize.Comm.Ajax.js             <-- scrunched files
js/Uize.Comm.Iframe.js
js/Uize.Comm.Iframe.Upload.js
... ... ...

Here, sourceFolderName is set to '~source', while buildFolderPath is set to '' (an empty string).

5. Writing Your Own Build Scripts

There's no saying that you need to be limited to the collection of convenient build scripts that are included with the UIZE JavaScript Framework download.

5.1. Adapting the Existing Build Scripts

Any build script provided as part of the UIZE JavaScript Framework download that is useful to your Web sites or projects can be adapted to suit your needs.

Not all of the provided build scripts will necessarily be useful to you, of course, since some of them are intended primarily for the UIZE Web site. But, if a build script is potentially useful but not perfectly suited to the folder structure of your own projects, just change it. And some of the build scripts are already configurable with Build Environment Variables.

5.2. Roll Your Own

If you can't adapt an existing build script to meet your needs, or hack it to meet slightly different needs, then you may just want to create your own specialized build script from scratch.

More creative applications of build scripts include things such as using a data set to drive the generation of hundreds (or thousands, even) of static files, such as HTML pages or XML files. The tomkidding.com Web site uses a build script, for example, to generate hundreds of HTML pages for paintings, drawings, sketches, graphic art, photography, photomontages, etc. from an artworks database. A benefit of building static HTML files is that there is no dependency on a server side database technology, and there are performance benefits that improve scalability under traffic load, since Web servers are well optimized to deliver static HTML pages to the client, and caching systems throughout the Internet are more likely to persist the static pages.

5.3. The Uize.Wsh Namespace

The various build scripts bundled with the UIZE JavaScript Framework all make use of the Uize.Wsh module.

The Uize.Wsh module provides facilities for accessing files, building files by recursing a folder hierarchy, automatically generating log files, and more. Additionally, a number of the build scripts use other modules under the Uize.Wsh namespace.

5.4. Structure of a Build Script

Build scripts are made up of two key sections: the Build Script Setup Boilerplate, and the Build Script Anonymous Module Declaration.

These two sections are highlighted using comments in the sample build script shown below...

EXAMPLE

/*** Build Script Setup Boilerplate ***/
  var _setupFile = new ActiveXObject ('Scripting.FileSystemObject').OpenTextFile (
    '_build-script-setup.js',1
  );
  eval (_setupFile.ReadAll ()) ();
  _setupFile.Close ();

/*** Build Script Anonymous Module Declaration ***/
  Uize.module ({
    required:[
      'Uize.Wsh'
      // add other modules that your build script requires, in a comma-separated list
    ],
    builder:function () {
      // build script code goes here
      // build script code goes here
      // build script code goes here
    }
  });

5.4.1. Build Script Setup Boilerplate

The Build Script Setup boilerplate is a small block of code that is necessary in every build script in order to bootstrap the process.

This little block of code evals the JavaScript contained inside the _build-script-setup.js file, which defines a module loader that works in the Windows Script Host context. For a more detailed discussion, consult the section Build Script Setup.

5.4.2. Build Script Anonymous Module Declaration

The build script anonymous module declaration is a declaration of the module of code that performs the build script's action.

5.4.2.1. Required Modules

Your build script's anonymous module can require any of the WSH-compatible UIZE Modules, which includes many modules of the UIZE JavaScript Framework, and even your own modules (provided they are WSH-compatible and reside in the modules folder).

Typically, your build script's code will at least require the Uize.Wsh module, but many build scripts may also require additional modules under the Uize.Wsh namespace (such as the Uize.Build.Util module), or basic utility modules such as the Uize.Data, Uize.String, Uize.Template, and other modules.

5.4.2.2. Builder Function

The builder function in your Build Script Anonymous Module Declaration is what contains the code that performs the build script's action.

The code inside this function will be executed when all the modules required by your anonymous module are loaded in by the module loader defined in the Build Script Setup file.

5.5. WSH-compatible UIZE Modules

In addition to using the build script specific modules under the Uize.Wsh namespace, build scripts can also use any of the other UIZE modules that are compatible with Windows Script Host.

5.5.1. Compatible Modules

UIZE modules that ARE compatible with Windows Script Host include...

Uize.Color (and all submodules)
Uize.Curve (and all submodules)
Uize.Data (and all submodules)
Uize.Date
Uize.Doc (and all submodules)
Uize.Fade (and all submodules, but only for non-time based fades)
Uize.Json
Uize.Build.Scruncher
Uize.String (and all submodules)
Uize.Template
Uize.Templates (and all submodules)
Uize.Test (and all submodules)
Uize.Url
Uize.Util.Coupler
Uize.Wsh (and all submodules)
Uize.Xml

5.5.2. Incompatible Modules

UIZE modules that are NOT compatible with Windows Script Host are those modules that assume a browser context, and include such modules as...

Uize.Cookie
Uize.Node (and all submodules)
Uize.Tooltip
Uize.Util.Cycle
Uize.Widget (and all submodules)

5.6. Start Hacking

Needless to say, there are any number of ways to utilize build scripts. All it takes is a little imagination. Crack open any one of the bundled build scripts to get an idea of where to start.