API Docs

Class: ParamGroup

PD. ParamGroup

Defines a group of dynamic parameters.

How parameter groups are displayed is up to each UI framework. However, each group in a list is typically displayed as a separate folding section within a much larger area of the interface. If title of the parameter group is empty, the parameter items in it are not wrapped within a folding section but are displayed in an untitled and unwrapped section.

new ParamGroup( [config])

Creates a new dynamic parameter group.

Parameters:
Name Type Argument Description
config object <optional>

A configuration object.
Properties of config:
Name Type Argument Description
name string <optional>

The name for the parameter group.
title string <optional>

The human-readable title to show above these parameters.
target object <optional>

The object containing the properties for these parameters.
callback function <optional>

A callback function invoked whenever any of the parameter values in this group change.
enabled Array <optional>

Whether or not the parameters in this group are active.
closed Array <optional>

Whether or not the group is initially closed in the UI.
params Array <optional>

An array of parameters to add to this group.
Author:
  • drajmarsh

Members

:function

callback

A callback function invoked whenever any of the parameter values in this group change.

Type
  • function
:boolean

closed

Whether or not this group is initially closed when shown in the UI.

Type
  • boolean
:boolean

enabled

Whether or not this group is enabled.

Type
  • boolean
:string

id

A unique identifier for use in the DOM.

Type
  • string
:boolean

isParamGroup <readonly>

A flag identifying this object as a parameter group.

Type
  • boolean
:number

key

An optional key used to manually update group parameter values.

Type
  • number
:string

name

A unique name for this parameter group.

Type
  • string
:Array

params

A list of dynamic parameters in this group.

Type
  • Array
:string

title

The human-readable title for the group.

Type
  • string

Methods

getParameter(name)

Returns the first parameter in this group with a matching name.

If you only want the value of the parameter, you can use the getParameterValue() method instead.

Parameters:
Name Type Description
name string

The name of the parameter to find.
Returns:

Returns the matching parameter or null.

Type
PD.Parameter | null

getParameterArrayIndex(name)

Returns the index of the first parameter with a matching name.

You can use this method to find the array index of a known parent class parameter in the group params array, and then splice in another parameter at the right index, regardless of whether other parameters have been added or removed.

Parameters:
Name Type Description
name string

The name of the parameter to find.
Returns:

Returns the index pof the parameter, or -1 if not found.

Type
number

getParameterValue(name)

Returns the value of the first parameter with a matching name.

If you want to access the parameter itself, you can use the getParameter() method instead.

Parameters:
Name Type Description
name string

The name of the parameter to find.
Returns:

Returns the parameter value or null.

Type
any | null

getTarget()

Retrieve the object with the properties set by this group's parameters.

Returns:

Returns the target object or null.

Type
object | null

setParameterProperties(name, props)

Sets a property value on the first parameter with a matching name.

NOTE: The props argument is expected to be a Plain Old Javascript Object (POJO) rather than a more complex object with multiple inherited properties. This is because it uses props.hasOwnProperty(key) to filter out any extraneous properties inherited from the base object class, etc.

Also, this method will only set the property value if a property with that name already exists in the parameter. It will not add new properties.

Parameters:
Name Type Description
name string

The name of the parameter to find.
props object

A POJO with the properties and values to set.
Returns:

Returns true if a parameter was found and at least one property was set.

Type
boolean

setParameterProperty(name, key, value)

Sets a property value on the first parameter with a matching name.

NOTE: This method will only set the property value if a property with that name already exists in the object. It will not add new properties.

Parameters:
Name Type Description
name string

The name of the parameter to find.
key string

The name of the property to set the value of.
value any

The new value of the property if parameter is found.
Returns:

Returns true if a parameter was found and the property value set.

Type
boolean

setParameterValue(name, value)

Set the value of the first parameter with a matching name.

Parameters:
Name Type Description
name string

The name of the parameter to find.
value any

The value to set if a parameter is found.
Returns:

Returns true if a parameter was found and its value set.

Type
boolean

setTarget(target)

The object with the properties set by group's parameters.

Parameters, ParamTypes and ParamGroups are all exposed directly to whatever front-end framework is being used and may be proxied or made reactive in order to dynamically update the model and UI. However, the target object is very likely to be a complex BIM element or component, so we really don't want any reactivity inadvertently 'leaking' into the model. Storing the object reference in a simple object and then freezing it gives some reasonable protections against this.

Parameters:
Name Type Description
target object | null

The new target element/component.
Returns:

Returns this group to support method chaining.

Type
PD.ParamGroup

updateParameter(name)

Refreshes the value of the first parameter matching the given name using a property with the same name on the target object.

Parameters:
Name Type Description
name string

The name of the parameter to find.
Returns:

Returns true if a matching property was found and updated.

Type
boolean

updateParameterValues()

Refreshes the values of each parameter in the group to their current values on the target object.

Returns:

Returns true if any parameter was found and updated.

Type
boolean