jsharmony-cms-sdk-clientjs

jsHarmony CMS SDK for Client-side JS

Installation

Installation and integration instructions are available at jsHarmonyCMS.com

API Documentation

jsHarmonyCmsClient Class

• Constructor
• Public Properties
  • onError
  • onRouteNotFound
  • onPageRender
  • onPageRendered
  • onPageDestroy
  • onLinkClick
  • onSaveState
  • onRestoreState
• Public Methods
  • Router
  • Standalone
  • isInEditor
  • resolve
  • render
  • route
  • getPageData
  • getRedirectData
  • renderPage
  • matchRedirect
  • bindLinks
  • getPageTemplateId

Constructor

new jsHarmonyCmsClient(config)

Arguments

• config (Object) :: Object with one or more of the configuration keys below:

{
  //Array(string) CMS Editor Access Keys
  access_keys: [],

  //(string) URL to page files
  page_files_path: '/',

  //(string) URL to redirect listing JSON file
  redirect_listing_path: null,

  //(string) Default Directory Document
  default_document: 'index.html',

  //(bool) Whether to try URL variations (add "/", "/<default_document>")
  strict_url_resolution: false,

  //Array(string) List of Page Template Names supported by this instance, or use '*' for all
  cms_templates: ['*'],

  //(bool) Whether to auto-bind the routing events (link click, browser back / forward buttons) for single-page functionality
  bind_routing_events: true,

  //(string) CSS Selector - If set, use an element ID to insert page.footer content, instead of appending to the end of the page
  footer_container: null,

  //(bool) Whether to automatically initialize the CMS Editor & Styles
  auto_init: true,

  //(object) Render Config
  // Define which items to render, or override renderer with custom function
  // Each item can be set to one of the following values:
  //   true (to render) (Default)
  //   false (do not render)
  //   function(val, obj, params){} //Override renderer with custom function
  render: {
    content: true,
      // or content: { [contentArea1]: true, [contentArea2]: true, ... }
    header: true,
    css: true,
    js: true,
    footer: true,
    seo: {
      metadesc: true,
      keywords: true,
      canonical_url: true,
    },
    elements: {
      "window-title": true,
      "cms-content-editor": true,
      "cms-component-content": true,
      "cms-onrender": true,
      "cms-title": true,
      "cms-template": true,
    },
}

Example

var cmsClient = new jsHarmonyCmsClient({ access_keys: ['*****ACCESS_KEY*****'] });

Public Properties

onError

function(err){ }

Function executed when an unexpected error occurs

cmsClient.onError = function(err){ console.error(err.message); };

onRouteNotFound

function(url){ }

Function executed when a matching route is not found for the URL

cmsClient.onRouteNotFound = function(url){ cmsClient.generate404(); };

onPageRender

function(page){ }

Function executed when page rendering has started

cmsClient.onPageRender = function(page){ }

onPageRendered

function(page){ }

Function executed when page rendering has completed

cmsClient.onPageRendered = function(page){ }

onPageDestroy

function(){ }

Function executed when the last rendered page is unbound and cleared from memory

cmsClient.onPageDestroy = function(){ }

onLinkClick

function(url, e){ }

Function executed when a link is clicked in a CMS content area (requires config.bind_routing_events = true)

cmsClient.onLinkClick = function(url, e){ /* return false to cancel click */ }

onSaveState

function(url){ }

Function executed when a URL is saved to the back button history

cmsClient.onSaveState = function(url){ window.history.pushState({}, document.title, url); }

onRestoreState

function(url){ }

Function executed when a user presses back or forward, and loads a history state

cmsClient.onRestoreState = function(url){ cmsClient.route(url); }

Public Methods

Router

<jsHarmonyCmsClient>.Router(url)

Main Entry Point - Run CMS Router

Parameters

• url: (string) (Optional) CMS Page URL

  Use Full URL, Root-relative URL, or leave blank to use current URL

Example

cmsClient.Router();

Standalone

<jsHarmonyCmsClient>.Standalone(url)

Main Entry Point - Load Standalone CMS Content

Parameters:

• url: (string) (Optional) CMS Page URL

  Use Full URL, Root-relative URL, or leave blank to use current URL

Example

cmsClient.Standalone('/login/');

isInEditor

<jsHarmonyCmsClient>.isInEditor()

Checks whether the page is in CMS Edit mode

Parameters

N/A

Returns

(bool) True if this page was opened from the CMS Editor

Example

if(cmsClient.isInEditor()) alert('Opened from CMS Editor');

resolve

<jsHarmonyCmsClient>.resolve(url, options)

Converts URL to CMS Content Path

Parameters

• url: (string) (Optional) CMS Page URL

  Use Full URL, Root-relative URL, or leave blank to use current URL

• options: (object) (Optional) Options

  {
     // Whether to try URL variations (adding "/", "/<default_document>")
     strictUrlResolution: (bool), 
  
     // Starting Variation ID
     variation: (int)
  }

Returns

(string) CMS Content Path

Example

var contentPath = cmsClient.resolve();

render

<jsHarmonyCmsClient>.render(url, options)

Get CMS Content and Render

Parameters

• url: (string) (Optional) CMS Page URL

  Use Full URL, Root-relative URL, or leave blank to use current URL

• options: (object) (Optional) Options

  {
     // Whether to execute HTTP requests synchronously (blocking)
     async: (bool),   
  
     // Function executed after page content is downloaded, before render
     onGetPageData: function(err){ /* return false to cancel page render */ }
  }

Returns

Promise

Example

cmsClient.render();

route

<jsHarmonyCmsClient>.route(url, options)

Run client-side CMS router on the target URL

Parameters

• url: (string) (Optional) CMS Page URL

  Use Full URL, Root-relative URL, or leave blank to use current URL

• options: (object) (Optional) Options

  {
     // Whether to execute HTTP requests synchronously (blocking)
     async: (bool),
  
     // Whether to force a redirect to the target URL if a matching route is not found
     redirectOnNotFound: (bool),
  
     // Whether to display a loading overlay while downloading / rendering content
     loadingOverlay: (bool)
  }

Returns

Promise

Example

cmsClient.route();

getPageData

<jsHarmonyCmsClient>.getPageData(url, options)

Get CMS Page Data

Parameters

• url: (string) (Optional) CMS Page URL

  Use Full URL, Root-relative URL, or leave blank to use current URL

• options: (object) (Optional) Options

  {
     // Whether to execute HTTP requests synchronously (blocking)
     async: (bool),
  
     // Starting Variation ID
     variation: (int)
  }

Returns

Promise<Page>

Page {
  seo: {
      title: (string),   //Title for HEAD tag
      keywords: (string),
      metadesc: (string),
      canonical_url: (string)
  },
  css: (string),
  js: (string),
  header: (string),
  footer: (string),
  title: (string),      //Title for Page Body Content
  content: {
      <content_area_name>: <content> (string)
  },
  properties: {
      <property_name>: <property_value>
  },
  page_template_id: (string)
}

Example

var page = await cmsClient.getPageData();

getRedirectData

<jsHarmonyCmsClient>.getRedirectData(options)

Get CMS Redirect Data

Requires config.redirect_listing_path to be defined

Parameters

• options: (object) (Optional) Options

  {
     // Whether to execute HTTP requests synchronously (blocking)
     async: (bool),
  }

Returns

Promise<Array<Redirect>>

Redirect {
    http_code: (string) '301', '302', or 'PASSTHRU',
    url: (string) 'destination/url',
}

Example

var cmsRedirects = await cmsClient.getRedirectData();

renderPage

<jsHarmonyCmsClient>.renderPage(page, options)

Render CMS Page

Parameters

• page: (Page) CMS Page Data Object (from getPageData function)
• options: (object) (Optional) Options

  {
     // Whether to route links in content areas using single-page JS
     // Default: config.bind_routing_events
     bindLinks: (bool),
  
     // Render Config
     // Default: config.render
     render: (Render Config),
  
     // Container for rendering
     // Default: document.body
     container: (DOM Node),
  
     // Whether to force rendering immediately
     //   When false, renderPage can be called before all containers are added to the DOM
     // Default: false
     immediate: (bool),
  }

Returns

Promise

Example

cmsClient.renderPage(page);

matchRedirect

<jsHarmonyCmsClient>.matchRedirect(redirects, url)

Check if URL matches redirects and return first match

Parameters

• redirects: Array(object) Array of CMS Redirects (from getRedirectData function)

• url: (string) Target URL to match against the CMS Redirects

  Use Full URL, Root-relative URL, or leave blank to use current URL

Returns

(Redirect) Redirect Data

Redirect {
  http_code: '301', '302', or 'PASSTHRU',
  url: '<destination url>'
}

Example

var redirect = cmsClient.matchRedirect(cmsRedirects);
if(redirect && ((redirect.http_code=='301') || (redirect.http_code=='302'))){
  window.location = redirect.url;
}

bindLinks

<jsHarmonyCmsClient>.bindLinks(obj)

Bind links in container to the single-page CMS router

Parameters

• obj: (DOM Node) Container whose links will be bound to the CMS Router

Example

cmsClient.bindLinks(document.body);

getPageTemplateId

<jsHarmonyCmsClient>.getPageTemplateId()

Returns the Page Template ID of the current page or editor template

Parameters

N/A

Returns

(string) Page Template ID

Example

var curPageTemplateId = cmsClient.getPageTemplateId();