jsharmony-cms-sdk-clientjs v1.4.0
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
- Public Methods
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 URLUse 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 URLUse 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 URLUse 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 URLUse 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 URLUse 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 URLUse 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 RedirectsUse 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();