module:bajaux/Properties

new (require("bajaux/Properties"))(objopt)

Description:

The properties for a Widget. These Properties have many uses:
- When embedding a bajaux Widget on a Px page, they will be shown and editable in the Px
  Editor.
- When a Widget is a field editor for a Property on a Niagara Component or Struct, that
  Property's slot facets will be converted into Widget Properties to customize that field
  editor's behavior.
- In your bajaux code, you can apply Properties to your own Widgets to customize their
  behavior any way you like.

Source:

Properties.js, line 268

Examples

Create a Properties instance with an object literal.

var props = new Properties({
  myProp: 'value',
  myHiddenProp: { value: 'hiddenValue', hidden: true }
});
props.getValue('myProp'); // 'value'
props.getValue('myHiddenProp'); // 'hiddenValue'
props.get('myHiddenProp').hidden); // true

Create a Properties instance with an array. Equivalent to the above.

var props = new Properties([
  { name: 'myProp', value: 'value' },
  { name: 'myHiddenProp', value: 'hiddenValue', hidden: true }
]);

Create a Properties instance with a defaultValue for `myProp`.

var props = new Properties([
  { name: 'myProp', value: 'value', defaultValue: 'this is default' },
  { name: 'myHiddenProp', value: 'hiddenValue' }
]);

props.getValue('myProp'); // 'value'
props.getDefaultValue('myProp'); // 'this is default'

props.setValue('myProp', undefined); // make the property value undefined

props.getValue('myProp'); // 'this is default'

props.setValue('myProp', null);
props.getValue('myProp'); // null

props.getValue('propThatDoesNotExist');  // null

Parameters:

Name	Type	Attributes	Description
`obj`	Object \| Array.<module:bajaux/Properties~PropertyDefinition> \| module:bajaux/Properties	<optional>	an initial set of properties with which to initialize this Properties instance. This can be an object literal, an array of object literal Property definitions, or another Properties instance.

Members

toObject

Description:

Convert this Properties instance into a new raw object literal. The object
keys will be the property names, and the values will be the property
values (as returned by #getValue()). Note that any metadata about each
Property will be lost.

This function will be useful for converting Properties into a context
object.

Source:

Properties.js, line 819

Since:

Niagara 4.9 (replaces toValueMap, which still works)

See:

module:bajaux/Properties#toObject

Convert this Properties instance into a new raw object literal. The object
keys will be the property names, and the values will be the property
values (as returned by #getValue()). Note that any metadata about each
Property will be lost.

This function will be useful for converting Properties into a context
object.

Example

Property Sheet converts slot facets into Widget properties. I need to use those facets in my field editor for number formatting purposes.

MyFieldEditor.prototype.numberToString = function (number) {
  var cx = this.properties().toObject();
  if (typeof cx.precision !== 'number') {
    cx.precision = 2;
  }
  return number.toString(cx);
};

Methods

add(prop, valueopt) → {module:bajaux/Properties}

Description:

Add a Property.

Please note, if the Property isn't transient, it's value may be saved and loaded
elsewhere (for example, in the case of Px, reloaded from a Px file).

If the property does not already exist on this Properties instance, this
will emit a PROPERTY_ADDED event, with an array (of length 1) of the
property names added.

As of Niagara 4.14, the property name can also be a Symbol. When the name is a Symbol, the
property is automatically made transient and hidden, and it will not fire added, removed, or
changed events. It will also not be included in iterative functions like .each() and
.get().

Source:

Properties.js, line 397

Examples

Add a Property

  widget.properties().add("foo", true);

Add a hidden Property

  widget.properties().add({
    name: "foo",
    value: true,
    hidden: true
  });

Add a transient, readonly, hidden Property

  widget.properties().add({
    name: "foo",
    value: true,
    hidden: true,
    transient: true,
    readonly: true
  });

Add a Property that maps to the baja:Weekday FrozenEnum in Niagara

  widget.properties().add({
    name: "weekday",
    value: "tuesday",
    typeSpec: "baja:Weekday"
  });

Parameters:

Name	Type	Attributes	Description
`prop`	module:bajaux/Properties~PropertyDefinition \| string		The Property object to be added, or the name of the Property.
`value`	*	<optional>	if passing a string name as the first argument, pass the value here as the second.

Returns:

this Properties instance.

Type: module:bajaux/Properties

addAll(arr) → {module:bajaux/Properties}

Description:

Add a number of properties at once. The object literal configuration
for each property is the same as for add().

Source:

Properties.js, line 409

Parameters:

Name	Type	Description
`arr`	Array.<module:bajaux/Properties~PropertyDefinition> \| module:bajaux/Properties	an array of property definitions, or a `Properties` instance to copy onto this one

Returns:

this Properties instance.

Type: module:bajaux/Properties

clone() → {module:bajaux/Properties}

Description:

Return a clone of this Properties object that can be modified without
changing the original.

Source:

Properties.js, line 941

Returns:

Type: module:bajaux/Properties

each(func) → {module:bajaux/Properties}

Description:

Iterate through each Property.

Source:

Properties.js, line 905

Parameters:

Name	Type	Description
`func`	function	The function to be called for each Property found in the array. This function will have the index, name and value of the Property passed to it. The Context of the function callback will be the Properties instance.

Returns:

this Properties instance.

Type: module:bajaux/Properties

get(nameopt, attrNameopt, defAttrValueopt) → {module:bajaux/Properties~PropertyDefinition|*|null|Array.<module:bajaux/Properties~PropertyDefinition>}

Description:

If no arguments are specified, a copy of the internal Properties array will be returned.
If only the name is specified, return a copy of the Property for the given name or index.
If a name/index and an attribute name is specified, then return the attribute of a Property.
If no particular value can be found then return null;

Source:

Properties.js, line 856

Parameters:

Name	Type	Attributes	Description
`name`	String \| Number \| Symbol	<optional>	The identifier or index of the Property to look up. If not specified, a copy of the internal Property array will be returned.
`attrName`	String	<optional>	If specified, this will retrieve a specific attribute of the Property. For example, specifying 'value' will get the value of the Property.
`defAttrValue`		<optional>	If specified, this value will be returned if the attribute name can't be found.

Returns:

A copy of the Property definition;
the attribute value if requested; or null if the specified Property can't be found; or if no
name specified, an array of all property definitions.

Type: module:bajaux/Properties~PropertyDefinition | * | null | Array.<module:bajaux/Properties~PropertyDefinition>

getDefaultValue(nameopt) → {*|null}

Description:

If a name/index is specified then return a Property's default value or null if nothing can be found.
If no name is specified then return an object containing all the Property names and default values.

Source:

Properties.js, line 545

Parameters:

Name	Type	Attributes	Description
`name`	String \| Number	<optional>	If specified, the name of the Property to return or the Property's index. If this parameter is not specified, an object containing all the property default values will be returned.

Returns:

The Property's default value or null if nothing is found.

Type: * | null

getIndex(name) → {Number}

Description:

Return a Property's index via its name or -1 if it can't be found.

Source:

Properties.js, line 740

Parameters:

Name	Type	Description
`name`	String	The name of the Property to look up the index number for.

Returns:

Returns the index number of the Property.

Type: Number

getMetadata(name) → {Object}

Description:

Return the corresponding metadata object literal for the Property

Source:

Properties.js, line 892

Parameters:

Name	Type	Description
`name`	String \| Number \| Symbol	The identifier or index of the Property to look up.

Returns:

The metadata object literal, or an empty object if the Property could not be found

Type: Object

getValue(nameopt, defValopt) → {*|null}

Description:

If no name is specified then return an object containing all the Property names and values.
If a name/index is specified then return a Property's value or null if nothing can be found.

Property values will fall back to defaultValue if value is not set.

Source:

Properties.js, line 507

Parameters:

Name	Type	Attributes	Description
`name`	String \| Number	<optional>	If specified, the name of the Property to return or the Property's index. If this parameter is not specified, an object literal containing all the property values will be returned (same as `.toObject()`).
`defVal`		<optional>	If specified, this will return if a value can't be found providing the first argument is a String. This will override the defaultValue for the given property.

Returns:

The Property value, Property default value, or null if nothing is found.

Type: * | null

has(name) → {Boolean}

Description:

Return true if the Property can be found via its name or index.

Source:

Properties.js, line 481

Parameters:

Name	Type	Description
`name`	String \| Number \| Symbol	The identifier or index of the Property to look up.

Returns:

true if the Property is found.

Type: Boolean

off(name, funcopt) → {module:bajaux/Properties}

Description:

Called to detach any event handlers from a Property or to
stop listening to all Property change events.

Source:

Properties.js, line 725

Parameters:

Name	Type	Attributes	Description
`name`	String		The Property name to remove.
`func`	function	<optional>	The event handler to remove.

Returns:

The Properties instance.

Type: module:bajaux/Properties

remove(name) → {module:bajaux/Properties}

Description:

Remove a Property.

Source:

Properties.js, line 446

Parameters:

Name	Type	Description
`name`	String	The name of the Property to remove.

Returns:

this Properties instance.

Type: module:bajaux/Properties

setMetadata(name, metadata, optionsopt) → {Boolean}

Description:

If an object is specified as the first argument, it will be iterated
through with object's properties being set as metadata

If a name/index is specified along with a value, the metadata for the
particular name/index will be set.

Source:

Properties.js, line 713

Since:

Niagara 4.4

Parameters:

Name	Type	Attributes	Description
`name`	String \| Object		The name of the Property we're going to set or a an object containing several metadata values to be set. The value for each property name in the object will be set as corresponding metadata for that property
`metadata`	Object		The metadata to be set.
`options`		<optional>	An optional parameter that is passed down into any changed callbacks or event handlers.

Returns:

Return false if at least one of the properties wasn't found.

Type: Boolean

setValue(name, value, optionsopt) → {Boolean}

Description:

If an object is specified as the first argument, it will be iterated
through with object's properties being set as values.

If a name/index is specified along with a value, the value for the
particular value will be set.

A Widget can detect Property changes by implemented a method called
changed. The changed call back will have the Property name and new value
passed to it. A developer can then override 'doChanged' to handle any
callbacks in their own widget subclasses.

Source:

Properties.js, line 693

Parameters:

Name	Type	Attributes	Description
`name`	String \| Object		The name of the Property we're going to set or a an object containing many values to be set.
`value`			The value to be set.
`options`		<optional>	An optional parameter that is passed down into any changed callbacks or event handlers.

Returns:

Return false if at least one of the properties wasn't found.

Type: Boolean

size() → {Number}

Description:

Return the total number of Properties.

Source:

Properties.js, line 490

Returns:

returns the total number of Properties.

Type: Number

subset(keys) → {module:bajaux/Properties}

Description:

Build a new Properties instance consisting of a subset of the properties
contained within this one. Useful for propagating a specific set of
properties down to a child widget.

Source:

Properties.js, line 927

Example

props.subset([ 'prop1', 'prop2', 'prop3' ]);
props.subset('prop1', 'prop2', 'prop3');

Parameters:

Name	Type	Description
`keys`	Array.<(string\|number\|Symbol)>	which keys to include in the subset. These can also be passed as individual varargs.

Returns:

Type: module:bajaux/Properties

toDisplayName(name) → {Promise}

Description:

Return a promise that will resolve once the display name of the Property
has been resolved.

If the Property doesn't have a display name, the Property's name will
be used instead.

Please note, a display name can be in the format of a Lexicon format. For instance,
%lexicon(moduleName:keyName)%.

Starting in Niagara 4.15, if no displayName is provided, but a moduleName is provided,
the name will be used as a key to look for a lexicon entry in the that module's lexicon.
If no lexicon entry is present, the toFriendly String will be provided.

Source:

Properties.js, line 769

Parameters:

Name	Type	Description
`name`	String \| Number	The name or index of the Property.

Returns:

The display name of the Property.

Type: Promise

(static) extend() → {module:bajaux/Properties}

Description:

Create a new Properties instance containing the merged properties of
one or more other Properties instances. Properties of instances later in
the argument list will override properties of earlier instances.

Each argument can be of any type acceptable to the Properties constructor
(Object, Array, or Properties).

Source:

Properties.js, line 316

Example

var mergedProps = Properties.extend(
  { myProp: 'a' },
  new Properties({ myProp: { value: 'a2', hidden: true } })
);
mergedProps.getValue('myProp'); // 'a2'
mergedProps.get('myProp').hidden; // true

Returns:

Type: module:bajaux/Properties