Module: bajaux/Properties

Configurable Properties for Widgets.


new (require("bajaux/Properties"))( [obj])

The properties for a Widget. This are configurable properties
that can be configured by a user.

Parameters:
Name Type Argument Description
obj Object | Array.<Object> | 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 literals, or another
Properties instance.

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 }
]);

Requires

Methods


<static> extend()

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).

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

add(prop)

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.

Parameters:
Name Type Description
prop Object

The Property object to be added or the name of the Property.

Properties
Name Type Argument Description
name String | Object

The name of the Property being added or if the first argument
is a String, this is the value.

value

The current value of the Property.

displayName String <optional>

The display name of the Property. For translated values,
this can be a format string. For example, %lexicon(moduleName:keyName)%.

trans Boolean <optional>

A hint to an external editor that it doesn't need to save
the state of this Property.

hidden Boolean <optional>

A hint to an external editor to hide this Property.

readonly Boolean <optional>

A hint to an external editor to make the editor for
this Property readonly.

typeSpec Boolean <optional>

A hint to Niagara on what Simple Niagara Type to use when
encoding/decoding the Property. If the Type is a FrozenEnum, the tag name of the Enum
should be used.

Returns:

returns the Properties instance.

Type
Properties
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,
    trans: 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"
  });

addAll(arr)

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

Parameters:
Name Type Description
arr Array.<Object> | module:bajaux/Properties

an array of object
literals to become properties, or a Properties instance to copy onto this
one

Returns:

this

Type
Properties

clone()

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

Returns:
Type
Properties

each(func)

Iterate through each Property.

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. If iteration needs to stop prematurely then
the function can return false.

Returns:

Returns the Properties instance.

Type
Properties

get( [name] [, attrName] [, defAttrValue])

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;

Parameters:
Name Type Argument Description
name String | Number <optional>

The name 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 object or null if the Property can't be found.

Type
Object

getIndex(name)

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

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])

If no arguments are specified, a copy of the internal Properties array will be returned.
If only the name is specified, return a the corresponding meta data object literal for the Property

Parameters:
Name Type Argument Description
name String | Number <optional>

The name or index of the Property to look up. If not
specified, a copy of the internal Property array will be returned.

Returns:

The meta data object literal or null if the Property could not be found

Type
Object

getValue( [name] [, defVal])

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.

Parameters:
Name Type Argument 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 of the property values will be returned.

defVal <optional>

If specified, this will return if a value can't be found providing the first argument is
a String.

Returns:

The Properties value or null if nothing is found.

Type
* | null

has(name)

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

Parameters:
Name Type Description
name String | Number

The name or index of the Property to look up.

Returns:

returns true if the Property is found.

Type
Boolean

off(name [, func])

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

Parameters:
Name Type Argument Description
name String

The Property name to remove.

func function <optional>

The event handler to remove.

Returns:

The Properties instance.

Type
Properties

remove(name)

Remove a Property.

Parameters:
Name Type Description
name String

The name of the Property to remove.

Returns:

returns the Properties instance.

Type
Properties

setMetadata(name, metadata [, options])

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.

Parameters:
Name Type Argument 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.

Since:
  • Niagara 4.4
Returns:

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

Type
Boolean

setValue(name, value [, options])

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.

Parameters:
Name Type Argument 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()

Return the total number of Properties.

Returns:

returns the total number of Properties.

Type
Number

subset(keys)

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.

Parameters:
Name Type Description
keys Array.<String>

which keys to include in the subset.

Returns:
Type
Properties

toDisplayName(name)

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)%.

Parameters:
Name Type Description
name String | Number

The name or index of the Property.

Returns:

The display name of the Property.


toValueMap()

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()).

Returns:
Type
Object