TOLD Module Reference

Related documents

• MVCS index
• Page Reference
• unitTest Reference
• Test Page Reference

Table of contents

• Introduction
  • Writing a page's TOLD lines
  • Plain text conversion
  • Self-test
• Exported identifiers
  • toldPageIds
  • toldText()
  • composeTold()
  • mailTold()
  • toldErrorRow()
  • isToldAirportValid()
  • toldAirportRows()

Introduction

TOLD (Takeoff and Landing Data) is the flight planning results as plain text, as emailed to the user by the Email button on the Weight and Balance and Flight Performance pages. The told module composes the text from the pages and mails it. It replaces the per-app copies of the old email code, so every aircraft app builds its email the same way.

Each page that contributes to the TOLD defines a renderTold() method that returns a template of the text lines it wants in the email. The module converts each template to text, asserting on anything that can't be represented as plain text, and joins the pages' text with a blank line between pages.

import {composeTold, mailTold} from 'common/option/told.js';

Import only what is needed, for example toldErrorRow and toldAirportRows in an airport page, and mailTold in a page with an Email button.

Writing a page's TOLD lines

A page defines renderTold() alongside render() and renderHelp():

renderTold () {
	return (tml`
		<PlainText>
			<Pl>Takeoff ground roll: {{dep_roll@}}</Pl>
		</PlainText>
	`);
},

• The root must be a <PlainText> element. <PlainText></PlainText> is valid and contributes nothing to the email.
• Each line is a <Pl> element. Only <Pl> elements are allowed directly inside <PlainText>. A page that has nothing to say for a given state can return <PlainText></PlainText>.
• A <Pl> can contain text, character entities, and state variable references. No other element is allowed. <PlainText> and <Pl> are never rendered; they exist only for the conversion.
• {{id}} inserts the state variable's formatted value in its current unit. {{id@}} (also {{id|@}}, or a showUnits property) adds the unit abbreviation after a space.
• A line that comes out empty is kept, so <Pl></Pl> produces a blank line.

Two tml details matter when writing lines:

• Whitespace alone between two children is dropped, so write {{a@}} {{b@}} to put a space between two references.
• Interpolated strings aren't parsed. To interpolate text that contains character entities, pass it through tml(text), as in ${tml(text.toLowerCase())}.

The tmlLint script checks the state variable references in renderTold() templates like any other template, so a reference to an undefined state variable is caught by make lint.

Plain text conversion

The email is sent without a character set, so the result is restricted to printable ASCII.

• Character entities are replaced with ASCII: the spaces (nbsp, nnbsp, thinsp, thinNbsp, ensp, emsp) become a space; le and ge become <= and >=; lt, gt and amp become <, > and &; deg becomes deg; minus, ndash and mdash become -; plusMinus and plusmn become +/-; and times becomes x. An entity not in this list asserts.
• A state variable that doesn't exist contributes nothing. One that is invalid contributes Invalid.
• A formatted value or unit that itself contains entities, such as the °C unit of a temperature, is converted the same way (15 deg C).
• In each line, runs of white space collapse to one space, a space before ,, ;, : or ) is dropped, and leading and trailing white space is removed.

Anything the converter can't represent calls assert(), so the self-test finds in development what the user's email would otherwise show.

Self-test

The module defines a TOLD self-test (see unitTest) that is registered when the module is imported. In an app without aircraft (the Radar app) it does nothing. Otherwise it:

• checks the conversion itself: entities, blank lines, space before punctuation, units with entities, time units, entities in values, invalid values, and that a disallowed tag, an unknown entity, text outside a line, and a root other than <PlainText> each assert once;
• composes the TOLD for every model alone and for every model with each of its selectable options installed one at a time. A sub-test fails if composing throws or asserts, or if the text contains undefined, NaN, [object, an unconverted &entity;, a tag, or any character outside printable ASCII;
• when the departure airport results are valid, also fails if the text has no Takeoff ground roll: <value> line, so the departure page must keep that line.

The test selects each model with selectModel() and firstSerial(), which the Test page exports for this purpose.

Exported identifiers

toldPageIds

Syntax

import {toldPageIds} from 'common/option/told.js';

An array of the page IDs that compose the TOLD, in order: 'ac', 'wb', 'dep', 'enrt', 'dest', 'alt', 'depRtn'. composeTold() requires every page in the list to define renderTold().

toldText()

Syntax

toldText(template)

Converts a <PlainText> template to plain text, one line per <Pl>. Anything that isn't allowed, as described in Writing a page's TOLD lines and Plain text conversion, calls assert().

Parameters

• template
  A Template whose tag is PlainText.

Return value

A string with the lines separated by '\n'. If template isn't a <PlainText> template, an assert fails and the string is empty.

composeTold()

Syntax

composeTold()

Calls renderTold() on each page in toldPageIds, converts the result with toldText(), and joins the pages that produced text with a blank line between them. A page that has no renderTold() method asserts.

Return value

A string containing the TOLD text.

mailTold()

Syntax

mailTold()

Emails the composed TOLD, with the subject Flight planning results, to the address in the set_email state variable (see the Settings page). If no address has been entered, it posts a notice asking the user to enter one on the Settings page and sends nothing. Otherwise it uses server.sendEmail() and posts a notice when the mail is sent or fails. It is used as the onclick handler of the Email button, so it takes no arguments and returns nothing.

toldErrorRow()

Syntax

toldErrorRow(pageId, name)

Returns the line for a page's error message, <name> error: <message>, if the state variable <pageId>_errorMsg is not empty; otherwise it returns an empty string. Put the result directly in a <PlainText> template.

Parameters

• pageId
  The airport page ID, such as 'dep'.
• name
  The name used in the text, such as 'Departure'.

Return value

A <Pl> template or an empty string.

isToldAirportValid()

Syntax

isToldAirportValid(pageId)

Returns true if the airport page's results can be reported: all of <pageId>_airportId, _elevation_ft, _windDir_M, _windSpeed_wkt, _oat_dC, _runwayId, _bestRunwayId, _roll_ft, _obstacle_ft and _runwayLeft_ft are valid. A page normally writes its airport and runway lines only when this is true, and a line such as Invalid departure information otherwise.

Parameters

• pageId
  The airport page ID.

Return value

A Boolean.

toldAirportRows()

Syntax

toldAirportRows(pageId, name)

Returns the lines shared by the airport pages:

• <name> airport: <airportId>, only if the airport ID is not empty,
• <name> airport elevation: <elevation>,
• <name> weather: <wind direction> @ <wind speed> <wind units>, <temperature>, and
• <name> runway: <runway>, followed by the runway length and surface in parentheses when the runway length is valid and greater than zero.

The runway shown is the best runway if <pageId>_selRunway is 'Best', and the selected runway otherwise. The state variables used are <pageId>_airportId, _elevation_ft, _windDir, _windSpeed, _windSpeedUnits, _oat, _bestRunwayId, _runwayId, _runwayLength_ft and _runwaySurface.

Parameters

• pageId
  The airport page ID, such as 'dep', 'dest', 'alt' or 'depRtn'.
• name
  The name used in the text, such as 'Departure'.

Return value

An array of <Pl> templates. Put the result directly in a <PlainText> template.