HFL formats are packages of content and layout that combine to produce a layout effect. They are usually HFL code and any necessary associated content such as HTML, CSS, javascript, images, etc.
Unlike templates, HFL formats can examine the content they manipulate and the context in which the actions will be done, because they are scripts. They have the potential to move and copy resource files as well as provide layout behavior. A well-designed format may provide sample code, images, CSS snippets and any other files which are needed to support the effect.
In the first step, the format file is located via a call to function getFormat(), which returns a function object that will apply that format to a scope when executed. (In javascript terminology, HFL format files execute as 'Factory' object constructors.)
In the second step, the function object is applied to a scope as an ordinary function call. The returned format function object may be called like any other function.
The returned function object is a javascript-style object, which can contain object properties and methods. Each format designer decides which properties and methods to export.
The main reason for separating the fetching of a format from applying it is to allow the calling application to modify the format's default behavior before it is applied. The parameters controlling the format's behavior are stored within the function as object properties. These properties may be inspected or modified before calling the function to apply the format changes.
A second reason for receiving a format as an object is to be able to get relevant data from it and invoke methods supplied by it. By encapsulating a format as an object, important information can be passed both ways such as the ids and classes of important sub-elements, or the filenames of support files such as .css or .js files.
And formats can provide methods for various features such as creating local copies of support files, or adding additional items to a an existing structure.
The getFormat function
- Locates an HFL format file, and returns a function object that will apply that format to a scope when executed.
- It is basically a 'load' command that initializes data but otherwise does not execute any code.
- The properties of the returned format function may be modified before calling the function, allowing for overrides of default behavior.
- The returned format function object may be called like any other function.
-
EXAMPLES:
-
// Apply a format, but override the id assigned to the top level cell
var fmt = getFormat('slides.carousel4.hfmt'); // Get the format object
fmt.id = 'myCarousel2'; // Override the default id
fmt(); // Apply the format
// Locate an inner scope created by the format
scope (fmt.id) {
...
}
-
The applyFormat function
- Locates an HFL format file and applies its instructions and content to the current scope. It is an optional-scope function, and thus can be invoked as either a function call or a scope with a code block.
- applyFormat() applies a format function object created by getFormat() to the current scope, and then executes the code block if specified.
- applyFormat() takes as its main argument either an existing format object or a filename string. If the latter, it calls getFormat() to fetch the format object automatically.
- When no modifications to the default behavior of a format are needed, calling applyFormat() with a filename string is a simpler way to apply a format, and the code is a bit easier to read.
-
EXAMPLE:
-
// Apply a format, and execute the code after it finishes.
applyFormat('page.Layou4.hfmt') {
...
}
-