Help Page Reference

Related documents

• Page Reference
• Nav Reference

Table of Contents

• Introduction
  • Tips
• Exported identifiers
  • help
  • The help page
  • Built-in topics
  • The allText page
  • help.toc
• help methods
  • addTopic()
  • hasTopic()
  • showTip()
  • topics()

Introduction

The Help page is a standard built-in popup page that displays help topics. When the Help page is initialized, it automatically gathers the help associated with each defined page by calling the page's renderHelp() method. In addition, pages can call the help.addTopic() method to add additional topics.

The help page supports active links to any help topic, including links within help topics. When a link to a help topic is clicked, a Help popup page instance is created that starts at the requested topic, though the user can then select any topic. If the user subsequently clicks a link within a help topic, a new popup instance of the Help page is created. The user will return to the old topic when the new page is dismissed.

Tips

The help page is also responsible for displaying page tips. These are small popup notices that provide a helpful hint that the user may not know. A tip may be displayed when a page is opened. A page may have several tips. Certain tips are displayed only the first time a page is opened. Others ('anyTime' tips) are displayed when a page is opened, but only if at least 7 days have passed since the last tip of any kind was displayed, so that they are not so frequent that it's annoying. At most one tip is displayed each time a page is opened, with 'firstTime' tips taking priority. Once a tip is displayed, it is not displayed again. However, all of a page's tips are always shown at the bottom of the page's help topic content.

The help page automatically gathers any page tips by reading the page's tipInfo property. The tips will be added to the bottom of the page's help topic.

Exported identifiers

help

Syntax

import {help} from 'common/mvcs/export.js';

The help object provides methods and properties to control the help system.

The help page

The help page has the page ID help. Its state variables are:

• help_selected
  A modelValue holding the ID of the currently selected help topic. The page is opened with a help topic ID as its argument (see nav.help()); an unknown topic ID is ignored.
• help_tipsDisplayed
  A globally saved modelValue holding a comma-separated list of pageId.tipId strings recording which tips have been displayed. Entries for pages or tips that no longer exist are pruned when a tip is displayed.
• help_lastTipsTime
  A globally saved modelValue holding the time (msec) the last tip was displayed.

Because the tip state is saved globally, a tip displayed on any cloud-synced device does not reappear.

Built-in topics

The following topics are added by the help system and are not associated with a page: help (what you can do to help), tips (page tips), offline (offline use), compat (compatibility), trouble (troubleshooting and support), and notes (general software notes and credits).

The allText page

The allText page (page ID allText) presents all of the app's help topics, tips, and card label tips (Ct templates) in a single page of cards. It is used to proof-read the app's prose, which excludes dialogs and notices.

help.toc

Syntax

help.toc = [helpId, {text, options:[helpId, ...]}, ...]

The table of contents of the help topic list. If null (the default), all topics are listed in the order they were added. Otherwise it is set to an array in the order wanted. Each entry is either a help topic ID string or an object with a text heading and an options array of help topic IDs forming a group.

help methods

addTopic()

Syntax

help.addTopic(helpId, info)

Add a help topic. The helpId is an ID string for the help topic. The helpId is used as an option value when selecting the help topic. It should be unique for each topic. The built-in topics (help, tips, offline, compat, trouble, and notes) are added by the help page itself and are not associated with a page. When the Help page gathers the help information from all pages, the helpId is the page ID. The info argument is an object containing the help topic information.

Parameters

• helpId
  A unique help topic ID string.
• info
  An object containing the following properties:
  • title (required)
    A title string for the help topic. The title will be displayed as a selectable item in the help topic list.
  • renderHelp (optional)
    A function that returns the View template for the help topic content. If omitted, the topic displays no content (only its tips, if any). It returns a Template object, a string, a number, a DOM node, a Component object, or an array containing a mix of these types. See the renderHelp() method.
  • tipInfo (optional)
    An array of tip objects. Each tip object contains the following properties:
    • id
      An ID string for this tip. The ID is used to record which tips have been displayed.
    • type
      A string indicating when the tip should be displayed. Tips are displayed as popup messages only once:
      • 'firstTime'
        Display the tip the first time the page is opened.
      • 'anyTime'
        Display the tip when the page is opened, but only if at least 7 days have passed since the last tip was displayed.
    • template
      A Template or string that contains the contents of the tip.
      The tipInfo will be ignored for help not associated with a page ID. The help page automatically gathers any page tips by reading the page's tipInfo property.

hasTopic()

Syntax

help.hasTopic(helpId)

Returns true if helpId is a defined help topic, otherwise false.

showTip()

Syntax

help.showTip(pageId)

Displays a tip for the page pageId, if one is due, using a notice. Tips are displayed at most once. The first undisplayed tip is chosen, with 'firstTime' tips ahead of 'anyTime' tips. A 'firstTime' tip is always displayed, while an 'anyTime' tip is displayed only if at least 7 days have passed since the last tip was displayed. The method does nothing if the page has no tipInfo. It is called automatically when a page is selected by the nav object, so applications do not normally need to call it.

topics()

Syntax

help.topics()

Returns an array of [helpId, info] entries for all the help topics in the order they were added, where info contains the title, renderHelp, and tipInfo as passed to addTopic().