PhetioIDUtils

PhetioIDUtils

Helpful methods for manipulating phetioIDs. Used to minimize the amount of duplicated logic specific to the string structure of the phetioID. Available in the main PhET-iO js import.

Members

(static, constant) ARCHETYPE :string

The component name for a dynamic element archetype
Type:
  • string

(static, constant) CAPSULE_SUFFIX :string

The component name suffix for the container (parent) of a dynamic element that doesn't have an '_' in it.
Type:
  • string

(static, constant) COLORS_COMPONENT_NAME :string

The component name for a section that holds colors
Type:
  • string

(static, constant) CONTROLLER_COMPONENT_NAME :string

The component name for an id section that holds controller specific elements.
Type:
  • string

(static, constant) GENERAL_COMPONENT_NAME :string

The component name for the id section that holds phet-io elements general to all simulations.
Type:
  • string

(static, constant) GLOBAL_COMPONENT_NAME :string

The component name for the id section that holds simulation specific elements that don't belong in a screen.
Type:
  • string

(static, constant) GROUP_SEPARATOR :string

The separator used to specify the count of a element in a group.
Type:
  • string

(static, constant) HOME_SCREEN_COMPONENT_NAME :string

The component name for the id section that holds the home screen.
Type:
  • string

(static, constant) INTER_TERM_SEPARATOR :string

The separator used to specify terms in a phetioID that is used by another phetioID. For example: sim.general.view.sim-global-otherID
Type:
  • string

(static, constant) MODEL_COMPONENT_NAME :string

The component name for an id section that holds model specific elements.
Type:
  • string

(static, constant) SEPARATOR :string

The separator used to piece together a phet-io ID.
Type:
  • string

(static, constant) STRINGS_COMPONENT_NAME :string

The component name for a section that holds strings
Type:
  • string

(static, constant) VIEW_COMPONENT_NAME :string

The component name for an id section that holds view specific elements.
Type:
  • string

Methods

(static) append(phetioID, componentNames) → {string}

Appends a component to an existing phetioID to create a new unique phetioID for the component.
Example
append( 'myScreen.myControlPanel', 'myComboBox' )
-->  'myScreen.myControlPanel.myComboBox'
Parameters:
Name Type Description
phetioID string the ID of the PhET-iO Element
componentNames string | Array.<string> the name or list of names to append to the ID
Returns:
- the appended phetioID
Type
string

(static) getArchetypalPhetioID(phetioID) → {string}

Converts a given phetioID to one where all dynamic element terms (i.e. ones with an underscore, like battery_4) are replaced with the term 'archetype'. This helps when looking up the archetype phetioID or metadata for a given dynamic element. Also support INTER_TERM_SEPARATOR delimited parts, like 'sim.screen1.myObject.term1-and-term2-battery_4-term4-etc'. See unit tests and examples in PhetioIDUtilsTests.ts.
Parameters:
Name Type Description
phetioID string
Returns:
Type
string

(static) getComponentName(phetioID) → {string}

Given a phetioID for a PhET-iO Element, get the part of that ID that pertains to the component (basically the tail piece).
Example
getComponentName( 'myScreen.myControlPanel.myComboBox' )
-->  'myComboBox'
Parameters:
Name Type Description
phetioID string the ID of the PhET-iO Element
Returns:
- the component name
Type
string

(static) getDOMElementID(phetioID) → {string}

Deprecated:
  • Yes
Given a phetioID for an instrumented object, get a string that can be used to assign an ID to a DOM element
Parameters:
Name Type Description
phetioID string the ID of the PhET-iO Element
Returns:
Type
string

(static) getGroupElementIndex(componentName) → {number}

Get the index number from the component name of the component name provided.
Example
getGroupElementIndex( 'particle_1' )
--> 1
Parameters:
Name Type Description
componentName string
Returns:
Type
number

(static) getParentID(phetioID) → {string|null}

Given a phetioID for a PhET-iO Element, get the phetioID of the parent component.
Example
getParentID( 'myScreen.myControlPanel.myComboBox' )
-->  'myScreen.myControlPanel'
Parameters:
Name Type Description
phetioID string the ID of the PhET-iO Element
Returns:
- the phetioID of the parent, or null if there is no parent
Type
string | null

(static) getScreenID(phetioID) → {string|null}

Get the screen id from the phetioID.
Example
getScreenID( 'sim.myScreen.model.property' )
--> sim.myScreen
getScreenID( 'sim.myScreen' )
--> sim.myScreen
getScreenID( 'sim.general.activeProperty' )
--> null
Parameters:
Name Type Description
phetioID string
Returns:
- null if there is no screen component name in the phetioID
Type
string | null

(static) isAncestor(potentialAncestorPhetioID, potentialDescendantPhetioID) → {boolean}

Returns true if the potential ancestor is indeed an ancestor of the potential descendant, but not the same phetioID
Parameters:
Name Type Description
potentialAncestorPhetioID string
potentialDescendantPhetioID string
Returns:
Type
boolean