Reference: Render Functions

• Using Render Functions
• Built-in Render Functions
• Publish-only Render Functions
• Site Component / Export Render Functions

Using Render Functions

The Component Templates use HTML / EJS to take the Component Data and Component Properties, and transform them into the resulting HTML.

The Render Functions extend the capabilities of EJS to make it easier to build advanced components.

Render Functions can be called directly from the EJS:

<div>
<%-escapeHTML(item.title)%>
</div>

Built-in Render Functions

The following functions can be used in Component Render Template EJS:

_ :: Lodash library
  * Lodash JavaScript functions can be used in the Component Render Templates
  Examples
    _.each(site_redirects, function(redirect){ ... })  => Iterates over the site_redirects array
    _.trimStart('/path/to/file', '/')  returns 'path/to/file'


escapeHTML(str)
  :: Escapes reserved characters in HTML with character entities.
  Parameters
    str :: (string) HTML string that will be escaped
  Returns
    Escaped string
  Example
    escapeHTML('<br>') returns '&lt;br&gt;'


escapeRegEx(str)
  :: Escapes reserved characters in a Regular Expression
  Parameters
    str :: (string) Text string that will be escaped
  Returns
    Escaped string
  Example
    escapeRegEx('[a-z]') returns '\[a\-z\]'


stripTags(str, ignore, options)
  :: Removes HTML tags from the input string
  Parameters
    str :: (string) Text with HTML tags that will be removed
    ignore :: (Optional) (string) HTML tags that will not be removed, ex. "<a><strong>"
    options :: (Optional) (Object:{ addSpaces: false })
                 addSpaces: (bool) If true, replace tags with spaces
  Returns
    String with HTML tags removed
  Example
    stringTags('<a href="/abc.html">Page</a>') returns 'Page'


iif(condition, valueTrue, valueFalse)
  :: Evaluates condition.  If condition is true, returns valueTrue.  Otherwise, returns valueFalse
  Parameters
    condition :: (bool) Condition that will be evaluated
    valueTrue :: (variant) Return value if condition is true
    valueFalse :: (Optional) (variant) Return value if condition is false.  If not defined, valueFalse will be set to empty string.
  Returns
    If condition is true, returns valueTrue. Otherwise, returns valueFalse
  Example
    <%-iif(menu.tree.length>3, '<hr/>')%>
      Renders a line break if menu.tree.length is greater than 3


isNullUndefinedEmpty(val)
  :: Returns true if value is null, undefined, or an empty string
  Parameters
    val :: (variant) Value that will be tested
  Returns
    (bool) Returns true if value is null, undefined, or an empty string, otherwise false
  Example
    isNullUndefinedEmpty(null) returns true


isNullUndefined(val)
  :: Returns true if value is null or undefined
  Parameters
    val :: (variant) Value that will be tested
  Returns
    (bool) Returns true if value is null or undefined, otherwise false
  Example
    isNullUndefined(null) returns true


renderTemplate(templateName, items)
  :: Renders a template that was defined with the "jsh-template" HTML attribute.
  Parameters
    templateName :: (string) Name of the template to be rendered
    items :: (Optional) (Array) List of data items that will be rendered by the template
  Returns
    Rendered HTML string
  Example
    <ul jsh-template="menu">
      <li jsh-foreach-item>
        <%-item.html%>
        <%-renderTemplate('menu', item.children)%>
      </li>
    </ul>
    <%-renderTemplate('menu', menu.tree)%>


getEJSOutput(f)
  :: Render EJS as a function (advanced feature)
  Parameters
    f :: (function) Function that renders EJS / HTML using EJS tags
  Returns
    (string) Rendered EJS / HTML output
  Example
    escapeHTML('<br>') returns '&lt;br&gt;'
    <%
      function renderContent(rootId){ return getEJSOutput(function(){
        %><div id="<%=rootId%>">Content</div><%
      }); }
    %>
    <%=renderContent('item1')%>
    <%=renderContent('item2')%>


getSitemapURL(sitemap_item)
  :: Returns a URL for a sitemap_item object
  * In most cases, except for Export functions, sitemap_item.href and sitemap_item.onclick should be
      used instead, since they are already pre-processed.
  * In the Page Editor, this will return "#", so that clicking on a link will not change the page.
  Parameters
    sitemap_item :: (sitemap_item) Sitemap item whose URL will be generated
  Returns
    (string) URL to the sitemap item, if the link type is PAGE, MEDIA, or URL
              If the link type is JS, it will return the JS code
  Example
    getSitemapURL(sitemap.sitemap_items[0]) returns '/'


getMenuURL(menu_item)
  :: Returns a URL for a menu_item object
  * In most cases, except for Export functions, menu_item.href and menu_item.onclick should be
      used instead, since they are already pre-processed.
  * In the Page Editor, this will return "#", so that clicking on a link will not change the page.
  Parameters
    menu_item :: (menu_item) Menu item whose URL will be generated
  Returns
    (string) URL to the menu item, if the link type is PAGE, MEDIA, or URL
              If the link type is JS, it will return the JS code
  Example
    getMenuURL(menu.menu_items[0]) returns '/'


getMediaThumbnails(image_url)
  :: Returns an array of available thumbnail URLs for the image
  Parameters
    image_url :: (string) URL to an existing CMS Media item
                          * Path must begin with /_funcs/media/
  Returns
    (object) Dictionary of thumbnail URLs, indexed by thumbnail ID
             * Only thumbnails with "export": true will be returned
  Example
    <img src="<%=getMediaThumbnails(item.image)['small']%>" />


renderPlaceholder(params)
  :: Renders a placeholder in the Page Editor, for components with incomplete parameters or publish-only templates
  * On Publish, renderPlaceholder will return an empty string
  Parameters
    params :: (Optional) (Object: { errors: '' })
                errors: (string) Error message to display in the Placeholder
  Returns
    Rendered HTML string
  Example
    <%-renderPlaceholder()%>
  Example Result
    "<div class="jsharmony_cms_component_preview empty"><h3>Banner</h3></div>"

Publish-only Render Functions

The following functions are only available in publish templates (they will not work in the Page Editor):

include(pathFromRoot)
* Include another page into this page
* Note: Path should be root-relative to the publish root folder
* ex: <%-include('/path/to/page.html')%>

Site Component / Export Render Functions

The following functions are only available in site components during export:

addFile(filePath, fileContent)
  :: Adds a file to the publish folder
  Parameters
    filePath :: (string) Path to the file, relative to publish folder root
    fileContent :: (string) Text content that will be written to the file
  Returns
    (None)
  Example
    addFile('menu/menu1.html', 'Menu content');


hasFile(filePath)
  :: Checks if a file exists in the publish folder
  Parameters
    filePath :: (string) Path to the file, relative to publish folder root
  Returns
    (bool) True if the file exists, otherwise false
  Example
    if(!hasFile('menu/menu1.html')) addFile('menu/menu1.html', 'Menu content');


deleteFile(filePath)
  :: Deletes a file from the publish folder
  Parameters
    filePath :: (string) Path to the file, relative to publish folder root
  Returns
    (None)
  Example
    deleteFile('menu/menu1.html');