nxus-help-topics

Help Topics Module

The Nxus Help Topics module provides access to Help Scout content. In general terms, it offers two ways of retrieving help content (which Help Scout refers to as articles):

• Help Beacons - You can add trigger elements to your web page to display help topics in the Help Scout Beacon (a modal help dialog). You identify the help topic, and the Beacon logic handles its display.
• Topic Details - You can retrieve the detailed data for a help topic. You're responsible for whatever use you want to make of the data. (Help topics can provide a handy place to stash material that isn't strictly a help topic, but benefits from being easily accessible for editing; welcome messages, for example.)

Here's a bit of background on how Help Scout organizes help content:

• Article - As noted above, help content is referred to as an article; it includes the help text and related metadata, including the article identifier, slug and name.
• Collection - Articles are grouped into collections. The Help Topics module provides access to the articles in a single collection.
• Article Slug - The article slug identifies the article in human-readable keywords. (By default, it's a kebab-case rendering of the article name, but any kebab-case word sequence will do.)
• Article Identifier - An opaque unique identifier for the article.

It's handy to use article slugs to designate help topics. They're human-readable, so they give an indication of the topic. Also, you can create slugs for help topics that aren't yet defined. However, the Help Scout Beacon and Document APIs require article identifiers for retrieving help topics, so there's an extra mapping step required to retrieve an article using its slug. The Nxus Help Topics module handles this mapping from slug to identifier, so you don't have to.

Configuration parameters

The Help Topics module accepts these configuration parameters:

• apiKey - The Help Scout Docs API key used for authentication (see the Help Scout documentation for the Docs API Key).
• collectionId - The id of the collection containing the help topic articles. It looks like the easiest place to find the collection id is in the URL for the Help Scout document library landing page (for example, https://secure.helpscout.net/docs/5d8a195e2c7d3a7e9ae18b54/).
• beaconKey - The Help Scout Beacon key. (You can find it in the embed code provided by the Help Scout Beacon Builder; it's the second parameter in the Beacon('init', key) call.) Define this parameter if you're using the help-topics partial to define the Beacon embed code and Help Topics context.
• listURL - the Docs API List Articles endpoint and parameters (default https://docsapi.helpscout.net/v1/collections/:id/articles?status=published&pageSize=100)
• getURL - the Docs API Get Article endpoint and parameters (default https://docsapi.helpscout.net/v1/articles/:id)

Embedding the Help Scout Beacon on web pages

Displaying help topics in the Help Scout Beacon requires the Help Scout Beacon object to defined in the web page context.

The Help Scout Beacon Builder provides embed code that does this.

Alternatively, the Help Topics module defines a help-topics partial through nxus-templater that you can render to provide the embed code.

See Defining the Help Topics context for details.

The \<help-topic-trigger> element

The <help-topic-trigger> element renders an interactive marker that, when clicked, displays the Help Scout Beacon. Use the topic property to specify the help topic to display in the beacon; if no topic is specified, the beacon is opened to the general help interface. If there is no article corresponding to the help topic you specify, the trigger element is hidden (so you can add trigger elements to a page speculatively, and define help topic articles as you see fit).

By default, the trigger element displays a FontAwesome info-circle icon as the clickable element. You can specify an alternate display as the content of the <help-topic-trigger> element.

The <help-topic-trigger> element requires the Help Topics context to be defined for the page. (The context provides the mapping from article slugs to identifiers, and lets the trigger determine which help topics have articles defined.) There's a help-topics partial you can use to set up the context (see Defining the Help Topics context below).

Properties

• topic: string Article slug for the help topic to display.

• opened: boolean The opened/closed state of the trigger. If true, the trigger has the beacon open; if false, the trigger is not controlling the beacon (it may be closed, or open from some other cause). Setting the property programmatically will open or close the beacon.

Styling

You can override these CSS variables to adjust the styling of the trigger element:

• --help-topic-trigger-font-family (default 'FontAwesome')
• --help-topic-trigger-font-size (default 75%)
• --help-topic-trigger-line-height (default 1)
• --help-topic-trigger-font (default uses --help-topic-trigger-font-size, --help-topic-trigger-line-height, and --help-topic-trigger-font-family settings)
• --help-topic-trigger-color (default inherit)
• --help-topic-trigger-color-open (default red)

Example

Here's a simple example showing a help topic with article slug my-help-topic. It replaces the default clickable element with a Font Awesome question-circle glyph.

<help-topic-trigger topic="my-help-topic">
  <i class="far fa-question-circle"></i>
</help-topic-trigger>

Defining the element

The <help-topic-trigger> element can be defined in page setup as follows:

<script src="/node_modules/nxus-help-topics/components/help-topic-trigger.js"></script>

Alternatively, you can use the clientjs includeScript() method:

clientjs.includeScript('default', process.cwd()+"/node_modules/nxus-help-topics/components/help-topic-trigger.js")

Defining the Help Topics context

There is a help-topics partial you can render to define the Help Topics context for a page. It will also provided the embed code for the Help Scout Beacon if it's not already defined. (Make sure you specify the Help Topics beaconKey configuration parameter if you're relying on the partial to provide the embed code.)

Place help-topics partial at the end of the contents of the page <body>...</body> element.

<%- render('help-topics') %>

By default, it sets the beacon display style to manual, so no beacon button will be displayed on the page. You can override this and other configuration settings by passing a beaconConfig object in the render() context. See the HelpScout Beacon JavaScript API for more information on configuration options.

Use with EJS and Nxus Templater

The Help Topics module adds these properties to the templater rendering context:

• beaconKey - The Help Scout Beacon key, copied from the Help Topics configuration parameter.
• helpTopicIndex - An associative array that maps help topic article slugs to article information (id, slug and name).

Possible issues, loose ends

The <help-scout-trigger> element uses ES6 module syntax. This seems to work with webpack and Chrome, but it's not entirely clear whether this approach is robust with other possible bundling strategies and browsers.

The package.json provides a compile-elements script that transpiles the source file for the element. Right now, all it does is remove the double-colon binding syntax (::). However, it could perform more extensive transformations if the need for them became apparent.

API

HelpTopics

Extends NxusModule

Help Topics (interface to Help Scout). See the introduction for a list of configuration parameters.

getHelpTopicIndex

Gets an index of available help topics.

The returned help topic specifications include these properties:

• id - article id
• slug - article slug
• name - article name

Parameters

• options Object index options:- status - selects help topics with specific status (published, notpublished or all); default is published (optional, default {})

Returns Object associative array of help topic specifications, indexed by Help Topic article slug.

getHelpTopicDetail

Gets help topic details.

The returned help topic details object includes these properties:

• id - article id
• slug - article slug
• name - article name
• text - article text; may include HTML markup (There are additional properties; see the Help Scout documentation for the Article Object.

Parameters

• slug string article slug

Returns Object help topic details