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 idslug
- article slugname
- 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 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
Returns Object help topic details