Align '$' helper between routes and model processors
Current Behavior
The $
helper available in model processors is significantly different from the $
utility provided to the routes. This leads to confusion for developers and lots or reimplementing things that already exist elsewhere.
New Behavior
The $
helper will be aligned as much as possible
. There will still be differences, but those differences will be noted below.
Implementation
Shared Utilities
mode
$.mode
Type
(String)
Description
The mode of the SlingConnector connected to the current Request. In standard setups this will be either author
or publish
makeBlankComponent
$.makeBlankComponent(resourceType)
Description
This function is a simple wrapper for creating an Object that BL recognizes as a component. It differs from componentTemplate
in that it doesn't reference the component's template. It simply creates an empty component with the provided type.
Arguments
- resourceType (String) : The resource type of the component to create.
Returns
(Object) : An object that has a non-enumerable property _meta
that is an Object with a single property _sling_resourceType
whose value is set to the provided resourceType
argument.
addScript
Deprecated
$.addScript($, path, options)
Description
Adds the provided script to scripts loaded for the page. Used nearly exclusively in page model processors. Note that while this is available in route processors is likely will not work as intended. It should be moved to the Model Processor specific area.
Arguments
- $ (Object) : The Utilities Object
-
path (String) : The path to the script. Can be a fully qualified path (pointing to an external resource), path to a publicly available resource in BL. No leading slash will auto-root it in the module while a leading slash will root it against the configured
publicMount
. -
options (Object)
-
rev (Boolean) : Defaults to true. If true and the provided
path
is not an external URL the a cache bust time stamp will be appended to the path. -
type (String) : Defaults to 'js'. If provided it must be either 'css' or 'js'. If not provided it will be inferred from
path
.
-
rev (Boolean) : Defaults to true. If true and the provided
Returns
(null)
express
$.express
Type
(Object)
Description
An Object containing the express req
and res
Objects.
blacklight
$.blacklight
Type
(Object)
Description
An Object containing the publicRoot
property, an emailError
function, and a translate
function. The translate function here is Deprecated in favor of the $.translate
function noted below
sling
$.sling
Type
(Object)
Description
The SlingConnector attached to the current Request.
translate
See #23 (closed)
componentTemplate
See #21 (closed)
Model Processor Only Utilities
Model Helpers
All model helpers are available with the structure $.<site>.<modules>.<model-helpers-function>
resolve
$.resolve()
Description
Only used for async Model Processors. Must be called when all processing is complete.
Arguments
Returns
(null)
reject
Deprecated
$.reject(error)
Description
Only used for async Model Processors. Must be called when a breaking error occurs during model processing.
Arguments
- error (Error) : An Error Object detailing what went wrong with the model processing.
Returns
(null)
slingData
$.slingData
Type
(Object)
Description
The raw Sling data for this component.
slingPath
$.slingPath
Type
(String)
Description
The full path to the slingData
in the repository
processSling
Deprecated
$.processSling(model)
Description
Provides a mechanism to model process a component dynamically. While still available, $.componentInclude
will serve most use cases better. This function is really only useful if there is a need for the invoking model processor to immediately see the result of the model processed child data.
Arguments
- model (Object) : The Object model representing a component to be model processed.
Returns
(Promise) : A Promise that will either resolve with the fully processed model or be rejected with the Error that cause the model processing to fail.
resourceType
$.resourceType
Type
(String)
Description
The resource type of this component.
isTopLevel
$.isTopLevel
Type
(Boolean)
Description
A flag indicating whether this model processor is the top level. Primarily used internally.
page
$.page
Type
(Object)
Description
An Object detailing information about the page being rendered for the Request. Includes the following properties:
-
slingPath (String) : Sling path of the page being rendered. More specifically it's the path against which the
.infinity.json
Request is made that creates the top levelslingData
. - trimmedPath (String) : The path the page being request trimmed of all selectors, extension, and any other URL artifacts (query strings, hashes, etc)
- selectors (Array) : An Array of selectors provided in the URL of the original Request
- extension (String) : The extension provided in the initial request
- originalPath (String) : The full URL of the original Request.
-
language (String) : The language segment from the
slingPath
componentInclude
See #20 (closed)
Route Processor Only Utilities
Model Helpers
All model helpers are available from the global bl
property: `global.bl.modules.modelHelpers...
page
$.page
Type
(Object)
Description
An Object detailing information about the page being rendered for the Request. Includes the following properties:
- path (String) : The segment of the URL that triggered this route to be invoked.
-
action (String) : The segments of the URL after
path
, if any. - selectors (Array) : An Array of selectors provided in the URL of the original Request
- extension (String) : The extension provided in the initial request
template
$.template
Type
(Function)
Description
The Handlebar function representing the parsed HBS file for this Route
handleError
$.handleError(error, [status=500])
Description
Used to stop execution of the route and immediately send back an error message.
Arguments
- error: (Error) : The Error that caused the Route processing to fail.
- status: (Number) : Optional. Defaults to 500.
Returns
(null)
logger
$.logger
Type
(Object)
Description
A Logger Object specific to this Route.
setTimeoutPulse
$.setTimeoutPulse(timeoutFunc)
Description
Allows a route to bypass the default 15s timeout four Routes.
Arguments
- timeoutFunc (Function) : A Function to be invoked to check if the Route is still processing.
Returns
(null)
generateComponentModel
$.generateComponentModel(model, [page={}])
Description
This allows a Route to create a fully processed model. Very similar to $.componentInclude
except it takes no direction on where the processed model is places.
Arguments
- model (Object) : The data for the component to be model processed
-
page (Object : This will be used as the
page
object in the Model Processor Utility function
Returns
(Promise) : A Promise that will either resolve with the fully processed model or be rejected with the Error that cause the model processing to fail.