TemplateService Class
A templating engine that provides the ability to read in file snippets and call back for data based on the flags in the template file. The instance can be provided a Localization instance which will be used to perform translations for localization flags are encountered. Flags are marked in html files by the pattern ^xzy^. The values provided here are not HTML encoded. Any reserved characters must be manually encoded by any flag call backs.
Constructor
TemplateService
-
opts
Parameters:
-
opts
ObjectThe localization service object
-
ls
Localization -
activeTheme
String -
site
String
-
Item Index
Methods
- _getActiveTheme
- blacklistTemplate static
- compile static
- getAvailableContentTemplates
- getChildInstance
- getCustomPath static
- getDefaultPath static
- getRegisteredLocal
- getTemplateContentsByPriority
- getTemplatesForActiveTheme
- getTheme
- handleReplacement
- handleTemplateReplacement
- init
- isFlag static
- isTemplateBlacklisted static
- load
- process
- processFlag
- registerGlobal static
- registerLocal
- registerModel
- setGlobalUnregisteredFlagHandler
- setReprocess
- setTheme
- setUnregisteredFlagHandler
Methods
_getActiveTheme
-
cb
Retrieves the active theme. When not provided the service retrieves it from the settings service.
Parameters:
-
cb
Function
blacklistTemplate
-
theme
-
relativePath
Blacklists a template for a theme. This means that the template service will not consider this theme and path combination the next time it is prompted to check for its existence
Parameters:
-
theme
String -
relativePath
String
Returns:
compile
-
text
-
[start='^']
-
[end='^']
Compiles the content be eagerly searching for flags/directives. The static content is also placed into an object. Whether static or a flag, an object is created and pushed into an array. Each object has two properties: "type" that describes the type of template part it is (static, flag). "val" the string value of the part.
Parameters:
-
text
StringThe template text to compile
-
[start='^']
String optionalThe starting flag marker
-
[end='^']
String optionalThe ending flag marker
Returns:
The array template parts
getAvailableContentTemplates
-
site
Retrieves the content templates that are available for use to render Articles and pages.
Parameters:
-
site
Object
Returns:
An array of template definitions
getCustomPath
-
themeName
-
templateLocation
Retrieves the path to a template file based on the assumption that the provided path is relative to the pencilblue/plugins/[themeName]/templates/ directory.
Parameters:
-
themeName
String -
templateLocation
String
Returns:
The absolute path
getDefaultPath
-
templateLocation
Retrieves the default path to a template file based on the assumption that the provided path is relative to the pencilblue/plugins/pencilblue/templates/ directory.
Parameters:
-
templateLocation
String
Returns:
The absolute path
getRegisteredLocal
-
flag
returns the value associated with a registered local key(flag)
Parameters:
-
flag
StringThe flag name to map to the value when encountered in a template.
Returns:
the callback or the value that was assigned to that local if the flag exists. If not, it will return null
getTemplateContentsByPriority
-
relativePath
-
cb
Retrieves the raw template based on a priority. The path to the template is derived from the specified relative path and the following order of directories:
- The theme provided by "getTheme" if not null
- The globally set active_theme
- Iterates over the list of active plugins looking for the template
- The system template directory
Parameters:
-
relativePath
String -
cb
FunctionCallback function
getTemplatesForActiveTheme
-
cb
Retrieves the content template names and locations for the active theme.
Parameters:
-
cb
FunctionA call back that provides two parameters: cb(err, [{templateName: templateLocation])
getTheme
()
String
Retrieves the prioratized theme
Returns:
The prioritized theme to use when loading templates
handleReplacement
-
flag
-
replacement
-
cb
Called when the processing engine encounters a non-sub-template flag. The function delegates the content transformation out to either the locally or globally registered function. In the event that a value was registered and not a function then the value is used as the second parameter in the callback. During template re-assembly the value will be converted to a string.
Parameters:
-
flag
StringThe flag to transform
-
replacement
The value can either be a function to handle the replacement or a value.
-
cb
FunctionCallback function
handleTemplateReplacement
-
flag
-
cb
When a sub-template flag is encountered by the processing engine this function is called to parse the flag and delegate out the loading and processing of the sub-template.
Parameters:
-
flag
StringThe sub-template flag
-
cb
FunctionCallback function
init
()
Sets up the default flags required for the template service, including the flags that were previously considered to be global but now requires to be instanced with the TemplateService
isFlag
-
content
-
flag
Determines if the content provided is equal to the flag
Parameters:
-
content
String -
flag
String
Returns:
isTemplateBlacklisted
-
theme
-
relativePath
Checks to see if a template has been blacklisted
Parameters:
-
theme
String -
relativePath
String
Returns:
load
-
templateLocation
-
cb
Loads a template file along with any encountered sub-template files and processes any flags. The call back provides any error encountered and a second parameter that is the transformed content.
Parameters:
-
templateLocation
StringThe relative location of the template file.
-
cb
FunctionCallback function
process
-
content
-
cb
Scans the template for flags. The callback provides any error and a second parameter that is the populated template with any registered flags replaced.
Parameters:
-
content
ObjectThe raw content to be inspected for flags
-
cb
FunctionCallback function
processFlag
-
flag
-
cb
Called when a flag is encountered by the processing engine. The function is responsible for delegating out the responsibility of the flag to the registered entity. Some flags are handled by default (although they can always be overriden locally or globally). The following flags are considered "baked in" and will be handled automatically unless overriden:
- ^loc_xyz^ - A localization flag. When provided, the Localization instance will have its "get" function called in an attempt to retrieve the properly translated value for the key (the part betwee "^loc_" and the ending "^").
- ^tmp_somedir=someotherdir=templatefileminusext^ - Specifies a sub-template that should be loaded processed. The file is expected to have a .html extension.
Parameters:
-
flag
StringThe flag to be processed. The value should NOT contain the carrot (^) prefix or postfix.
-
cb
FunctionCallback function
registerGlobal
-
key
-
callbackFunctionOrValue
Registers a value or function for the specified
Parameters:
-
key
StringThe flag name to map to the value when encountered in a template.
-
callbackFunctionOrValue
The function to execute to perform the transformation or the value to substitute in place of the flag.
Returns:
TRUE when registered successfully, FALSE if not
registerLocal
-
flag
-
callbackFunctionOrValue
Registers a value or function for the specified
Parameters:
-
flag
StringThe flag name to map to the value when encountered in a template.
-
callbackFunctionOrValue
The function to execute to perform the transformation or the value to substitute in place of the flag.
Returns:
TRUE when registered successfully, FALSE if not
registerModel
-
model
-
[modelName]
Registers a model with the template service. It processes each key/value pair in the object and creates a dot notated string registration. For the object { key: 'value' } with a model name of "item" would result in 1 local value registration in which the key would be "item.key". If no model name existed the registered key would be: "key". The algorithm fails fast. On the first bad registeration the algorithm stops registering keys and returns. Additionally, if a bad model object is pass an Error object is thrown.
Parameters:
-
model
ObjectThe model is inspect
-
[modelName]
String optionalThe optional name of the model. The name will prefix all of the model's keys.
Returns:
TRUE when all keys were successfully registered. FALSE if a single items fails to register.
setGlobalUnregisteredFlagHandler
-
unregisteredFlagHandler
When a flag is encountered that is not registered with the engine the handler is called as a fail safe unless there is a locally registered handler. It is expected to return a string that will be put in the place of the flag.
Parameters:
-
unregisteredFlagHandler
Function
Returns:
TRUE when the handler was set, FALSE if not
setReprocess
-
reprocess
Sets the option that when true, instructs the engine to inspect the content provided by a flag for more flags. This is one way of providing iterative processing of items. See the sample plugin for an example.
Parameters:
-
reprocess
Boolean
setTheme
-
theme
Sets the prioritized theme to use when loading templates
Parameters:
-
theme
StringThe name of the theme.
setUnregisteredFlagHandler
-
unregisteredFlagHandler
When a flag is encountered that is not registered with the engine the handler is called as a fail safe. It is expected to return a string that will be put in the place of the flag.
Parameters:
-
unregisteredFlagHandler
Function
Returns:
TRUE when the handler was set, FALSE if not
Properties
activeTheme
Unknown
CUSTOM_PATH_PREFIX
String
private
static
The absolute path to the plugins directory
localCallbacks
Object
MIS_CACHE
Object
private
static
Tracks the template keys that do not exist on disk. This allows us to skip disk reads after the first request for a non-existent template
reprocess
Boolean
Indicates if the data from the registered flags should be reprocessed. The value is FALSE by default.
siteUid
String
A container that provides the mapping for global call backs. These should only be added to at the start of the application or on plugin install/update.
theme
String
The prioritized theme when selecting templates
unregisteredFlagHandler
Function
The default handler for unregistered flags. It outputs the flag back out.