acType reference

table of contents

Introduction

The acType object controls the presentation of aircraft data based on the selected aircraft model, serial number, and the selected options. The aircraft data may contain both data and methods. The data for the currently selected aircraft and options in assembled in the acData object. The acData object is global and does not need to be imported. It represents the POH data and the associated computation methods for a particular Pilot's Operating Handbook, Owner's Handbook, or Owner's Manua (we'll call all these POH), as amended by any Airplane Flight Manual Supplements (AFMS) for selected options.

Typically, the Aircraft page allows the user to configure and select aircraft and also sets the ac_data state variable to the contents of acData whenever a new model, serial number, or options are selected. This allows pages to use ac_data to trigger Model computations.

Internal and external model IDs

Each aircraft type (e.g., Beech Bonanza) may have several aircraft models (e.g., A36, V35, etc.). Sometimes, an aircraft model has more than one associated POH (e.g., Bonanza A36). The correct POH is selected by the serial number. The model name that the user associated with the aircraft (e.g., A36) is the "external" model. The set of data that is associated with a specific POH is the "internal" model. An internal model name is the external model name with a suffix consisting of an "_" followed by a string specifying the POH.

Serial numbers and ranges

Serial numbers consist of an alphanumeric prefix that does not vary within the model and can be empty, followed by a numeric string that varies with individual aircraft.

Applicable serial number ranges are specified by a string containing the following elements:

The isInSerialNums() method tests whether a specific serial number (without the prefix) falls within a serial number range string. The isValidSerialNumber() method return true if the serial number is valid for a particular internal model ID.

A model serial number can have a fixed width. If it does, the numeric part of the serial number may be extended with leading zeros as required. The serial numbers in serial number range strings need not contain leading zeros.

Creating aircraft models

Models are created by calling acType.createModel(), which takes an info object as a parameter. The object contains the following properties:

In POH Performance aircraft apps, the Aircraft page imports all the relevant model files to cause them to be loaded. This means that the aircraft models are already defined when the page's init() method is called, at which time the model selector state variable can be configured.

Type-wide data

Some aircraft data applies across all types that the app supports. Examples of type-wide data are risk parameters, the aircraft icon, the fuel type, and default methods, etc. These properties are included in all assembled aircraft data in acData. The type-wide data is set by calling acType.setTypeData(). The type-wide data can be overridden by the data in selected models or options if required.

Merging aircraft-specific data

The type-wide data may include a type-specific data merge method mergeModelData which has the signature:

mergeModelData(target, ...sources)

If no mergeModelData method is provided, then objectOverlay() is used. The acType.setAcData() method is used to merge the current aircraft model data into the type-wide data to build the current aircraft object in acData. The method is also used to merge data for the selected options into the current aircraft data.

If the aircraft data contains nested objects that must be overridden instead of overlayed when aircraft data is merged, then a mergeModelData method must be provided. Often, this method utilizes objectMergePathsOver() to merge only specific nested objects.

Options

Options are optional features that either have a separate AFMS or are embedded in the POH. Each option has an ID and separate data and methods that modify the base data and methods of the aircraft model they are applied to. Each option is identified by an option ID string and has an associated data object containing the modifications to the base model data.

Like model IDs, option IDs can have internal and external versions in cases where the same selected option has different data depending on the model or serial number. Like model IDs, the external and internal parts of the ID string are separated by "_". Each defined option must have a unique internal ID. Each internal option ID must apply to a unique combination of model and serial number. It is an error for a selected external option ID in a given aircraft to apply to more than one internal option ID.

Applicability string

Options are restricted to apply to a specified set of model IDs and serial numbers. These are specified by an applicability string composed of ${modelId}:${serialNumRange}. The modelId is an internal model ID or a RegExp string (without the surrounding '/'), and serialNumRange is a serial number range string or '-' that matches all serial numbers for the matching model IDs. Multiple models and serial ranges can be specified by separating them with a ';'. For example: A36_2:- matches all serial numbers associated the second A36 POH, and A36:-;G36:- or [AG]36:- match all serial numbers in all A36 and G36 POHs. Remember that the modelId being a RegExp can have unexpected effects if some model IDs are substrings of other model IDs. In some cases, it might be best to surround the model ID string with '^' and '$' as in ^[AG]36$:-.

Creating options

Options are created by calling acType.createOption(), which takes an info object as a parameter. The object contains some of the following properties:

The info object must also contain one of the following properties. It may contain both:

Merging option data

When an option is installed, its info.data property is retrieved and used to merge the option's information into the current model data. The options are merged in the order specified by the value of info.order, if provided. The options with the lowest numeric value in info.order are merged first, options that don't specify an order are merged last. There are several ways to merge data, providing flexibility to implement options in various ways.

If the info.data property value is an object using the mergeModelData method. If the info.data property value is a function, it is called with the current aircraft model data object as an argument and returns an object to be used to merge with the model data. This allows the function to build custom option data that extends the model data.

UseValue instances

An option can set the value of a key to a UseValue instance. This allows an option to build a custom value for a specific key. For example, to add a new weight point for a gross weight increase. Assume the model data contains the following property:

glideCasTbl: new Ptable({
	title: `Glide CAS`,
	inputs: [{key:'weight', limit:'clampLo'},],
	output: {key:'ias', rndMult:1},
	a: [
		{p:2100, v:63},
		{p:2600, v:73},
		{p:3100, v:78},
	],
}),

Then, one could write the options property for a gross weight increase to 3,200 lb as:

glideCasTbl: new UseValue((obj, modelData) => {
	const table = modelData.glideCasTbl;
	oldMaxWeight = table.a.at(-1).p;
	oldCas = table.a.at(-1).v;
	table.a.push({
		p: 3200,
		v: round(weightAdjustCas(oldCas, oldMaxWeight, 3200))
	}),
	return (table);
})

Selecting an aircraft model

In POH Performance apps, the Aircraft page allows the user to define and edit a list of aircraft. Each defined aircraft has a selected model within the aircraft type and serial number, along with a set of selected options. Once selected, the Aircraft page calls acType.setAcData() to set up acData according to the selected model, serial number, and options. acType.setAcData() builds the contents of acData by copying the type-wide data, then merging the contents of the selected model's data object, and merging the data objects of the installed options. In addition, it adds the following acData properties:

Displaying selectable options

The user interface to select options is usually on the Aircraft page. The page can use acType.renderOptionRows() to display the options associated with the currently selected aircraft model as <Cr> components.

acType.renderOptionRows() only displays the options in the acData.options.available array. Options not in the acData.options.selectable array are disabled and greyed out, letting the user know that other selections have disabled them.

Conflicting options

When two or more options are to be installed, it's possible that they each try to modify the same properties. This is disallowed and will produce a conflict assertion failure. In addition, some options are incompatible with other options even if they don't produce a conflict. There are several ways to prevent this. The first is the option class: Each option can belong to one or more option classes. Only one option from each class can be installed. The optClass property in the info object contains an array of option class ID strings that the option belongs to. For example, an engine upgrade can belong to option classes 'Eng' and 'GWI' if it provides both an engine upgrade and gross weight increase. If this engine upgrade option is selected, then all other engine upgrades or gross weight increase options are removed from the selectable list.

Like a model ID, an option ID can contain a suffix consisting of an "_" followed by a string specifying a variant of an option. The base (prefix) part of the option ID forms an implicit option class ID. For example, option ID option1_variant1 will define an class ID of option1 in addition to any other class ID defined by optClass. This means that only one option variant is selectable or installed.

Sometimes, selecting an option conflicts with a specific set of other options. The incompatibleWith property in the info object contains an array of option ID strings for options that are incompatible with this one. If this option is selected, the listed options will be removed from the selectable and installed list, and if any option in the list is selected, then this option will also be removed from the selectable list. The incompatibleWith property will allow a selected option to override an installed option, for example, to provide an upgraded replacement for a manufacturer-installed device.

Dependent options

Sometimes an option depends on other options being installed. The enabledBy property in the info object contains an array of option ID strings for options that must be installed if this option is to be visible. If none of the enabling options in the list are installed, then this option is removed from both the selectable list and the available list so it will not be displayed. Use enabledBy when the option is obviously related to its dependencies, such that it doesn't make sense to display the option when no dependency is selected. For example, a turbulence detection option that is dependent on radar being installed.

Alternatively, the includes property in the info object contains an array of option ID strings for options that must be installed if this option is selected. The option remains visible. If the option is selected then all the options in the list are automatically selected and removed from the selectable list so that they cannot be deselected. Use includes when the option is not obviously related to its dependencies so that it makes sence to have the option visible even when its dependencies are not selected. For example, when seat heaters are dependent on a particular interior package and the user may not be aware of the dependency.

Exported identifiers

acData

Syntax

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

The acData object contains the properties and methods that represent the currently selected aircraft model and serial number, as amended by the installed options. The acData object is also a global identifier and does not require an explicit import.

acType

Syntax

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

The acType object contains the properties and methods used to control the currently active aircraft data and define aircraft models and options.

acType methods

createModel()

Syntax

acType.createModel(info)

This function defines a new aircraft model according to the info object. All aircraft models should be defined when the application is loaded, but in any case, before acType.init() is called on startup.

Parameters

createOption()

Syntax

acType.createOption(info)

This function defines a new aircraft model according to the info object. The model will be identified by the internal model ID in info.modelId. info.data can contain an object containing model data properties and methods or be a function with no arguments that returns an object containing model data properties and methods.

All aircraft options should be defined when the application is loaded, but in any case, before acType.init() is called on startup. If it's inconvenient to declare a data object when the file is loaded, use a function to build it dynamically or resolve individual properties using UseValue.

Parameters

The info object must contain at least one or both of optionOn or installedOn properties

externalModels()

Syntax

acType.externalModels()

This function returns an array of external model ID strings. It filters the list of all defined internal model ID strings to extract the unique external IDs.

Return value

An array of model ID strings.

findInternalModels()

Syntax

acType.findInternalModels(extModelId, serialNum)

This function returns an array of internal model ID strings corresponding to the external model ID extModelId and serial number serialNum. If the serial number is valid and corresponds to a single model, then that model ID is returned. If the serial number doesn't correspond to any model with that external model ID, all the internal model IDs with the specified external model ID are returned.

Parameters

Return value

An array of model ID strings.

getModelData()

Syntax

acType.getModelData(modelId)

This function returns the full model data without any options for the given internal modelId. This includes the type-wide data with the model data merged over it. Any uses of UseValue are resolved.

Parameters

Return value

An object containing the data for modelId merged over the type-wide data.

getOptionData()

Syntax

acType.getOptionData(optId, modelId)

This function returns the data associated with option optId as applied to model modelId. If info.data (see acType.createOption()) is a function, the function is called with the model data associated with modelId as an argument.

Parameters

Return value

An object containing the data for optionId.

getOptionInfo()

Syntax

acType.getOptionInfo(extModelId)
acType.getOptionInfo(extModelId, serialNum)
acType.getOptionInfo(extModelId, serialNum, selectedOptions)

This function returns the options object that would be set in acData for the model, serial number, and selected options. See Selecting an aircraft model.

Parameters

Return value

An object containing the data for optionId.

hasOption()

Syntax

acType.hasOption(optionExpr)

This function returns true if the aircraft has options installed according to an expression consisting of option IDs, spaces, and '&', '|', '^', and '!' representing logical AND, OR, XOR, and NOT, respectively. Parentheses may be used for grouping.

Parameters

Return value

A Boolean.

init()

Syntax

acType.init()

This function initializes acType and sets up default aircraft data in acData. This function should be called by app.js after the app is loaded but before calling ctl.startApp to ensure aircraft data is present while the app is being initialized.

acType.init() builds the data for each model, merging it with any type-wise data and memoizing the result.

isApplicable()

Syntax

acType.isApplicable(appStr)
acType.isApplicable(appStr, modelId)
acType.isApplicable(appStr, modelId, serialNum)

This function returns true if the internal model ID modelId and serial number serialNum apply to the applicability string appStr. If serialNum is '-', then modelId must match a model RegExp in appStr that has a serialnumber range of '-'. If modelId and serialNum are unspecified, the data from the current aircraft is used.

Parameters

Return value

A Boolean.

isInSerialNums()

Syntax

acType.isInSerialNums(serialNum, serialNums)

This function returns true if the serial number serialNum is in the serial number range specified by serialNums. If serialNums is '-' then all serial numbers are accepted.

Parameters

Return value

A Boolean.

isModel()

Syntax

acType.isModel(modelExp)
acType.isModel(modelExp, modelId)

This function returns true if the model expression modelExp (a RegExp or RegExp string) matches the internal model ID modelId.

This function is used to verify that the model expression extracted from an applicability string matches a specified internal model.

Parameters

Return value

A Boolean.

isValidSerialNumber()

Syntax

acType.isValidSerialNumber(modelId, serialNum)

This function returns true if serialNum in valid for the interhal modelId.

Parameters

Return value

A Boolean.

models()

Syntax

acType.models()

This function returns an array of all defined internal model IDs.

Return value

An array of model ID strings.

modelTitle()

Syntax

acType.modelTitle(modelId)

This function returns the title (info.title) of the internal model ID modelId.

Parameters

Return value

A string containing the model title.

newName()

Syntax

acType.newName(currentNames)

This function returns a new unique aircraft name that doesn't confilct with any existing name in the currentNames array. It is intended to be used by the Aircraft page when a new aircraft is defined to create a unique name.

acType.newName() creates the name of the form N ${num} where num does not conflict with other names of the same form.

Parameters

Return value

A string containing a unique name.

renderAvailableDataSources()

Syntax

acType.renderAvailableDataSources(extModelId, serialNum)

If serial number serialNum identifies a valid internal model for the extern model ID extModelId then this function returns ''. Otherwise, the function returns a Template with a table containing the available data sources for the internal models associated with extModelId. The table contains the serial number ranges that apply to each data source.

This function is intended for use by the Aircraft page's render() method to inform users of which data POH data sources are available when the serial number is incorrect.

Parameters

Return value

A Template containing a <Table> component.

renderOptionRows()

Syntax

acType.renderOptionRows(modelDataSv, selectedOptSv)
acType.renderOptionRows(modelDataSv, selectedOptSv, displayGroup)

This function returns a Template with a <When> component that triggers when either of the state variables modelDataSv or selectedOptSv is changed. modelDataSv.value contains the constructed model data for the current model and serial number. Normally, this mirrors the contents of acData. selectedOptSv.value contains an array of option IDs for the options that are currently installed in modelDataSv.value. When modelDataSv or selectedOptSv changes, the <When> component generates an array of card rows (<Cr> components) representing each of the available options in modelDataSv.value.options.available for the model and serial number. When a checkbox is selected or deselected, the list in selectedOptSv.value is adjusted.

Each row contains a label with the option title and a value with a checkbox that will be checked if the option appears in the list in selectedOptSv.value. Options that are not in the list of selectable options in modelDataSv.value.options.selectable) will appear greyed out, and the checkbox will be disabled.

This function is intended for use by the Aircraft page's render() method to allow users to select and deselect options. The disabled options also make conflicting options visible.

If displayGroup is present, then only those options whose info.displayGroup string matches displayGroup will be shown. This allows the Aircraft page to group the options into cards (e.g., "Engine", "TipTanks"). If displayGroup is omitted, all the available options will be displayed.

The order that options are presented as a whole or within a displayGroup is set by info.displayOrder, where lower values come first. Options that have no displayOrder set always come after the ones that do. If two info.displayOrder values are equal (or undefined), then the options are sorted in option title order.

Parameters

Return value

A Template containing a <When> component.

renderSourceList()

Syntax

acType.renderSourceList()

This function returns a Template with a <ul> containing a list of all aircraft data sources in the app. This includes all POHs (or Owners Manuals) and Aircraft Flight Manual Supplements.

Return value

A Template containing a <u;> list.

selectOption()

Syntax

acType.selectOption(selectedOptSv, optionId)

This function adds options ID optionId to the array in selectedOptSv.value. This does not rebuild the aircraft data or change acData. acType.setAcData() must eventually be called to rebuild the aircraft data with the new option settings. This function is for conveniently manipulating selectedOptSv.

Parameters

setAcData()

Syntax

acType.setAcData(extModelId)
acType.setAcData(extModelId, serialNum)
acType.setAcData(extModelId, serialNum, selectedOptions)

This function builds the current aircraft data according to the external model ID extModelId, the serial number serialNum, and the array of selected options in selectedOptions. The aircraft data is built by copying the properties of the type-wide data object, then overlaying the properties of the internal model for extModelId and serialNum, then finally overlaying the properties of the installed options.

Parameters

setTypeData()

Syntax

acType.setTypeData(info)

This function sets the type-wide data object to info. The properties in info will be used as a base for all defined aircraft. They may be overridden by either aircraft or option properties.

Parameters

unselectOption()

Syntax

acType.unselectOption(selectedOptSv, optionId)

This function removes options ID optionId from the array in selectedOptSv.value. This does not rebuild the aircraft data or change acData. acType.setAcData() must eventually be called to rebuild the aircraft data with the new option settings. This function is for conveniently manipulating selectedOptSv.

Parameters