API Docs for: 0.8.0
Show:

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 Object

    The localization service object

Methods

_getActiveTheme

(
  • cb
)
private

Retrieves the active theme. When not provided the service retrieves it from the settings service.

Parameters:

  • cb Function

blacklistTemplate

(
  • theme
  • relativePath
)
Boolean static

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:

Boolean:

compile

(
  • text
  • [start='^']
  • [end='^']
)
Array static

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 String

    The template text to compile

  • [start='^'] String optional

    The starting flag marker

  • [end='^'] String optional

    The ending flag marker

Returns:

Array:

The array template parts

getAvailableContentTemplates

(
  • site
)
Array

Retrieves the content templates that are available for use to render Articles and pages.

Parameters:

  • site Object

Returns:

Array:

An array of template definitions

getChildInstance

() TemplateService

Creates an instance of Template service based

Returns:

getCustomPath

(
  • themeName
  • templateLocation
)
String static

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:

String:

The absolute path

getDefaultPath

(
  • templateLocation
)
String static

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:

String:

The absolute path

getRegisteredLocal

(
  • flag
)

returns the value associated with a registered local key(flag)

Parameters:

  • flag String

    The 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:

  1. The theme provided by "getTheme" if not null
  2. The globally set active_theme
  3. Iterates over the list of active plugins looking for the template
  4. The system template directory

Parameters:

  • relativePath String
  • cb Function

    Callback function

getTemplatesForActiveTheme

(
  • cb
)

Retrieves the content template names and locations for the active theme.

Parameters:

  • cb Function

    A call back that provides two parameters: cb(err, [{templateName: templateLocation])

getTheme

() String

Retrieves the prioratized theme

Returns:

String:

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 String

    The flag to transform

  • replacement

    The value can either be a function to handle the replacement or a value.

  • cb Function

    Callback 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 String

    The sub-template flag

  • cb Function

    Callback 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
)
Boolean static

Determines if the content provided is equal to the flag

Parameters:

  • content String
  • flag String

Returns:

Boolean:

isTemplateBlacklisted

(
  • theme
  • relativePath
)
Boolean static

Checks to see if a template has been blacklisted

Parameters:

  • theme String
  • relativePath String

Returns:

Boolean:

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 String

    The relative location of the template file.

  • cb Function

    Callback 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 Object

    The raw content to be inspected for flags

  • cb Function

    Callback 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 String

    The flag to be processed. The value should NOT contain the carrot (^) prefix or postfix.

  • cb Function

    Callback function

registerGlobal

(
  • key
  • callbackFunctionOrValue
)
Boolean static

Registers a value or function for the specified

Parameters:

  • key String

    The 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:

Boolean:

TRUE when registered successfully, FALSE if not

registerLocal

(
  • flag
  • callbackFunctionOrValue
)
Boolean

Registers a value or function for the specified

Parameters:

  • flag String

    The 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:

Boolean:

TRUE when registered successfully, FALSE if not

registerModel

(
  • model
  • [modelName]
)
Boolean

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 Object

    The model is inspect

  • [modelName] String optional

    The optional name of the model. The name will prefix all of the model's keys.

Returns:

Boolean:

TRUE when all keys were successfully registered. FALSE if a single items fails to register.

setGlobalUnregisteredFlagHandler

(
  • unregisteredFlagHandler
)
Boolean

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:

Boolean:

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 String

    The name of the theme.

setUnregisteredFlagHandler

(
  • unregisteredFlagHandler
)
Boolean

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:

Boolean:

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.

Unknown private

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.

unregisteredFlagTemplate

Function