API.md

Classes

Sidekick ⇐ HTMLElement

The sidekick provides helper tools for authors.

Typedefs

elemAttr : Object.<string, string>

The name and value of the attribute to set on an element.

elemLstnr : Object.<string, function()>

The event name and listener to register on an element.

elemConfig : Object

The configuration of an element to add.

pluginButton : Object

The configuration for a plugin button. This can be used as a shorthand for elemConfig.

plugin : Object

The plugin configuration.

viewCallback : function

A callback function to render a view.

viewConfig : Object

A custom view configuration.

helpStep : Object

The definition of a help step inside a helpTopic.

helpTopic : Object

The definition of a help topic.

sidekickConfig : Object

The sidekick configuration.

External

window.hlx.sidekickConfig : sidekickConfig

The global variable holding the initial sidekick configuration.

window.hlx.sidekick : Sidekick

The global variable referencing the Sidekick singleton.

window.hlx.sidekickScript : Element

The

script

element which loaded the sidekick module.

window.hlx.initSidekick ⇒ Sidekick

Initializes the sidekick and stores a reference to it in window.hlx.sidekick.

Sidekick ⇐ HTMLElement

The sidekick provides helper tools for authors.

Kind: global class
Extends: HTMLElement

• Sidekick ⇐ HTMLElement
  • new Sidekick(cfg)
  • .fetchStatus() ⇒ Sidekick
  • .loadContext(cfg) ⇒ Sidekick
  • .checkPushDownContent() ⇒ Sidekick
  • .show() ⇒ Sidekick
  • .hide() ⇒ Sidekick
  • .toggle() ⇒ Sidekick
  • .add(plugin) ⇒ HTMLElement
  • .get(id) ⇒ HTMLElement
  • .remove(id) ⇒ Sidekick
  • .isEditor() ⇒ boolean
  • .isDev() ⇒ boolean
  • .isInner() ⇒ boolean
  • .isOuter() ⇒ boolean
  • .isProd() ⇒ boolean
  • .isFranklin() ⇒ boolean
  • .isHelix() ⇒ boolean
  • .isContent() ⇒ boolean
  • .isAuthenticated() ⇒ boolean
  • .isAuthorized(feature, permission) ⇒ boolean
  • .notify(message, level)
  • .showWait()
  • .showModal(msg, sticky, level, callback) ⇒ Sidekick
  • .hideModal() ⇒ Sidekick
  • .showHelp(topic, step) ⇒ Sidekick
  • .loadCSS(path) ⇒ Sidekick
  • .switchEnv(targetEnv, open) ⇒ Sidekick
  • .update() ⇒ Response
  • .delete() ⇒ Response
  • .publish(path) ⇒ Response
  • .unpublish() ⇒ Response
  • .addEventListener(type, listener, opts)
  • .removeEventListener(type, listener)
  • "shown"
  • "hidden"
  • "pluginused"
  • "contextloaded"
  • "statusfetched"
  • "envswitched"
  • "updated"
  • "deleted"
  • "published"
  • "unpublished"
  • "loggedin"
  • "loggedout"
  • "helpnext"
  • "helpdismissed"
  • "helpacknowledged"
  • "helpoptedout"

new Sidekick(cfg)

Creates a new sidekick.

Param	Type	Description
cfg	sidekickConfig	The sidekick config

sidekick.fetchStatus() ⇒ Sidekick

Fetches the status for the current resource.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick
Emits: statusfetched

sidekick.loadContext(cfg) ⇒ Sidekick

Loads the sidekick configuration and retrieves the location of the current document.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick
Emits: contextloaded

Param	Type	Description
cfg	sidekickConfig	The sidekick config

sidekick.checkPushDownContent() ⇒ Sidekick

Recalculates the height of the sidekick and pushes down the page content by that amount to make room for the sidekick.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick

sidekick.show() ⇒ Sidekick

Shows the sidekick.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick
Emits: shown

sidekick.hide() ⇒ Sidekick

Hides the sidekick.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick
Emits: hidden

sidekick.toggle() ⇒ Sidekick

Shows/hides the sidekick.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick

sidekick.add(plugin) ⇒ HTMLElement

Adds a plugin to the sidekick.

Kind: instance method of Sidekick
Returns: HTMLElement - The plugin

Param	Type	Description
plugin	plugin	The plugin configuration.

sidekick.get(id) ⇒ HTMLElement

Returns the sidekick plugin with the specified ID.

Kind: instance method of Sidekick
Returns: HTMLElement - The plugin

Param	Type	Description
id	string	The plugin ID

sidekick.remove(id) ⇒ Sidekick

Removes the plugin with the specified ID from the sidekick.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick

Param	Type	Description
id	string	The plugin ID

sidekick.isEditor() ⇒ boolean

Checks if the current location is an editor URL (SharePoint or Google Docs).

Kind: instance method of Sidekick
Returns: boolean - true if editor URL, else false

sidekick.isDev() ⇒ boolean

Checks if the current location is a development URL.

Kind: instance method of Sidekick
Returns: boolean - true if development URL, else false

sidekick.isInner() ⇒ boolean

Checks if the current location is an inner CDN URL.

Kind: instance method of Sidekick
Returns: boolean - true if inner CDN URL, else false

sidekick.isOuter() ⇒ boolean

Checks if the current location is an outer CDN URL.

Kind: instance method of Sidekick
Returns: boolean - true if outer CDN URL, else false

sidekick.isProd() ⇒ boolean

Checks if the current location is a production URL.

Kind: instance method of Sidekick
Returns: boolean - true if production URL, else false

sidekick.isFranklin() ⇒ boolean

Checks if the current location is a configured Franklin URL.

Kind: instance method of Sidekick
Returns: boolean - true if Franklin URL, else false

sidekick.isHelix() ⇒ boolean

Deprecated

Kind: instance method of Sidekick
Returns: boolean - true if Franklin URL, else false

sidekick.isContent() ⇒ boolean

Checks if the current location is a content URL.

Kind: instance method of Sidekick
Returns: boolean - true if content URL, else false

sidekick.isAuthenticated() ⇒ boolean

Checks if the user is logged in.

Kind: instance method of Sidekick
Returns: boolean - true if user is logged in (or does not need to be), else false

sidekick.isAuthorized(feature, permission) ⇒ boolean

Checks if the user is allowed to use a feature.

Kind: instance method of Sidekick
Returns: boolean - true if user is allowed, else false

Param	Type	Description
feature	string	The feature to check
permission	string	The permission to require

sidekick.notify(message, level)

Deprecated

Displays a non-sticky notification.

Kind: instance method of Sidekick

Param	Type	Default	Description
message	string | Array.<string>		The message (lines) to display
level	number	2	error (0), warning (1), of info (2)

sidekick.showWait()

Displays a sticky notification asking the user to wait.

Kind: instance method of Sidekick

sidekick.showModal(msg, sticky, level, callback) ⇒ Sidekick

Displays a modal notification.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick
Emits: Sidekick#event:modalshown

Param	Type	Description
msg	object | string | Array.<string>	The message (object or lines)
msg.message	string	The message
msg.css	string	The CSS class to add
msg.sticky	boolean	true if message should be sticky (optional)
msg.level	number	error (0), warning (1), of info (2, default)
msg.callback	function	The function to call when the modal is hidden again
sticky	boolean	true if message should be sticky (optional)
level	number	error (0), warning (1), of info (2, default)
callback	function	The function to call when the modal is hidden again

sidekick.hideModal() ⇒ Sidekick

Hides the modal if shown.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick
Emits: Sidekick#event:modalhidden

sidekick.showHelp(topic, step) ⇒ Sidekick

Displays a balloon with help content.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick

Param	Type	Default	Description
topic	helpTopic		The topic
step	number	0	The step number to display (starting with 0)

sidekick.loadCSS(path) ⇒ Sidekick

Loads the specified default CSS file, or a sibling of the current JS or HTML file. E.g. when called without argument from /foo/bar.js, it will attempt to load /foo/bar.css.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick

Param	Type	Description
path	string	The path to the CSS file (optional)

sidekick.switchEnv(targetEnv, open) ⇒ Sidekick

Switches to (or opens) a given environment.

Kind: instance method of Sidekick
Returns: Sidekick - The sidekick
Emits: envswitched

Param	Type	Default	Description
targetEnv	string		One of the following environments: dev , preview , live or prod
open	boolean	false	true if environment should be opened in new tab

sidekick.update() ⇒ Response

Updates the preview or code of the current resource.

Kind: instance method of Sidekick
Returns: Response - The response object
Emits: updated

sidekick.delete() ⇒ Response

Deletes the preview or code of the current resource.

Kind: instance method of Sidekick
Returns: Response - The response object
Emits: deleted

sidekick.publish(path) ⇒ Response

Publishes the page at the specified path if

config.host

is defined.

Kind: instance method of Sidekick
Returns: Response - The response object
Emits: published

Param	Type	Description
path	string	The path of the page to publish

sidekick.unpublish() ⇒ Response

Unpublishes the current page.

Kind: instance method of Sidekick
Returns: Response - The response object
Emits: unpublished

sidekick.addEventListener(type, listener, opts)

Sets up a function that will be called whenever the specified sidekick event is fired.

Kind: instance method of Sidekick

Param	Type	Description
type	string	The event type
listener	function	The function to call
opts	object	options

sidekick.removeEventListener(type, listener)

Removes an event listener previously registered with addEventListener.

Kind: instance method of Sidekick

Param	Type	Description
type	string	The event type
listener	function	The function to remove

"shown"

This event is fired when the sidekick has been shown.

Kind: event emitted by Sidekick

"hidden"

This event is fired when the sidekick has been hidden.

Kind: event emitted by Sidekick

"pluginused"

This event is fired when a sidekick plugin has been used.

Kind: event emitted by Sidekick
Properties

Name	Type	Description
id	string	The plugin ID
button	Element	The button element

"contextloaded"

This event is fired when the context has been loaded.

Kind: event emitted by Sidekick
Properties

Name	Type	Description
config	sidekickConfig	The sidekick configuration
location	Location	The sidekick location

"statusfetched"

This event is fired when the status has been fetched.

Kind: event emitted by Sidekick

"envswitched"

This event is fired when the environment has been switched

Kind: event emitted by Sidekick
Properties

Name	Type	Description
sourceUrl	string	The URL of the source environment
targetUrl	string	The URL of the target environment

"updated"

This event is fired when a path has been updated.

Kind: event emitted by Sidekick

"deleted"

This event is fired when a path has been deleted.

Kind: event emitted by Sidekick

"published"

This event is fired when a path has been published.

Kind: event emitted by Sidekick

"unpublished"

This event is fired when a path has been unpublished.

Kind: event emitted by Sidekick

"loggedin"

This event is fired when a user has logged in.

Kind: event emitted by Sidekick

"loggedout"

This event is fired when a user has logged out.

Kind: event emitted by Sidekick

"helpnext"

This event is fired when a user clicks next on a help dialog.

Kind: event emitted by Sidekick

"helpdismissed"

This event is fired when a help dialog has been dismissed.

Kind: event emitted by Sidekick

"helpacknowledged"

This event is fired when a help dialog has been acknowledged.

Kind: event emitted by Sidekick

"helpoptedout"

This event is fired when a user decides to opt out of help content.

Kind: event emitted by Sidekick

elemAttr : Object.<string, string>

The name and value of the attribute to set on an element.

Kind: global typedef

elemLstnr : Object.<string, function()>

The event name and listener to register on an element.

Kind: global typedef

elemConfig : Object

The configuration of an element to add.

Kind: global typedef
Properties

Name	Type	Description
tag	string	The tag name (mandatory)
text	string	The text content (optional)
attrs	Array.<elemAttr>	The attributes (optional)
lstnrs	Array.<elemLstnr>	The event listeners (optional)

pluginButton : Object

The configuration for a plugin button. This can be used as a shorthand for elemConfig.

Kind: global typedef
Properties

Name	Type	Default	Description
text	string		The button text
action	function		The click listener
isPressed	function	false	Determines whether the button is pressed
isEnabled	function	true	Determines whether to enable the button
isDropdown	boolean	false	Determines whether to turn this button into a dropdown

plugin : Object

The plugin configuration.

Kind: global typedef
Properties

Name	Type	Default	Description
id	string		The plugin ID (mandatory)
button	pluginButton		A button configuration object (optional)
container	string		The ID of a dropdown to add this plugin to (optional)
override	boolean	false	Determines whether to replace an existing plugin
elements	Array.<elemConfig>		An array of elements to add (optional)
condition	function		Determines whether to show this plugin (optional). This function is expected to return a boolean when called with the sidekick as argument.
advanced	function		Show this plugin only in advanced mode (optional). This function is expected to return a boolean when called with the sidekick as argument.
callback	function		A function called after adding the plugin (optional). This function is called with the sidekick and the newly added plugin as arguments.

viewCallback : function

A callback function to render a view.

Kind: global typedef

Param	Type	Description
viewContainer	HTMLELement	The view container
data	Object	The data to display

viewConfig : Object

A custom view configuration.

Kind: global typedef
Properties

Name	Type	Description
js	string | viewCallback	The URL of a JS module or a function to render this view
path	string	The path or globbing pattern where to apply this view
css	string	The URL of a CSS file or inline CSS to render this view (optional)

helpStep : Object

The definition of a help step inside a helpTopic.

Kind: global typedef
Properties

Name	Type	Description
message	string	The help message
selector	string	The CSS selector of the target element

helpTopic : Object

The definition of a help topic.

Kind: global typedef
Properties

Name	Type	Description
id	string	The ID of the help topic
steps	Array.<helpStep>	An array of helpSteps

sidekickConfig : Object

The sidekick configuration.

Kind: global typedef
Properties

Name	Type	Default	Description
owner	string		The GitHub owner or organization (mandatory)
repo	string		The GitHub owner or organization (mandatory)
ref	string	"main"	The Git reference or branch (optional)
mountpoint	string		The content source URL (optional)
project	string		The name of the Franklin project used in the sharing link (optional)
plugins	Array.<plugin>		An array of plugin configurations (optional)
outerHost	string		The outer CDN's host name (optional)
host	string		The production host name to publish content to (optional)
byocdn	boolean	false	true if the production host is a 3rd party CDN
devMode	boolean	false	Loads configuration and plugins from the developmemt environment
pushDown	boolean	false	true to have the sidekick push down page content
pushDownSelector	string		The CSS selector for absolute elements to also push down
specialViews	Array.<viewConfig>		An array of custom view configurations (optional)
adminVersion	number		The specific version of admin service to use (optional)

window.hlx.sidekickConfig : sidekickConfig

The global variable holding the initial sidekick configuration.

Kind: global external

window.hlx.sidekick : Sidekick

The global variable referencing the Sidekick singleton.

Kind: global external

window.hlx.sidekickScript : Element

The

script

element which loaded the sidekick module.

Kind: global external

window.hlx.initSidekick ⇒ Sidekick

Initializes the sidekick and stores a reference to it in window.hlx.sidekick.

Kind: global external
Returns: Sidekick - The sidekick

Param	Type	Description
cfg	sidekickConfig	The sidekick configuration (extends window.hlx.sidekickConfig)