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:
-
optsObjectThe localization service object
-
lsLocalization -
activeThemeString -
siteString
-
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:
-
cbFunction
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:
-
themeString -
relativePathString
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:
-
textStringThe 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:
-
siteObject
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:
-
themeNameString -
templateLocationString
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:
-
templateLocationString
Returns:
The absolute path
getRegisteredLocal
-
flag
returns the value associated with a registered local key(flag)
Parameters:
-
flagStringThe 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:
-
relativePathString -
cbFunctionCallback function
getTemplatesForActiveTheme
-
cb
Retrieves the content template names and locations for the active theme.
Parameters:
-
cbFunctionA 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:
-
flagStringThe flag to transform
-
replacementThe value can either be a function to handle the replacement or a value.
-
cbFunctionCallback 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:
-
flagStringThe sub-template flag
-
cbFunctionCallback 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:
-
contentString -
flagString
Returns:
isTemplateBlacklisted
-
theme -
relativePath
Checks to see if a template has been blacklisted
Parameters:
-
themeString -
relativePathString
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:
-
templateLocationStringThe relative location of the template file.
-
cbFunctionCallback 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:
-
contentObjectThe raw content to be inspected for flags
-
cbFunctionCallback 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:
-
flagStringThe flag to be processed. The value should NOT contain the carrot (^) prefix or postfix.
-
cbFunctionCallback function
registerGlobal
-
key -
callbackFunctionOrValue
Registers a value or function for the specified
Parameters:
-
keyStringThe flag name to map to the value when encountered in a template.
-
callbackFunctionOrValueThe 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:
-
flagStringThe flag name to map to the value when encountered in a template.
-
callbackFunctionOrValueThe 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:
-
modelObjectThe 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:
-
unregisteredFlagHandlerFunction
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:
-
reprocessBoolean
setTheme
-
theme
Sets the prioritized theme to use when loading templates
Parameters:
-
themeStringThe 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:
-
unregisteredFlagHandlerFunction
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.
