option.Manager

Extends IOptionManager.

Options manager. For setting and getting option values by a string key, as well as allowing option values in the context of the existing hierarchy of options managers.

The special "preset" key is for making a set of options by default for this manager. The value of the "preset" option can be a hash with the format {"option name": "option value"}, or a string ID for a hash of options in the option.presetStorage storage. This hash of options can also contain a field named "preset", which allows for inheritance of option values from other sets of options.

When searching for values in the hierarchy, first the options themselves are checked, then the options set using the "preset" key, and after that the parent is accessed, if there is one.

To track changes to certain options, you can use Monitor.

Constructor | Fields | Events | Methods

Constructor

option.Manager([options[, parent[, name]]])

Creates an options manager.

Parameters:

Parameter

Default value

Description

options

Type: Object

Hash of options.

parent

Type: IOptionManager

Parent options manager.

name

Type: String

Name of the options manager.

Examples:

1.

// Example of building a hierarchy of options managers.
var parentManager = new ymaps.option.Manager({
    key1: '123'
});
var childManager = new ymaps.option.Manager({
    key2: '234'
}, parentManager);
// Outputs 123. The value is taken from manager1.
alert(childManager.get('key1'));
// Outputs 234. The value is taken from manager2.
alert(childManager.get('key2'));
// Overriding the option.
childManager.set('key1', '345');
// Outputs 345. The value is taken from manager2.
alert(childManager.get('key1'));
// Outputs 123. The value is taken from manager1.
alert(parentManager.get('key1'));

2.

// Example using the "preset" option.
var optionManager = new ymaps.option.Manager({
    preset: 'islands#blueIcon'
});
var subOptionManager = new ymaps.option.Manager();
// There is no data, because subOptionManager is empty.
alert(subOptionManager.get('iconImageSize');
// Binding two managers.
subOptionManager.setParent(optionManager);
// [37, 42] - value is taken from the preset in the parent manager.
alert(subOptionManager.get('iconImageSize');
// Overriding the value of iconImageSize on the level of subOptionManager.
subOptionManager.set('iconImageSize', [10, 12]);
// [10, 12] - value is taken from subOptionManager.
alert(subOptionManager.get('iconImageSize');
// Canceling the override of iconImageSize.
subOptionManager.unset('iconImageSize');
// [37, 42] - value is again taken from the preset in the parent manager.
alert(subOptionManager.get('iconImageSize'));

Fields

Name

Type

Description

events

IEventManager

Event manager for the object.

Inherited from IFreezable.

Events

Name

Description

change

Changes occurred either in the options values, or in the options inheritance hierarchy. Instance of the Event class.

parentchange

The parent object reference changed.

Data fields:

  • oldParent - Old parent.
  • newParent - New parent.

Inherited from IChild.

Methods

Name

Returns

Description

freeze()

IFreezable

Switches the object to "frozen" mode.

Inherited from IFreezable.

get(key[, defaultValue])

Returns the value of the specified option in the context of the existing options inheritance hierarchy. When this method is called, first values are searched for in the current options manager, then, if the value is not defined, the search continues in the hierarchy of parent managers.

Inherited from IOptionManager.

getAll()

Object

Returns a reference to the internal hash that stores option values.

Inherited from IOptionManager.

getName()

String

Returns name of the options manager.

Inherited from IOptionManager.

getNative(key)

Object

Returns the value of the specified option that is defined for the given level of the options hierarchy, i.e. in this manager.

Inherited from IOptionManager.

getParent()

IOptionManager|null

Returns parent options manager.

Inherited from IOptionManager.

isFrozen()

Boolean

Returns true if the object is in "frozen" mode, otherwise false.

Inherited from IFreezable.

resolve(key[, name])

Object

Method intended to be called by child options managers.

Inherited from IOptionManager.

set(key[, value])

option.Manager

Sets option values for this manager. Two signatures are supported:

  • A single argument consisting of a hash in the format {"option name": "option value"}.
  • Two arguments, the first of which is the option name, and the second is the value.

setName(name)

Sets the name of the options manager.

Inherited from IOptionManager.

setParent(parent)

IChild

Sets the parent options manager.

Inherited from IOptionManager.

unfreeze()

IFreezable

Switches the object to active mode.

Inherited from IFreezable.

unset(keys)

option.Manager

Clears the values for the set options in this manager.

unsetAll()

option.Manager

Clears the values for all options in this manager.

Events details

change

Changes occurred either in the options values, or in the options inheritance hierarchy. Instance of the Event class.

Methods details

set

{option.Manager} set(key[, value])

Sets option values for this manager. Two signatures are supported:

  • A single argument consisting of a hash in the format {"option name": "option value"}.
  • Two arguments, the first of which is the option name, and the second is the value.

Returns self-reference.

Parameters:

Parameter

Default value

Description

key*

Type: Object|String

The option name, or a hash in the format {"option name": "option value"}.

value

Type: Object

The option value, if the name was passed as the first argument.

* Mandatory parameter/option.

Examples:

1.

// Setting multiple options via hash.
myMap.options.set({
    dblClickZoomCentering: true,
    dblClickFloatZoom: true
});
// Generates a single event option.Manager.event:change.

2.

// Setting options separately.
myMap.options
    .set("dblClickZoomCentering", true)
    .set("dblClickFloatZoom", true);
// Gernerates the event option.Manager.event:change.

3.

// Using "freeze" to minimize the number of option.Manager.event:change events.
myMap.options.freeze();
myMap.options.set({
    dblClickZoomCentering: true,
    dblClickFloatZoom: true
});
myMap.options.set('cursor', 'zoom');
myMap.unfreeze();
// Generates a single option.Manager.event:change event.

unset

{option.Manager} unset(keys)

Clears the values for the set options in this manager.

Returns self-reference.

Parameters:

Parameter

Default value

Description

keys*

Type: String|String[]

Option name or array of option names whose values should be canceled.

* Mandatory parameter/option.

Example:

map.options.unset(['dblClickZoomCentering', 'dblClickFloatZoom']);

unsetAll

{option.Manager} unsetAll()

Clears the values for all options in this manager.

Returns self-reference.

Example:

var geoObject = new ymaps.Placemark([37, 55], {}, {preset:'islands#blueIcon'});
myMap.geoObjects.add(geoObject);
// Changing the style however we want.
geoObject.options.set({
    iconLayout: 'default#image',
    iconImageHref: 'http://mysite.ru/icon.png',
    iconImageSize: [16, 16]
});
// Restoring the initial appearance.
geoObject.options
    // To avoid a double reaction of the geo object
    // to the option changes, first we call "freeze", then after
    // setting all values, we call "unfreeze".
    .freeze()
    .unsetAll()
    .set('preset','islands#blueIcon')
    .unfreeze();