jsharmony-cms-sdk-express

jsHarmony CMS SDK for Node.js / Express

Installation

Installation and integration instructions are available at jsHarmonyCMS.com

API Documentation

jsHarmonyCmsRouter

• Constructor
• Public Properties
  • onError
  • onPageRender
  • onRedirect
• Public Methods
  • getRouter
  • getStandalone
  • isInEditor
  • resolve
  • route
  • getPageData
  • getPageFile
  • getRedirectData
  • getEditorScript
  • matchRedirect
  • generate404
  • generateError

jsHarmonyCmsEditor Class (Client JS)

• Constructor

jsHarmonyCmsRouter Class

jsHarmonyCmsRouter Constructor

new jsHarmonyCmsRouter(config)

Arguments

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

{
  content_path: null,
  //(string) File path to published CMS content files

  redirect_listing_path: null,
  //(string) Path to redirect listing JSON file (relative to content_path)

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

  strict_url_resolution: false,
  //(bool) Whether to support URL variations (appending "/" or Default Document)

  passthru_timeout: 30,
  //(int) Maximum number of seconds for passthru request

  cms_clientjs_editor_launcher_path: '/.jsHarmonyCms/jsHarmonyCmsEditor.js',
  //(string) Path where router will serve the client-side JS script that launches CMS Editor

  cms_server_urls: [],
  //Array(string) The CMS Server URLs that will be enabled for Page Editing (set to '*' to enable any remote CMS)
  //  * Used by page.editorScript, and the getEditorScript function
  //  * NOT used by jsHarmonyCmsEditor.js - the launcher instead uses access_keys for validating the remote CMS
}

Example

var cmsRouter = new jsHarmonyCmsRouter({ cms_server_urls: ['https://cms.example.com'] });

Public Properties

onError

function(err, req, res, next){ }

Function executed when an unexpected error occurs

cmsRouter.onError = function(err, req, res, next){ console.error(err); };

onPageRender

function(pageFile, req, res, next){ }

Function executed to render the page

cmsRouter.onPageRender = function(pageFile, req, res, next){ res.end(pageFile); }

onRedirect

function(redirect, req, res, next){ }

Function executed when a matching redirect has been found

cmsRouter.onRedirect = function(redirect, req, res, next){ /* return false to not follow redirect */ }

Public Methods

getRouter

<jsHarmonyCmsRouter>.getRouter(options)

Main Entry Point - CMS Express.js Router Application

Parameters

• options: (object) (Optional) Options

  {
     serveContent: (bool),
     //(Optional, default true) Whether the router should serve static content from config.content_path
  
     serveRedirects: (bool),
     //(Optional, default true) Whether the router should serve redirects
  
     servePages: (bool)
     //(Optional, default true) Whether the router should serve pages, based on the request URL
  
     serveCmsEditorScript: (bool)
     //(Optional, default true) Whether the router should serve the CMS Editor Launcher script at config.cms_clientjs_editor_launcher_path
  
     generate404OnNotFound: (bool)
     //(Optional, default false) Whether the router should generate a 404 page if no matching page was found
  }

Returns

(function) Express.js Route

Example

app.use(cmsRouter.getRouter({ generate404OnNotFound: true }));

getStandalone

<jsHarmonyCmsRouter>.getStandalone(req, url)

Main Entry Point - Load Standalone CMS Content

Parameters:

• req: (object) Express.js Request

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

  Use Full URL, Root-relative URL, or leave blank to use current URL from Express.js Request

Returns

(object) Page Object, with additional properties: isInEditor, editorContent, notFound

If page is opened from CMS Editor or Not Found, an empty Page Object will be returned

Page Object {
  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),
  isInEditor: (bool),     //Whether the page was opened from the CMS Editor
  editorScript: (string), //If page was opened from a CMS Editor in config.cms_server_urls, the HTML script to launch the Editor
  notFound: (bool)        //Whether the page was Not Found (page data will return empty)
}

Example

app.get('/standalone_page', async function(req, res, next){
  var page = await cmsClient.getStandalone(req);
  res.render('standalone_page.ejs', { page: page });
});

isInEditor

<jsHarmonyCmsRouter>.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(cmsRouter.isInEditor()){ console.log('Editor'); }

resolve

<jsHarmonyCmsRouter>.resolve(url, options)

Converts URL to CMS Content Path

Parameters

• url: (string) CMS Page URL

  Use Full URL or Root-relative 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 = cmsRouter.resolve(targetUrl);

route

<jsHarmonyCmsRouter>.route(url)

Run CMS router on the target URL

Parameters

• url: (string) CMS Page URL

  Use Full URL or Root-relative URL

Returns

(object) Page, Redirect, or null if Not Found

Page {
    type: 'page',
    content: (string) 'Page file content'
}

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

Example

var routeDest = cmsRouter.route(targetUrl);

getPageData

<jsHarmonyCmsRouter>.getPageData(url, options)

Get CMS Page Data

Parameters

• url: (string) CMS Page URL

  Use Full URL or Root-relative URL

• options: (object) (Optional) Options

  {
     // Starting Variation ID
     variation: (int)
  }

Returns

(object) Page Object, or null if not found

Page Object {
  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 pageData = cmsRouter.getPageData(targetUrl);

getPageFile

<jsHarmonyCmsRouter>.getPageFile(url, options)

Get CMS Page File

Parameters

• url: (string) CMS Page URL

  Use Full URL or Root-relative URL

• options: (object) (Optional) Options

  {
     // Starting Variation ID
     variation: (int)
  }

Returns

(buffer) Page Content

Error is thrown if page is not found

Example

var pageFile = cmsRouter.getPageFile(targetUrl);

getRedirectData

<jsHarmonyCmsRouter>.getRedirectData()

Get CMS Redirect Data

Requires config.redirect_listing_path to be defined

Returns

Array(Redirect Object) Redirects

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

Example

var cmsRedirects = cmsRouter.getRedirectData();

getEditorScript

<jsHarmonyCmsRouter>.getEditorScript(req)

Generate script for CMS Editor

Parameters

• req: (object) Express.js Request

Returns

(string) HTML Code to launch the CMS Editor

If the page was not launched from the CMS Editor, an empty string will be returned

Security

The querystring jshcms_url parameter is validated against config.cms_server_urls

If the CMS Server is not found in config.cms_server_urls, an empty string will be returned

Example

res.send(cmsRouter.getEditorScript(req));

matchRedirect

<jsHarmonyCmsRouter>.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 or Root-relative URL

Returns

(object) Redirect

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

Example

var redirect = cmsRouter.matchRedirect(cmsRedirects);
if(redirect && (redirect.http_code=='301')){
  res.writeHead(301,{ 'Location': redirect.url });
  res.end();
}

generate404

<jsHarmonyCmsRouter>.generate404(req, res)

Generate a 404 Not Found page in Express.js

Parameters

• req: (object) Express.js Request
• res: (object) Express.js Response

Example

cmsRouter.generate404(req, res);

generateError

<jsHarmonyCmsRouter>.generateError(req, res, err)

Generate a 500 Error page in Express.js

Parameters

• req: (object) Express.js Request
• res: (object) Express.js Response
• err: (object|string) Error object or string text

Example

cmsRouter.generateError(req, res, 'An unexpected error has occurred.');

jsHarmonyCmsEditor Class (Client JS)

jsHarmonyCmsEditor Constructor

jsHarmonyCmsEditor(config)

Arguments

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

{
  access_keys: [],
  //Array(string) CMS Editor Access Keys, used to validate remote CMS URL
}

Example

//Load the CMS Editor in this page
jsHarmonyCmsEditor({ access_keys: ['*****ACCESS_KEY*****'] });