module:bajaux/Properties

module:bajaux/Properties

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

Description:

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

Source:
Mixes In:
  • tinyevents
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.<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.

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; to preserve metadata, use toObject().

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

Source:
Since:
  • Niagara 4.9 (replaces toValueMap, which still works)
See:

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; to preserve metadata, use toObject().

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

Source:
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 String | Object

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

Properties
Name Type Attributes 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)%.
transient 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.
value * <optional>

if passing a string name as the first argument, pass the
value here as the second.
Returns:

returns the 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:
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
module:bajaux/Properties

clone() → {module:bajaux/Properties}

Description:

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

Source:
Returns:
Type
module:bajaux/Properties

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

Description:

  • Iterate through each Property.

Source:
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
module:bajaux/Properties

get(nameopt, attrNameopt, defAttrValueopt) → {Object}

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

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:
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 of the property default values will be returned.
Returns:

The Properties 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:
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(nameopt) → {Object}

Description:

  • 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

Source:
Parameters:
Name Type Attributes 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(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 fallback to defaultValue if value is not set.

Source:
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 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. This will override the defaultValue for the given property.
Returns:

The Properties value or null if nothing is found.

Type
* | null

has(name) → {Boolean}

Description:

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

Source:
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, funcopt) → {module:bajaux/Properties}

Description:

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

Source:
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:
Parameters:
Name Type Description
name String

The name of the Property to remove.
Returns:

returns the 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:
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:
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:
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:
Parameters:
Name Type Description
keys Array.<String>

which keys to include in the subset.
Returns:
Type
module:bajaux/Properties

toDisplayName(name)

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

Source:
Parameters:
Name Type Description
name String | Number

The name or index of the Property.
Returns:

The display name of the Property.

(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:
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