Checklist Page Reference

Table of Contents

Introduction

The Checklist page (page ID clist) is a popup page that displays one checklist procedure. It is defined in common/page/checklist.js. The page does not choose the procedure itself. The app must provide a separate page that lists the procedures (for example, the TBM app's procedures.js) and opens the Checklist page with the selected procedure ID. Currently the TBM app and the Testapp use the page. It is optional: an app that has no checklist content does not import common/page/checklist.js.

An app opens a procedure by calling the page's displayProcedure() method, or directly:

nav.popupPage('clist', procedureId);

The procedure templates come from acData.checklist.procedures, a Map from procedure ID to the procedure's template, which the app's aircraft data supplies from its .tml procedure files. The templates use the checklist elements described in XML for Aircraft Checklist Procedures. The page renders them with a private tag namespace, clistNS.

The app must supply:

The page also reads the nav_style state variable (for the ui attribute) and the aircraft's options and applicability (for the option, appliesTo and notAppliesTo attributes).

Displayed procedure

When the selected procedure or the amplification setting changes, the page computes the displayed template with buildProcedureTemplate(). It then selects the first step that is not a memory item (or step 0 if there is none), and clears the decisions. The displayed card has the procedure's <ClTitle> as its title. If the procedure has any amplification, the title bar also has a "Show Amplification"/"Hide Amplification" button that toggles clist_showAmplified and clears the selected step.

Only numbered steps (<ClStep>) can be selected, by touching them. Memory items, notes, text, and conditions are not selectable. The selected step is highlighted.

Side control

A control column beside the card (swappable between the right and left sides with the &switch; button, clist_ctlLeft) has the following buttons:

Speech and autoplay

The step sound setting clist_soundType is off, check (say "check" when a step is selected or advanced), or speak (speak the step). Speech and autoplay apply only to a spoken procedure: the <ClProcedure> has a true speak attribute and the amplified variant is not displayed. For other procedures, play is disabled.

A step is spoken from what it displays: the <ClConditionHeading>, <ClStepObject> and <ClStepAction> contents, in that order. A spokenCondition, spokenObject, or spokenAction attribute on the <ClStep> overrides the displayed text for that part. Character entities are spoken as words where needed (for example, &lt; as "less than"), live state variable values are spoken as displayed, tables are skipped, and a CAS <ClAlert> is spoken followed by "CAS" and its type. Conditions that stop play (see below) are announced with "condition" followed by the condition text.

Autoplay speaks each step, pauses for clist_autoPlayDelay × 0.5 s, and advances until it reaches a stop point. At the end of the procedure it says "end of procedure", and at any other stop it says "play stopped". Autoplay stays enabled at a stop, so selecting another step resumes play from it. Touching a step while autoplay is reading it stops autoplay. The speech rate is 1 + clist_speechRate / 4 times normal. Leaving the page stops speech.

Stacked pages

A procedure can contain a link to another procedure (<Ref ref=cl.procedureId>, or a <ClRef>). Following it opens another Checklist popup. The page saves its procedure, step, decisions, and amplification when it is deactivated under another popup and restores them when it is reactivated.

Exported identifiers

clistNS

Syntax

import {clistNS} from 'common/page/checklist.js';

A Map that is the checklist tagNamespace. It maps the checklist element tag names to the components that render them. Wrap checklist content that the app renders itself with <With tagNamespace=${clistNS}>.

The map has components for: ClBody, ClMemoryGroup, ClStep, ClRef, ClAlert, ClTitle, ClShortTitle, ClHeading, ClConditionHeading, ClShortConditionHeading, ClLabel, ClCustomText, ClText, ClDirective, ClAmplifiedText, ClFigure, ClCustomLine, ClCautionNote, ClWarningNote, ClAdvisoryNote, ClSituation, ClConditionalGroup, ClNamedGroup, ClEop, ClDecisionGroup and ClAlternativesGroup. The <ClStepObject>, <ClStepAction>, <ClStepNote> and <ClStepAmplification> children are rendered by <ClStep> itself.

The <ClAlert> element reads the device, system, and type attributes and renders a <span> with the class clAlert_${device}_${system}-${type} (the _${system} part is omitted when there is no system).

getProcTitle()

Syntax

import {getProcTitle} from 'common/page/checklist.js';
getProcTitle(id)

Arguments

Returns a displayable title template for the procedure. It uses the procedure's <ClShortTitle> if it has one that applies to the current aircraft and otherwise its <ClTitle>, with elements that don't apply to the aircraft (by appliesTo, option, etc.) removed. The result already uses the checklist tag namespace. Returns '' if there is no such procedure. It asserts if the procedure has no applicable title.

buildProcedureTemplate()

Syntax

import {buildProcedureTemplate} from 'common/page/checklist.js';
buildProcedureTemplate(procTemplate, showAmplified = false, memOnly = false)

Arguments

Returns a displayable clone of the procedure template, or null if nothing is displayable. The clone omits elements that the current aircraft does not display:

A <ClBody> with a useProcedure attribute takes the (non-title) children of the named procedure; if that procedure doesn't exist, it gets a <ClEop />. Image src attributes are prefixed with imageBase. Elements inside a <ClMemoryGroup> get the isMemory property, and every element gets hasMemory if it is or contains a memory item. The result's tagNamespace is clistNS.

The following properties are added to the returned template:

Each step also gets continuePlay (false if a decision group, conditional group, alternatives group, situation, directive, or text follows it, or it is the last step), eop (true for the last step before a <ClEop> and for the last step of the procedure), and stopText (the speakable text of the situation, directive, or text that stops play). The nextProcedure and speak attributes of the <ClProcedure> remain available as properties of the template. As the code is written, an <eop /> element is also appended at the end unless the last child has the tag eop; since a procedure normally ends with <ClEop>, the element is usually appended in addition.

Page state variables

All the state variables have the prefix clist_.

State variable Type Description
clist_selectedProc modelValue The procedure ID being displayed.
clist_selectedStep modelValue The selected step number (1-based), or 0 for none.
clist_selectedDecisions modelObject An array, indexed by decision number, of the selected branch of each <ClDecisionGroup>.
clist_soundType selectorInput off, check (default), or speak. Saved locally.
clist_speechRate selectorInput 0 (normal) to 4 (fast). Saved locally.
clist_autoPlayDelay selectorInput 0 (small) to 4 (large), default 1. Saved locally.
clist_ctlLeft booleanInput True if the side control is on the left.
clist_showAmplified booleanInput True to show the amplified procedure.
clist_autoPlay modelValue True while autoplay is enabled.
clist_template modelObject The displayed template computed from the above.

Page methods

open()

Called with the procedure ID when the page is opened. Sets the selected procedure, selects the first non-memory step, clears the decisions, and turns off amplification and autoplay.

close()

Turns off autoplay and stops any speech.

displayProcedure()

Syntax

ctl.page('clist').displayProcedure(id)

Arguments

Displays the procedure according to its element type. A <ClProcedure> opens a Checklist popup page. A <ClInformation> is displayed in a notice (its <ClTitle> is left out). Any other tag, including <ClDescription>, fails an assertion: the page does not currently display a <ClDescription>.