API.md

Classes

Sidekick ⇐ HTMLElement

The sidekick provides helper tools for authors.

Typedefs

Plugin : Object

The plugin configuration.

ViewConfig : Object

A custom view configuration.

HelpStep : Object

The definition of a help step inside a help topic.

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(refreshLocation) ⇒ Sidekick
  • .loadContext(cfg) ⇒ Sidekick
  • .checkPushDownContent() ⇒ Sidekick
  • .show() ⇒ Sidekick
  • .hide() ⇒ Sidekick
  • .toggle() ⇒ Sidekick
  • .add(plugin) ⇒ HTMLElement
  • .get(id) ⇒ HTMLElement
  • .remove(id) ⇒ Sidekick
  • .isEditor() ⇒ boolean
  • .isAdmin() ⇒ boolean
  • .isDev() ⇒ boolean
  • .isInner() ⇒ boolean
  • .isOuter() ⇒ boolean
  • .isProd() ⇒ boolean
  • .isProject() ⇒ 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
  • "shown" (e)
  • "hidden" (e)
  • "pluginused" (e)
  • "contextloaded" (e)
  • "statusfetched" (e)
  • "envswitched" (e)
  • "updated" (e)
  • "deleted" (e)
  • "published" (e)
  • "unpublished" (e)
  • "loggedin" (e)
  • "loggedout" (e)
  • "helpnext" (e)
  • "helpdismissed" (e)
  • "helpacknowledged" (e)
  • "helpoptedout" (e)

new Sidekick(cfg)

Creates a new sidekick.

Param	Type	Description
cfg	SidekickConfig	The sidekick config

sidekick.fetchStatus(refreshLocation) ⇒ Sidekick

Fetches the status for the current resource.

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

Param	Type	Description
refreshLocation	boolean	Refresh the sidekick's location (optional)

sidekick.loadContext(cfg) ⇒ Sidekick

Loads the sidekick configuration and language dictionary, 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
See: SidekickConfig.pushDown

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.isAdmin() ⇒ boolean

Checks if the current location is an admin URL (SharePoint or Google Drive).

Kind: instance method of Sidekick
Returns: boolean - true if admin 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.isProject() ⇒ boolean

Checks if the current location is a configured project URL.

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

sidekick.isHelix() ⇒ boolean

Deprecated

Checks if the current location is a configured project URL.

Kind: instance method of Sidekick
Returns: boolean - true if project URL, else false
See: isProject

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
See: showModal

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

"shown" (e)

This event is fired when the sidekick has been shown.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	Sidekick	The sidekick

"hidden" (e)

This event is fired when the sidekick has been hidden.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	Sidekick	The sidekick

"pluginused" (e)

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

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	Object	The event payload
e.detail.data.id	string	The plugin ID
e.detail.data.button	Element	The button element

"contextloaded" (e)

This event is fired when the context has been loaded.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	Object	The event payload
e.detail.data.config	SidekickConfig	The sidekick configuration
e.detail.data.location	Location	The sidekick location

"statusfetched" (e)

This event is fired when the status has been fetched.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	Object	The status object

"envswitched" (e)

This event is fired when the environment has been switched

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	Object	The event payload
e.detail.data.sourceUrl	string	The URL of the source environment
e.detail.data.targetUrl	string	The URL of the target environment

"updated" (e)

This event is fired when content or code has been updated.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	string	The updated path

"deleted" (e)

This event is fired when a resource has been deleted.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	string	The deleted path

"published" (e)

This event is fired when content has been published.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	string	The published path

"unpublished" (e)

This event is fired when content has been unpublished.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	string	The unpublished path

"loggedin" (e)

This event is fired when a user has logged in.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	Sidekick	The sidekick

"loggedout" (e)

This event is fired when a user has logged out.

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	Sidekick	The sidekick

"helpnext" (e)

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

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	string	The help topic

"helpdismissed" (e)

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

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	string	The help topic

"helpacknowledged" (e)

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

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	string	The help topic

"helpoptedout" (e)

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

Kind: event emitted by Sidekick

Param	Type	Description
e	CustomEvent	The event

Properties

Name	Type	Description
e.detail.data	string	The help topic

Plugin : Object

The plugin configuration.

Kind: global typedef
Properties

Name	Type	Default	Description
id	string		The plugin ID (mandatory)
title	string		The button text
titleI18n	Object	{}	A map of translated button texts
url	string		The URL to open when the button is clicked
passConfig	boolean		Append additional sk info to the url as query parameters: ref, repo, owner, host, project
passReferrer	boolean		Append the referrer URL as a query param on new URL button click
event	string		The name of a custom event to fire when the button is clicked. Note: Plugin events get a custom: prefix, e.g. "foo" becomes "custom:foo".
containerId	string		The ID of a dropdown to add this plugin to (optional)
isContainer	boolean		Determines whether to turn this plugin into a dropdown
isPalette	boolean		Determines whether a URL is opened in a palette instead of a new tab
paletteRect	string		The dimensions and position of a palette (optional)
environments	Array.<string>		Specifies when to show this plugin (admin, edit, dev, preview, live, prod)
excludePaths	Array.<string>		Exclude the plugin from these paths (glob patterns supported)
includePaths	Array.<string>		Include the plugin on these paths (glob patterns supported)

ViewConfig : Object

A custom view configuration.

Kind: global typedef
Properties

Name	Type	Description
path	string	The path or globbing pattern where to apply this view
viewer	string	The URL to render this view

HelpStep : Object

The definition of a help step inside a help topic.

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 help steps

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 project used in the sharing link (optional)
plugins	Array.<Plugin>		An array of plugin configurations (optional)
previewHost	string		The host name of a custom preview CDN (optional)
liveHost	string		The host name of a custom live CDN (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 development environment
devOrigin	boolean	http://localhost:3000	URL of the local development 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
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)