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 theBeacon('init', key)
call.) Define this parameter if you're using thehelp-topics
partial to define the Beacon embed code and Help Topics context.listURL
- the Docs API List Articles endpoint and parameters (defaulthttps://docsapi.helpscout.net/v1/collections/:id/articles?status=published&pageSize=100
)getURL
- the Docs API Get Article endpoint and parameters (defaulthttps://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
(default75%
)--help-topic-trigger-line-height
(default1
)--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
(defaultinherit
)--help-topic-trigger-color-open
(defaultred
)
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
andname
).
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 idslug
- article slugname
- article name
Parameters
options
Object index options:-status
- selects help topics with specific status (published
,notpublished
orall
); default ispublished
(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 idslug
- article slugname
- article nametext
- 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