UIZE JavaScript Framework

MODULES Uize.Build.Util

1. Introduction

The Uize.Build.Util package provides various utility methods to facilitate building of pages for a Web site project.

DEVELOPERS: Chris van Rensburg

1.1. Examples

There are no dedicated showcase example pages for the Uize.Build.Util module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Build.Util module...

SEARCH

1.2. Implementation Info

The Uize.Build.Util module defines the Uize.Build.Util package under the Uize.Build namespace.

1.2.1. Features Introduced in This Module

1.2.2. Features Overridden in This Module

No features have been overridden in this module.

1.2.3. Features Inherited From Other Modules

This module has no inherited features.

1.2.4. Modules Directly Under This Namespace

1.2.5. Unit Tests

The Uize.Build.Util module is unit tested by the Uize.Test.Uize.Build.Util test module.

2. Static Properties

2.1. Uize.Build.Util.jsModuleExtensionRegExp

A regular expression that is used in determining source files for JavaScript modules.

This regular expression matches files with any of the file extensions contained in the Uize.Build.Util.jsModuleExtensions array.

NOTES

see also the companion Uize.Build.Util.jsModuleExtensions static property

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Build.Util.jsModuleExtensions

An array, containing a list of the file extensions for the source files from which JavaScript modules are built.

This list includes the string elements...

'.js' - for regular JavaScript source files
'.js.jst' - for JavaScript template source files
'.csst' - for CSS template source files
'.loc' - for locale strings source files

NOTES

see also the companion Uize.Build.Util.jsModuleExtensionRegExp static property

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Build.Util.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Build.Util.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Methods

3.1. Uize.Build.Util.buildFiles

Facilitates iterating through a folder hierarchy, processing specific files, and writing the results of processing to a specified log file.

SYNTAX

Uize.Build.Util.buildFiles ({
  targetFolderPathCreator:targetFolderPathCreatorFUNC,  // REQUIRED
  targetFilenameCreator:targetFilenameCreatorFUNC,      // REQUIRED
  fileBuilder:fileBuilderFUNC,                          // REQUIRED

  rootFolderPath:rootFolderPathSTR,                     // optional
  alwaysBuild:alwaysBuildBOOL,                          // optional
  doNotEnter:doNotEnterARRAYorREGEXP,                   // optional
  logFilePath:logFilePathSTR                            // optional
});

This method starts iterating through files in the folder that contains the build script being executed and then recursively iterates through subfolders.

3.1.1. targetFolderPathCreator

A function reference, specifying a function that should be used to create a target folder path for the output of the files being built.

The function specified by this parameter should expect to receive one string parameter, being the folder path of the files being built. The function should return a string, being the path of the target folder where the built versions of the files should be written.

In a special case, if the function returns a boolean, then the files in the current folder being processed will not be built, and the boolean value will determine if the method recurses deeper into the current folder's subfolders. This provides a way to skip building the files in the current folder but recurse deeper, or to ignore a particular folder and all its contents - files and subfolders.

3.1.2. targetFilenameCreator

A function reference, specifying a function that should be used to create the target filenames for the output of the files being built.

The function specified by this parameter should expect to receive one string parameter, being the filename of the file being built. The function should return a string, being the target filename for where the built version of the file should be written. If the source file is not to be built, based upon interrogating the source filename (perhaps it's not a type of file that should be built), then the function should return an empty string or the value false.

3.1.3. fileBuilder

A function reference, specifying a function that should be used for processing the source file to create output that should be written as the target file.

The function specified by this parameter should expect to receive two string parameters, being the filename of the source file being built and the text contents of that file. The function should return an object containing the property outputText, being the output text for the built version of the file, and an optional logDetails property that can be used to specify any extra log information to summarize or describe how the file was built.

When a file is built, the output of the function specified by the fileBuilder parameter will be written as a file of the name determined by the targetFilenameCreator function, into a folder of the path determined by the targetFolderPathCreator function.

3.1.4. rootFolderPath

A string, specifying the path of a folder to serve as the root folder from which to start building files.

3.1.5. alwaysBuild

An optional boolean, indicating whether or not eligible files should always be built, or whether the need to build should be determined automatically.

For any file within the folder hierarchy that would be processed by the Uize.Build.Util.buildFiles method (given the configuration of this method by all its parameter values), a decision to build the file will normally be made automatically by this method, based upon the target file either not existing or having an older modified date than the source file. This is the behavior for the optional alwaysBuild parameter's default value of false. When the value true is specified, then the file will always be built, even if it is considered to have been previously built and up-to-date.

3.1.6. doNotEnter

An optional array or regular expression, specifying a folder (or folders) that should not be entered when recursing through the folder hierarchy.

Any folders specified by this parameter will terminate recursion at that point in the folder tree, and any folders contained inside these dead end folders will not be processed. If a regular expression is specified for this parameter, then this regular expression will be tested against the folder name currently being processed by the Uize.Build.Util.buildFiles method. If the regular expression matches, then the method will not enter the folder.

This parameter is useful for build scripts that should ignore files generated by the build script (or other build scripts) and that are stored in a special build directory. Your site project may also contain a folder of build scripts, and you may not wish any build script using the Uize.Build.Util.buildFiles method to process any of the files contained therein.

3.1.7. logFilePath

An optional string, specifying the filename of a file within the same folder as the build script that should be used for writing out the log of the build process.

Basic information is automatically placed into the log file by the Uize.Build.Util.buildFiles method, but additional information for each built file can be added by returning text for the optional logDetails property of your fileBuilder function's return object.

NOTES

If no logFilePath parameter is specified, or if it's value is an empty string, null, or undefined, then the filename for the log file will be derived from the filename of the build script, with the ".js" file extension replaced with the extension ".log".

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Build.Util.compileJstFile

Returns a template function, compiled from the specified JST (.jst) template file.

SYNTAX

templateFUNC = Uize.Build.Util.compileJstFile (jstTemplatePathSTR);

This method caches the compiled template function so that, if multiple requests are made to compile the same template file, the file is only read and the template compiled once. Any modules that are required by the template, using the @required template directive, are required so that the template function returned by this method is safe to call. If the specified JST template file does not exist, then the method returns the value undefined.

IMPLEMENTATION INFO

this feature was introduced in this module

3.3. Uize.Build.Util.dataAsModule

Returns a string, being the text for a data module wrapper for the specified data.

SYNTAX

moduleTextSTR = Uize.Build.Util.dataAsModule (moduleNameSTR,moduleDataANYTYPE);

This method first serializes the data specified by the moduleDataANYTYPE parameter, after which it wraps this serialized data in the form of a data module and then returns the text serialization of this module. If this text were then to be written to a file under the modules folder of a project, then it could be required by the name specified in the moduleNameSTR parameter.

NOTES

see also the related Uize.Build.Util.moduleAsText and Uize.Build.Util.writeDataModule static methods

IMPLEMENTATION INFO

this feature was introduced in this module

3.4. Uize.Build.Util.getHtmlFileInfo

Returns an object, providing information about the specified HTML file.

SYNTAX

htmlFileInfoOBJ = Uize.Build.Util.getHtmlFileInfo (filePathSTR,titleExtractorFUNC);

This method returns an object containing the following properties...

path - the value specified for the filePathSTR parameter (echoed as a convenience)
title - the value of the title tag of the document, modified by the function specified by the titleExtractorFUNC parameter
keywords - the value of the keywords meta tag of the document (an empty string if the tag is not present)
description - the value of the description meta tag of the document (an empty string if the tag is not present)
imageSrc - the value of the image_src link tag of the document (an empty string if the tag is not present)

NOTES

see also the related Uize.Build.Util.getHtmlFilesInfo static method

IMPLEMENTATION INFO

this feature was introduced in this module

3.5. Uize.Build.Util.getHtmlFilesInfo

Returns an array of objects, representing the file info for all the HTML files in the specified folder.

SYNTAX

htmlFilesInfoARRAY = Uize.Build.Util.getHtmlFilesInfo (folderToIndexPathSTR,titleExtractorFUNC);

The returned array is sorted by the titles of the files, as represented by the title property of the file info objects and lowercased so that the sort is case-insensitive. This method uses the related Uize.Build.Util.getHtmlFileInfo method in its implementation to generate the info object for each file, so you can refer to the documentation for that method for more info on the contents of the file info objects.

Files are only considered to be HTML files if their filenames have a .html file extension. Files whose filenames begin with a "~" (tilde) character are excluded from the list, as this prefix is used to indicate files that are not yet ready for prime time and that should be ignored by certain build processes.

NOTES

see also the related Uize.Build.Util.getHtmlFileInfo static method

IMPLEMENTATION INFO

this feature was introduced in this module

3.6. Uize.Build.Util.getJsModuleTodos

Returns a string array, containing the module names of all the TODO files (files with a .todo file extension) under the modules folder of the project.

SYNTAX

jsModuleTodosARRAY = Uize.Build.Util.getJsModuleTodos (paramsOBJ);

IMPLEMENTATION INFO

this feature was introduced in this module

3.7. Uize.Build.Util.getJsModules

Returns an array, containing the names of all the UIZE modules.

SYNTAX

jsModulesARRAY = Uize.Build.Util.getJsModules (paramsOBJ);

The array of module names returned by this method will include modules that are built from various non-JavaScript source files (such as CSS template files with the .csst file extension). For a comprehensive list of such source file types, consult the reference for the Uize.Build.Util.jsModuleExtensions static property.

3.7.1. Params

The paramsOBJ object should have the following properties...

sourcePath - a string, specifying the path where the source files of the project are located
modulesFolder - a string, specifying the name of the folder containing the modules for the project (relative to the source path)

These two properties of the params object correspond to the same named properties of the UIZE config. Therefore, if your code has a reference to the UIZE config object, you can pass it as the paramsOBJ parameter to this method.

IMPLEMENTATION INFO

this feature was introduced in this module

3.8. Uize.Build.Util.getPathToRoot

Returns a string, containing zero or more "../" (back folder) path segments, representing a relative path from the specified relative path back to the root.

SYNTAX

pathToRootSTR = Uize.Build.Util.getPathToRoot (relativePathSTR);

This method is used by build scripts that build pages for nested sections of a site that may have links that are root-absolute and need to be converted to paths that are relative to the document being built. The implementation is very basic (i.e. non-robust) and simply counts all the slashes in the specified path and builds a prefix with that many "../" (back folder) segments.

EXAMPLES

Uize.Build.Util.getPathToRoot ('foo.html');              // returns ''
Uize.Build.Util.getPathToRoot ('foo/bar.html');          // returns '../'
Uize.Build.Util.getPathToRoot ('foo/bar/baz.html');      // returns '../../'
Uize.Build.Util.getPathToRoot ('foo/bar/baz/qux.html');  // returns '../../../'

IMPLEMENTATION INFO

this feature was introduced in this module

3.9. Uize.Build.Util.getTitleFromFilename

Returns a string, being a title that is generated from the specified filename.

SYNTAX

titleSTR = Uize.Build.Util.getTitleFromFilename (filenameSTR);

This method is used by build scripts that build HTML pages from a source format, where a title is needed for the HTML page but no pretty title is provided in the source file (such as in metadata, if the source format supports this). In such cases, a title can be derived from the filename using this method.

The method performs the following transformation on the specified filename...

removes the file extension
converts hyphens / dashes to spaces
capitalizes all the words

EXAMPLE

Uize.Build.Util.getTitleFromFilename ('javascript-animation-and-effects.simple');

In the above example, the value 'Javascript Animation And Effects' would be returned.

IMPLEMENTATION INFO

this feature was introduced in this module

3.10. Uize.Build.Util.moduleAsText

Returns a string, being the module specified by a module definition object serialized to its string form.

SYNTAX

moduleTextSTR = Uize.Build.Util.moduleAsText (moduleDefinitionOBJ);

If a string value is specified for the builder property of the module definition (rather than a builder function, in other words), then this value will be substituted as is for the builder in the serialized module. This allows us to provide the exact code for a module's builder, complete with comments and formatting that you wish to preserve in the serialized text version of the module. This can be useful in some build processes that generate modules.

IMPLEMENTATION INFO

this feature was introduced in this module

3.11. Uize.Build.Util.moduleNameFromModulePath

Returns a string, representing the module name of the module located at the specified path.

SYNTAX

moduleNameSTR = Uize.Build.Util.moduleNameFromModulePath (modulePathSTR);

This method removes the file extension and replaces slashes and underscores with periods to address the way that module paths are constructed for folder organizated modules.

EXAMPLE

Uize.Build.Util.moduleNameFromModulePath ('Uize/Widgets/Button/Html.js.jst');

In the above example, the value 'Uize.Widgets.Button.Html' would be returned.

IMPLEMENTATION INFO

this feature was introduced in this module

3.12. Uize.Build.Util.processJstFile

Compiles the specified JST template file, uses the compiled template function to process the specified input, and writes the result as a new file.

SYNTAX

Uize.Build.Util.processJstFile (jstTemplatePathSTR,templateInputOBJ);

This method writes the result as a file alongside the JST template file, where the name of the written file is the same as the template file but with the .jst suffix stripped off. So, for example, if the JST template file being processed were named "homepage.html.jst", then the written file would be named "homepage.html".

NOTES

see also the related Uize.Build.Util.compileJstFile static method

IMPLEMENTATION INFO

this feature was introduced in this module

3.13. Uize.Build.Util.readSimpleDataFile

Returns an object that is parsed from the specified simple data file, with the children collapsed using the collapseChildren option of the SimpleData parser.

SYNTAX

simpleDataOBJ = Uize.Build.Util.readSimpleDataFile (simpleDataFilePathSTR);

IMPLEMENTATION INFO

this feature was introduced in this module

3.14. Uize.Build.Util.writeDataModule

Wraps the specified data in a data module wrapper of the specified module name and writes the module under the specified modules folder path.

SYNTAX

Uize.Build.Util.writeDataModule (modulesFolderPathSTR,moduleNameSTR,moduleDataANYTYPE);

This method uses the Uize.Build.Util.dataAsModule static method to wrap the data specified by the moduleDataANYTYPE parameter as a data module of the name specified by the moduleNameSTR parameter and then writes the module under the modules folder path specified by the modulesFolderPathSTR parameter.

NOTES

see also the related Uize.Build.Util.dataAsModule static method

IMPLEMENTATION INFO

this feature was introduced in this module