Набор утилит-классов для виджета(1. Attribute)

Attribute --  эта утилита служит, для предоставлению классу функционала по добавлению в него атрибутов, что в себе несет гетер/сетер для атрибута, валидатор, возможность создавать слушателей, которые реагируют на изменение атрибута.

Для того чтобы применить этот функционал к своему классу его нужно расширить by Y.augment() атрибутом.


Атрибуты добавляются двумя методами:

addAttr
addAttrs - этот хорош тем, что кроме добавления несколько атрибутов одновременно, мы можем вторым параметром проинициализировать их. Значения инициализации передаются в конструтор по именам атрибутов, смотреть пример ниже:

function MyClass(userValues) {
 
    // Use addAttrs, to setup default attributes for
    // your class, and mixing in user provided initial values.
 
    var attributeConfig = {
        attrA : {
            // ... Configuration for attribute "attrA" ...
        },
 
        attrB : {
            // ... Configuration for attribute "attrB" ...
        } 
    };
 
    this.addAttrs(attributeConfig, userValues);
};
Y.augment(MyClass, Y.Attribute);

// Set initial value for attrA during instantiation
var o = new MyClass({
    attrA:5
}); 
// Set attrB later on
o.set("attrB", "Hello World!");

А вот так работает addAttr:

this.addAttr("attrA", {
    // Configuration for attribute "attrA"
 
    value: 5,
 
    setter: function(val) {
        return Math.min(val, 10); 
    },
 
    validator: function(val) {
        return Y.Lang.isNumber(val);
    }
});

Таблица возможных настроек атрибута:

Property Name	Type	Description
value	Any	Значение по-умолчанию.
valueFn	Function	Функция которая должна вернуть значение по умолчанию. Эта функция может предоставлять значения основываясь на каком-нибудь состоянии обьекта. Поэтому я думаю эта настройка вставляется не в контрукторе класса, а при добавлении ему атрибута со временем. Если определена эта функция и value, то приоритет имеет она.
getter	Function	Эта функция возвращает результат для геттера(myClass.get('attrA')). Имеет два аргумента: 1) Значение атрибута; 2) Имя атрибута. Значние внутри мы можем подизменить.
setter	Function	Эта возвращает результат для сетера. Два аргумента: 1) переданное в сетер значение; 2) имя атрибута.
validator	Function	Функция для валидации имеет два аргумента таких как в кастомном обработчике сетера. Вызывается до сетера, если вернет фолс, то сетер не будет вызван. Если валидация сильно дорогая, и в сетере нужно выполнять те же дорогие действия, то можно сделать валидацию в самом сетере и если что не так, то вернуть Attribute.INVALID_VALUE
readOnly	boolean	Если флаг вкулючен, то паблик сетер не будет работать. Можно будет менять атрибут только через приватный сетер внутри обьекта.
writeOnce	boolean or "initOnly"	Если включен флаг, то можно записать публичным сетером только раз значение, если флаг "initOnly", то значение можно записать только при создание екземпляра класса, передав параметр в контсруктор.
broadcast	int	По-умолчанию вещание события изменения аргумента не идет на юай обьект и тем-более во все сендбоксы. Но можно поставить, чтобы вещало как на юай, так и на все сендбоксы юая на странице. See CustomEvent's broadcast property for valid values.
lazyAdd	boolean	Если в тру, то инициализация аргумента происходит только перед первым обращением на атрибут. В классе Base(он влючил в себя аргумент) все атрибуты имеют этот флаг включенным.
cloneDefaultValue	"shallow", "deep", true, false	В классе Атрибут этой настройки нет. Но она есть в Base, и определяет как клонировать/копировать обьекты которые инициализируют аргументы через статический аргумента класса Base ATTRS: 1 - только первого уровня обьекты будут клонированы все остальные будут переданны в клоны по ссылке; 2=3 - клонирована будет вся иерархия обьектов; 4 - будет сохранено по ссылке.

Уставливаем мы атрибуты методом set, при этом этот тарибут не сработает, если у нас только ридонли или райтванс стоит. Но мы всегда можем вызвать метод _set(который вызывается внутри set), таким образом игнорируя любые настройки аргумента, поменяв его значения. В юае много таким псевдо протектид методов, они имеют только такую декларацию, но не являются такимим по сути).

События изменения атрибутов
Возможность для обьекта стать источником события(fire) представляет класс Y.TargetEvent. Он также в себе реализует все событийные методы after, before, on, bubble и другие. Этот класс и используется внутри класса Attribute.
По названим понятно что preventDefault не даст измениться атрибуту только в реакциях присоединенных в before и on, в after будет уже поздно.

Y.TargetEvent передает в обработчик ивентфасад, которые содержит следующие свойства/методы:

- newVal

- prevVal

- attrName

- subAttrName

For example, during o.set("X.a.b", 5);, event.subAttrName will be "X.a.b", the path of the property which was modified, and event.attrName will be "X", the attribute name.

- preventDefault()

- stopImmediatePropagation()

 

Понятное дело свойство не обязано быть только простым типом, оно может быть и обьектом:

o.set("strings", {
    ui : {
        accept_label : "OK",
        decline_label : "Cancel",
    },
    errors : {
        e1000 : "Not Supported",
        e1001 : "Network Error"
    }
});

// Set existing properties
o.set("strings.ui.accept_label", "Yes");
o.set("strings.ui.decline_label", "No");
 
// Add a new property
o.set("strings.errors.e2000", "New Error");
 
// Cannot set new intermediate properties:
// "strings.messages" does not exist so can't set
// "strings.messages.intro"
o.set("strings.messages.intro", "Welcome");

// Get the string for the accept label
var lbl = o.get("strings.ui.accept_label");