Skip to main content

Parsing Checklists from DOM

Introduction​

The Checklist API offers a way to parse checklist definitions from DOM (document object model) objects. While any object that conforms to the DOM specification can be parsed, the typical use case is parsing definitions from XML. Therefore, the rest of this page is written under the assumption that the source being parsed is XML.

ChecklistDOMParser​

DOM parsing is performed with the ChecklistDOMParser class.

import { ChecklistDOMParser } from '@microsoft/msfs-sdk';

const parser = new ChecklistDOMParser();

// Parses a checklist set definition from the DOM element setElement.
const checklistSetDef = parser.parse(setElement);

ChecklistDOMParser parses checklist item definitions that conform to the default item type to item definition mapping defined by ChecklistItemTypeDefMap. To parse item definitions that conform to a different mapping, a subclass that extends ChecklistDOMParser should be created and used instead. For more information on extending ChecklistDOMParser, please refer to this page.

Options defined by ChecklistDOMParserParseOptions can be passed to parse() to customize the parsing logic.

// Tell the parser to drop list definitions that don't have any items
// and to drop group definitions that don't have any lists.
const checklistSetDef = parser.parse(setElement, {
  discardEmptyLists: true,
  discardEmptyGroups: true
});

// Tell the parser to throw an error when a syntax error is encountered.
try {
  const checklistSetDef = parser.parse(setElement, {
    errorInsteadOfDiscard: true
  });
} catch (e) {
  console.error(e);
}

Finally, the parser can be directed to parse checklist set, group, list, and branch metadata by defining the appropriate metadata parsing functions in ChecklistDOMParserParseOptions.

// Tell the parser to parse metadata for lists that include the shortName property.
const checklistSetDef = parser.parse(setElement, {
  parseListMetadata: (element, parsed, onError) => {
    const shortName = element.getAttribute('short-name');

    if (!shortName) {
      onError(`List ${parsed.name} is missing a short name`);
    }

    return { shortName };
  }
});

const firstListShortName = checklistSetDef.groups[0].lists[0].metadata.shortName;

DOM Syntax​

The Set Tag​

The definition for a single checklist set is parsed from a single tag. The tag can have any name that isn't already taken by one of the tags described in the following sub-sections. All other tags used for defining groups, lists, and items in a set are descendants of the set tag.

<Set>

  <!-- All other tags go in here. -->

</Set>

Set tags can be placed anywhere in the DOM tree, including the root of the tree. When parsing the DOM, query selectors should be used to fetch the desired set tag(s) from the DOM:

// Fetches and parses the element with the ID 'MySet'.
parser.parse(document.querySelector('#MySet'));

// Fetches and parses all <Set> tags in the document.
for (const element of document.querySelectorAll('Set')) {
  parser.parse(element);
}

Groups​

Groups are defined with <Group> tags placed directly under a set tag:

<Set>

  <Group name="Normal Procedures">
  </Group>

  <Group name="Abnormal Procedures">
  </Group>

  <Group name="Emergency Procedures">
  </Group>

</Set>

The order of the <Group> tags determines the order in which their definitions appear in the set's group array.

Lists​

Lists are defined with <List> tags placed directly under the <Group> tags of their parent groups:

<Checklist>
  <Group name="Normal Procedures">

    <List name="Before Engine Start">
    </List>

    <List name="Engine Start">
    </List>

    <List uid="before-taxi" name="Before Taxi">
    </List>

  </Group>
</Checklist>

The order of the <List> tags determines the order in which their definitions appear in their parent group's list array.

Branch​

Branches are defined with <Branch> tags placed directly under the <List> tags of their parent lists:

<Checklist>
  <Group name="Normal Procedures">

    <List name="Engine Start">

      <Branch uid="engine-start-branch-normal" name="Normal Conditions">
      </Branch>

      <Branch uid="engine-start-branch-cold" name="Cold Weather Conditions">
      </Branch>

    </List>

  </Group>
</Checklist>

Items​

Items are defined with <Item> tags placed directly under the <List> tags of their parent lists if they are members of the base list or under the <Branch> tags of their parent branches if they are members of a branch. The order of the <Item> tags within their parent tag determines the order of the corresponding items in the list or branch.

The following sections describe the syntax used to define the item definitions used in the ChecklistItemTypeDefMap mapping. These are the item definitions that ChecklistDOMParser parses by default.

info

Subclasses of ChecklistDOMParser can choose to override the default parsing behavior and parse item definitions that differ from the default ones. In doing so, these subclasses may require a different DOM syntax for item definitions.

Actionable Items​

To define an actionable item, use an <Item> tag with a type attribute of actionable:

<Item type="actionable">
  <LabelText>
    1. Preflight Inspection
  </LabelText>
  <ActionText>
    Completed
  </ActionText>
</Item>

The <LabelText> child tag is required and defines the text that describes the item's topic. The <ActionText> child tag is optional and defines the text that describes the action to be taken for the item.

note

The presence or absence of action text does not affect whether an actionable item is completable. All actionable items are completable.

Branch Items​

To define a branch item, use an <Item> tag with a type attribute of branch:

<Item type="branch">
  <Branch logic="sufficient">engine-start-branch-normal</Branch>
  <Branch logic="sufficient">engine-start-branch-cold</Branch>
  <Text>
    Weather Conditions
  </Text>
</Item>

Each <Branch> child tag defines a single linked branch (the text content of the tag is the branch's unique ID) and the logic to apply to the linked branch's completion state when determining the completion state of the branch item. The logic attribute can be either none (the default if the attribute is omitted), sufficient, or necessary. See this page for a description of how each logic type behaves.

The <Text> child tag is required and defines the item's text.

To define a link item, use an <Item> tag with a type attribute of link:

<Item type="link">
  <Target>before-taxi</Target>
  <Text>
    Go to Before Taxi checklist.
  </Text>
</Item>

The <Target> child tag is required and defines the unique ID of the link's target list or branch.

The <Text> child tag is optional and defines the item's text.

Note Items​

To define a note item, use an <Item> tag with a type attribute of note:

<Item type="note">
  <Text>
    Following engine start, a warm engine should run at idle thrust for at least 2 minutes prior to takeoff.
  </Text>
</Item>

The <Text> child tag is required and defines the item's text.

Title Items​

To define a title item, use an <Item> tag with a type attribute of title:

<Item type="title">
  <Text>
    Descent
  </Text>
</Item>

The <Text> child tag is required and defines the item's text.

Spacer Items​

To define a spacer item, use an <Item> tag with a type attribute of spacer:

<Item type="spacer" />

You can also optionally specify a height for the spacer using the height attribute:

<Item type="spacer" height="1" />

XML Text Formatting​

info

When using XML, all standard XML text formatting conventions must be respected. In particular, this means that certain characters must always be escaped when they appear in the text content for a tag:

  • < (less than): escaped with &lt;
  • & (ampersand): escaped with &amp;

Text parsed from the various text tags in XML preserves all whitespace characters (including newline characters) except leading and trailing whitespace, which are entirely removed. Enclosing the text in quotes (either single or double) causes the text within the quotes to be parsed as a JSON-formatted string (after any XML-escaped characters are resolved).

To preserve leading and/or trailing whitespace in a text tag, use a JSON-formatted string:

<Text>
  "  The spaces before and after this sentence will be preserved.  "
</Text>

To insert a forced line break, use a JSON-formatted string with an escaped newline character (\n):

<Text>
  "This text will have a line break...\nafter the ellipsis."
</Text>