Seemple#bindNode - это единственный метод класса Seemple, отвечающий за изменения DOM. Он создаёт мост между значением свойства и состоянием HTML элемента на странице: от простого инпута до сложного виджета (сложность элементов не ограничена). После связывания свойства экземпляра и HTML элемента не нужно больше следить за синхронизацией данных и представления.

Обратите внимание, что у метода есть статичный аналог, который работает в точности так же, но принимает любой целевой объект в качестве первого аргумента, cдвигая остальные аргументы вправо.

const bindNode = require('seemple/bindnode');
const object = {};
bindNode(object, key, node, binder, eventOptions);
// вместо this.bindNode(key, node, binder, eventOptions);

Для двустороннего связывания элемента и значения свойства, в метод передаются три аргумента: имя свойства, HTML элемент и правило привязки (байндер, биндер, binder, привязчик). Байндер, в свою очередь, является обычным объектом и может иметь следующие свойства: on, getValue, setValue, initialize, destroy (подробнее см. binder). Все пять свойств опциональны. Это позволяет также объявлять и односторонние привязки.

Метод bindNode поддерживает привязки "многие ко многим". С одним свойством можно связать несколько элементов, а с одним элементом можно связать несколько свойств, в том числе и от разных экземпляров разных классов.

this.bindNode('myKey', '.my-element', {
    on: 'click',
    getValue() { ... },
    setValue() { ... }
});

Например, вы хотите связать свойство объекта с элементом input[type="checkbox"]:

this.bindNode('myKey', '.my-checkbox', {
    // когда менятся состояние элемента?
    // - по событию 'click'
    on: 'click',
    // как извлечь состояние элемента?
    // - вернуть значение 'checked'
    getValue() {
        return this.checked;
    },
    // как установить состояние элемента?
    // - установить значение 'checked'
    setValue(v) {
        this.checked = !!v;
    }
});

После объявления привязки можно устанавливать значение свойства объекта самым привычным способом, а элемент изменит своё состояние автоматически. При клике на чекбокс, значение свойства тоже изменится на соответствующее.

// устанавливает checked = true
this.myKey = true;

Более сложный пример: связывание свойства объекта с виджетом jQuery UI

<div class="my-slider"></div>

this.bindNode('myKey', '.my-slider', {
    // когда менятся состояние элемента?
    // - по событию 'slide'
    on: 'slide',
    // как извлечь состояние элемента?
    // - вернуть значение виджета 'value'
    getValue() {
        return $(this).slider('option', 'value');
    },
    // как установить состояние элемента?
    // - установить значение 'value'
    setValue(v) {
        $(this).slider('option', 'value', v);
    },
    // как инициализировать виджет?
    // инициализировать слайдер можно любым способом,
    // но initialize предоставляет немного синтаксического сахара
    initialize() {
        $(this).slider({ min: 0, max: 100 });
    }
});

// установит знaчeние слайдера 42
this.myKey = 42;

Выглядит просто, но вы, скорее всего, задаётесь вопросом: "Как сделать так, чтоб мне не пришлось каждый раз прописывать эти правила?". Действительно, на странице может быть очень много однотипных элементов: текстовых полей, выпадающих меню, новых полей из спецификации HTML5, могут быть и сторонние виджеты (о чем говорит пример выше).

Как видно из документации к аргументам метода bindNode, третий аргумент не обязателен. Этот вопрос решает массив Seemple.defaultBinders, который содержит функции, проверяющие HTML элемент на соответствие заданным правилам и возвращающие соответствующий байндер или undefined. Появляется возможность многократно сократить код, вынося правила привязки в отдельную часть вашего кода, а для привязки использовать синтаксис без третьего аргумента:

this.bindNode('myKey', '.my-element');

Как это сделать? Нужно добавить функцию, проверяющую ваш элемент на соответствие некоторым правилам в начало массива Seemple.defaultBinders.

const checkboxBinder = () => {
    return {
        on: 'click',
        getValue() {
            return this.checked;
        },
        setValue(v) {
            this.checked = !!v;
        }
    }
};

// метод unshift добавляет функцию
// в начало массива Seemple.defaultBinders
Seemple.defaultBinders.unshift(node => {
    // проверяем, является ли элемент чекбоксом
    if(node.tagName === 'INPUT' && node.type === 'checkbox') {
        // если проверка пройдена, возвращаем новый байндер
        return checkboxBinder();
    }
});

this.bindNode('myKey', '.my-checkbox');
this.myKey = true;

Что делать, если вам нужно передать аргументы для инициализации какого-нибудь плагина или виджета? Можно вручную вызывать функцию, возвращающую байндер.

const uiSlider = (min, max) => {
    return {
        on: 'slide',
        getValue() {
            return $(this).slider('option', 'value');
        },
        setValue(v) {
            $(this).slider('option', 'value', v);
        },
        initialize() {
            $(this).slider({ min: min, max: max });
        }
    }
};

this.bindNode('myKey1', '.my-slider1', uiSlider(0, 100));
this.bindNode('myKey2', '.my-slider2', uiSlider(1, 1000));
this.myKey1 = 42;
this.myKey2 = 999;

Для глобального доступа к байндеру, можно расширить Seemple.binders.

Seemple.binders.uiSlider = uiSlider;
// ...
this.bindNode('myKey1', '.my-slider1', Seemple.binders.uiSlider(0, 100));
this.bindNode('myKey2', '.my-slider2', Seemple.binders.uiSlider(1, 1000));

Seemple.defaultBinders из коробки содержит поддержку всех без исключения HTML элементов форм: select (включая multiple), textarea, output, input (в том числе и все типы из спецификации HTML5: text, checkbox, radio, range, number, date, search, time, datetime, datetime-local, color и остальных). Это значит, что для стандартных элементов указывать байндер не обязательно.

<input type="color" class="my-color-input">

this.bindNode('myColor', '.my-color-input');
this.myColor = '#66bb6a';

После привязки, вам доступен новый нестандартный CSS селектор :bound(KEY).

this.bindNode('myKey', '.my-element');

// найдет элемент '.my-inner-element' внутри '.my-element'
this.bindNode('myAnotherKey', ':bound(myKey) .my-inner-element');

И расширяется синтаксис возможных имен событий:

this.bindNode('myKey', '.my-element');

// отловит клик на элементе .my-element
this.on('click::myKey', () => { ... });

// отловит клик на элементе .my-element .my-inner-element
this.on('click::myKey(.my-inner-element)', () => { ... });

Если элемент не найден, бросается исключение "Bound element is missing". Для того, чтоб избежать ошибки используйте метод Seemple#bindOptionalNode

Создание песочницы

Seemple#bindNode умеет ассоциировать экземпляр класса с "главным" HTML элементом, создавая так называемую песочницу. Это нужно для того, чтоб ограничить влияние объекта одним HTML элементом. Для привязки песочницы используется специальное свойство sandbox.

<div class="my-sandbox">
    <!-- your HTML code -->
</div>

this.bindNode('sandbox', '.my-sandbox');

Определение песочницы добавляет множество удобств программисту. Например:

• Позволяет использовать методы Seemple#select и Seemple#$
• Добавляет новый селектор :sandbox в методах Seemple#bindNode, Seemple#select, Seemple#$
• Добавляет синтаксический сахар для делегированных DOM событий в методе Seemple#on

Следует иметь в виду, что только один HTML элемент может быть связан со свойством sandbox, иначе бросается ошибка. Для объявления песочницы можно воспользоваться методом Seemple#bindSandbox. Перед тем, как объявить байндинг, метод отвязывает предыдущую песочницу.

// объявляем песочницу
this.bindNode('sandbox', '.my-sandbox');

// .my-element ищется в песочнице
this.bindNode('myKey', ':sandbox .my-element');

// для делегированных событий внутри песочницы не требуется указывать ключ
this.on('click::(.my-button)', () => { ... });

// выведет в консоль элемент .inner-node,
// который находится внутри песочницы
console.log(this.$('.inner-node'));

Важные особенности работы метода и специальные флаги

Четвертым аргументом eventOptions в метод bindNode можно передать объект, состоящий из флагов, описанных ниже, глобальных флагов (например, silent), или кастомных данных, которые попадут в обработчики событий bind и bind:KEY.

this.on('bind:x', evt => {
    console.log(evt.foo); // bar
});
this.bindNode('x', node, binder, { foo: 'bar' });

Для ознакомления с важными тонкостями работы bindNode информация ниже обязательна к ознакомлению. При этом, имена флагов запоминать не обязательно.

Флаг exactKey=false

Если в качестве key передать строку, содержащую точку, то такая строка будет интерпритирована как путь к свойству во вложенном объекте. фреймворк будет слушать изменения во всём дереве, разрывая связь для старых ветвей, и создавая её для новых.

this.a = { b: { c: 'foo' } };
this.bindNode('a.b.c', node);

this.a.b.c = 'bar'; // обновит элемент значением bar

const oldB = this.a.b;

this.a.b = { c: 'baz' }; // обновит элемент значением baz

 // элемент не обновится, так как связь с этой ветвью разорвана
oldB.c = 'fuu';

В случае, если имя свойства должно быть использовано как есть, воспользуйтесь флагом exactKey со значением true.

this['a.b.c'] = 'foo';
this.bindNode('a.b.c', node, binder, {
    exactKey: true
});
this['a.b.c'] = 'bar';

Флаг getValueOnBind

При наличии у байндера getValue, состояние элемента будет извлечено и присвоено свойству сразу после вызова bindNode при условии, если привязываемое свойство имеет значение undefined. Для того, чтоб форсировать это поведение даже если свойство - не undefined используйте флаг getValueOnBind со значением true. Для отмены этого поведения, используйте тот же флаг со значением false.

Флаг setValueOnBind

При наличии у байндера setValue, значение свойства будет установлено в качестве состояния элемента сразу после вызова bindNode при условии, если привязываемое свойство имеет значение отличное от undefined. Для того, чтоб форсировать это поведение даже если свойство - undefined используйте флаг setValueOnBind со значением true. Для отмены этого поведения, используйте тот же флаг со значением false.

Флаги debounceGetValue=true и debounceSetValue=true

Важной особенностью метода bindNode является то, что к изменению свойств и изменению состояния элемента применяется микропаттерн debounce. Это значит, что если привязанное свойство будет изменено многократно за короткий промежуток времени (например, в цикле), состояние элемента будет обновлено лишь один раз после задержки в несколько миллисекунд (благодаря debounceSetValue=true). И наоборот: если состояние элемента меняется многократно за короткий промежуток времени (т. е. вызывается соответствующее DOM событие), свойство получит новое значение только один раз после короткой зарержки (благодаря debounceGetValue=true).

const input = document.querySelector('.my-input');
this.bindNode('x', input);
this.x = 'foo';
console.log(input.value === 'foo'); // false
setTimeout(() => {
    console.log(input.value === 'foo'); // true
});

Для отмены этого поведения, т. е. для отмены асинхронности действий, используйте флаги debounceSetValue и/или debounceGetValue со значением false.

Флаги debounceSetValueOnBind=false и debounceGetValueOnBind=false

Как говорилось выше, к изменению свойств и изменению состояния элемента применяется микропаттерн debounce. Это не касается самого момента связывания. При вызове bindNode установка состояния элемента или его извлечение с изменением свойства происходит синхронно. debounceSetValueOnBind и debounceGetValueOnBind установленные как true включают debounce и для этих процессов.

Флаги debounceSetValueDelay=0 и debounceGetValueDelay=0

Эти флаги позволяют указать задержку debounce. debounceSetValueDelay задаётся при использовании debounceSetValue и debounceSetValueOnBind, debounceGetValueDelay при использовании debounceGetValue и debounceGetValueOnBind.

Флаг useExactBinder=false

Даже если в метод bindNode передать конкретный байндер, фреймворк попытается отыскать байндер из Seemple.defaultBinder и расширить его свойствами переданного объекта. Такая возможность позволяет использовать дефолтный байндер, который частично переопределен.

Например, мы хотим связать input[type="text"] со свойством. По умолчанию, стандартный байндер для этого элемента содержит свойство "on" со значением "input". Это значит, что значение свойства экземпляра и состояние элемента будут синхронизированы сразу после ввода или удаления символа пользователем. В случае, если вы хотите, чтоб синхронизация происходила по DOM событию "blur", вам потребуется передать третьим аргументом объект, содержащий единственное свойство "on". Этот объект объединится со стандартным байндером, сохранив при этом значения getValue и setValue.

this.bindNode('x', '.my-input', { on: "blur" });

Для отмены этого поведения и использования байндера как он есть, в объект события можно передать флаг useExactBinder со значением true.

this.bindNode('x', node, binder, {
    useExactBinder: true
})

В метод Seemple#bindNode можно передать объект чтобы избежать многократного вызова метода и сократить код. Ключи объекта - это имена привязываемых свойств, а значения могут быть следующими:

• HTML элемент
• Объект со свойствами node (HTML элемент) и binder
• Массив объектов со свойствами node (HTML элемент) и binder

Если binder передан вторым аргументом, то он служит байндером для тех элементов, для которых байднер не указан явно.

Вариация метода позволяет передать массив объектов, содержащих информацию об одном байндинге каждый. Элемент массива должен содержать следующие свойства:

• key - имя свойства
• node - элемент, для которого объявляем связывание с key
• binder - байндер (не обязательно)
• event - объект события (не обязательно)

Второй аргумент - общий объект события, расширяющий event для каждого байндинга (свойства из event приоритетнее).

У метода есть статичный аналог.

При этом, "отвязывает" предыдущую, если таковая существует.

У метода есть статичный аналог.

Метод calc создает зависимость значения свойства (аргумент target) от значений других свойств (аргумент source). При изменении source, target вычисляется автоматически.

Обратите внимание, что у метода есть статичный аналог, который работает в точности так же, но принимает любой объект в качестве первого аргумента, cдвигая остальные аргументы вправо.

const calc = require('seemple/calc');
const object = {};
calc(object, target, source, handler, eventOptions);
// вместо this.calc(target, source, handler, eventOptions);

Аргумент source имеет несколько вариаций.

Строка

Свойство target будет зависеть от свойства source.

this.b = 1;
this.calc('a', 'b', b => b * 2);
console.log(this.a); // 2

Массив строк

Свойство target будет зависеть от свойств, перечисленных в source.

this.b = 1;
this.c = 2;
this.d = 3;
this.calc('a', ['b', 'c', 'd'], (b, c, d) => b + c + d);
console.log(this.a); // 6

Объект со свойствами object и key

В этом случае можно объявить зависимость свойства target от другого объекта.

const someObject = { b: 1 };
this.calc('a', {
    object: someObject,
    key: 'b'
}, b => b * 2);

console.log(this.a); // 2

В качестве свойства key в объект можно передать массив ключей.

const someObject = {
    b: 1,
    c: 2,
    d: 3
};
this.calc('a', {
    object: someObject,
    key: ['b', 'c', 'd']
}, (b, c, d) => b + c + d);

console.log(this.a); // 6

Массив объектов со свойствами object и key

Так можно объявить зависимость свойства от свойств разных объектов.

const someObjectX = {
    b: 1,
    c: 2
};
const someObjectY = {
    d: 3
};
this.calc('a', [{
    object: someObjectX,
    key: ['b', 'c']
}, {
    object: someObjectY,
    key: 'd'
}], (b, c, d) => b + c + d);

console.log(this.a); // 6

Массив, комбинирующий строки (собственные свойства) и объекты

this.b = 1;
this.c = 2;

const someObject = {
    d: 3,
    e: 4
};

this.calc('a', ['b', 'c', {
    object: someObjectX,
    key: ['d', 'e']
}], (b, c, d, e) => b + c + d + e);

console.log(this.a); // 10

Из соображений чистоты кода, комбинировать строки и объекты в массиве source не рекомендуется. Вместо строк лучше передать объект, у которого свойство object равно целевому объекту. Пример ниже делает то же самое, что и предыдущий.

this.b = 1;
this.c = 2;

const someObject = {
    d: 3,
    e: 4
};

this.calc('a', [{
    object: this, // целевой объект - это this
    keys: ['b', 'c']
}, {
    object: someObjectX,
    key: ['d', 'e']
}], (b, c, d, e) => b + c + d + e);

console.log(this.a); // 10

Точка в имени свойства-источника

Если имя ключа содержит точку, метод инициирует зависимость от свойства во вложенном объекте.

this.b = { c: { d: 1 } };
this.e = { f: { g: 2 } };

this.calc('a', ['b.c.d', 'e.f.g'], (d, g) => d + g);

console.log(this.a); // 3

То же самое касается и внешних объектов

this.b = { c: { d: 1 } };
const someObject = { e: { f: { g: 2 } } };

this.calc('a', [{
    object: this
    key: 'b.c.d'
}, {
    object: someObject
    key; 'e.f.g'
}], (d, g) => d + g);

console.log(this.a); // 3

Метод защищен от цикличных зависимостей (например a зависит от b, b зависит от c, а c зависит от a) и при ошибке вычислений не блокирует страницу и не бросает исключение о переполнении стека.

Как вы могли заметить, аргументы функции handler всегда расположены в том же порядке, что и свойства из source.

В случае, если нужно изменить значение свойства-источника и сделать это так, чтоб целевое свойство не было вычислено заново, используйте метод Seemple#set с флагом skipCalc равным true.

this.calc('a', 'b', handler);
this.set('b', newValue, {
    skipCalc: true
});

Важные особенности работы метода и специальные флаги

Четвертым аргументом в метод calc можно передать объект события eventOptions, содержащий специальные флаги, которые описаны ниже, флаги для метода set (например, silent), либо кастомные данные, которые передаются в обработчик события change:KEY.

this.on('change:a', evt => {
    console.log(evt.foo); // 'bar'
});

this.calc('a', source, handler, { foo: 'bar' });

Флаг debounceCalc=true

При вызове метода calc целевое свойство вычисляется без задержек, но при изменении свойства-источника применяется паттерн debounce. Это значит, что целевое свойство изменится через несколько миллисекунд и только один раз, даже если свойства-источники изменились многократно за короткий промежуток времени.

this.b = 1;
this.c = 2;
this.d = 3;

this.calc('a', ['b', 'c', 'd'], (b, c, d) => b + c + d);

this.on('change:a', () => {
    // обработчик будет вызван один раз несмотря на то,
    // что свойства-источники изменились трижды
    console.log(`a is changed to ${this.a}`); // a is changed to 60
});

this.b = 10;
this.c = 20;
this.d = 30;
console.log(this.a); // 6 вместо 60

Для отмены debounce при изменении свойств, т. е. для включения моментального обновления целевого свойства (как было в предыдущих версиях метода), четвертым аргументом метода calc можно передать флаг debounceCalc равный false.

this.b = 1;
this.c = 2;
this.d = 3;

this.calc('a', ['b', 'c', 'd'], (b, c, d) => b + c + d, {
    debounceCalc: false
});

this.on('change:a', () => {
    // обработчик будет вызван трижды,
    // каждый раз когда свойства b, c или d меняются

    // a is changed to... 15, 33, 60
    console.log(`a is changed to ${this.a}`);
});

this.b = 10;
this.c = 20;
this.d = 30;
console.log(this.a); // 60

Флаг debounceCalcOnInit=false

Как говорилось выше, при вызове метода calc целевое свойство вычисляется сразу, а при изменении свойств-источников - нет. Включить debounce и при первом вычислении свойства можно передав в качестве свойства объекта события флаг debounceCalcOnInit=true.

this.on('change:a', () => {
    // обработчик будет вызван один раз через небольшой промежуток времени
    console.log(`a is changed to ${this.a}`); // a is changed to 6
});

this.b = 1;
this.c = 2;
this.d = 3;

this.calc('a', ['b', 'c', 'd'], (b, c, d) => b + c + d, {
    debounceCalcOnInit: true
});

console.log(this.a); // undefined

На практике debounceCalcOnInit вряд ли пригодится. Нужно лишь помнить, что есть флаг включающий "полный debounce".

Флаг debounceCalcDelay=0

Флаг позволяет указать задержку debounce при использовании debounceCalc и debounceCalcOnInit.

Флаг setOnInit=true

Известно, что при вызове метода calc свойство сразу получает новое значение. Для того, чтоб отменить это поведение и вычислить свойство target только тогда, когда свойство-источник впервые изменено, используйте флаг setOnInit равный false.

this.calc('a', 'b', b => b * 2, {
    setOnInit: false
});

console.log(this.a); // undefined

// но если обновить this.b, для свойства a будет вычислено новое значение
this.b = 1;

Флаг exactKey=false

Как говорилось выше, в качестве имени свойства-источника можно передать строку, содержащую точки. Такое имя будет истолковано как путь к свойству во вложенном объекте. В случае, если имя должно быть использовано как есть, воспользуйтесь флагом exactKey со значением true.

this['foo.bar.baz'] = 1;
this.calc('a', 'foo.bar.baz', fooBarBaz => fooBarBaz * 2, {
    exactKey: true
});
console.log(this.a); // 2

Флаг promiseCalc=false

Этот флаг позволяет использовать экземпляры Promise внутри функции, вычисляющей значение. Значением искомого свойства становится результат успешного выполнения промиса.

Внимание! Promise невозможно отменить. Используйте возможность promiseCalc аккуратно и не допускайте многократного вызова тяжелых функций.

this.calc('a', ['b', 'c'], (b, c) => {
    return new Promise(resolve => {
        setTimeout(() => {
            resolve(a + b)
        }, 1000);
    });
}, {
    promiseCalc: true
});

this.b = 1;
this.c = 2;

// "a" изменится через секунду

this.calc('response', 'data', async (data) => {
    const resp = await fetch(url, {
        method: 'post',
        body: data
    });

    return resp.json();
}, {
    promiseCalc: true
});

Первый аргумент - объект, ключи которого - имена свойств, которые нужно вычислять, а значения - объекты, содержащие:

• source - свойства, от которых зависит целевое свойство;
• handler - как именно будет вычислено свойство (по умолчанию равен (value) => value);
• event - объект события (не обязательно).

Второй аргумент - общий объект события, расширяющий event для каждого искомого свойства (свойства из event приоритетнее).

source может принимать любой вид описаный выше (строка, массив строк, объект со свойствами key и object, массив объектов).

Обратите внимание, что у метода есть статичный аналог.

Метод создаёт и фиксирует экземпляр класса в качестве значения заданного свойства. При попытке переопределить свойство, вместо самого переопределения, экземпляр обновляется. Таким образом достигается целостность приложения, сделанном на базе Seemple.

Метод является надстройкой над Seemple#mediate и переопределяет медиатор.

Экземпляр класса создается во время запуска метода instantiate. Первым аргументом конструктора класса становится текущее значение свойства. В конструкторе класса необходимо предусмотреть то, что в него попадет либо undefined (если свойство не содержало до этого никаких данных), либо объект, с которым нужно что-то сделать (например, расширить экземпляр класса свойствами объекта).

На деле это выглядит просто: вы создаете обычный класс, который почти всегда принимает какие-нибудь данные, которые нужно обработать (например, использовать их в методе Seemple.Object#setData).

При попытке присвоить свойству другое значение, внутренний механизм метода instantiate, вместо присваивания, делает следующее:

• Если указана функция updateCallback, метод запускает его с двумя аргументами: текущим значением свойства и данными, которые код пытается присвоить.
• Если заданный класс унаследован от Seemple.Object, экземпляр обновляется новыми данными, используя метод Seemple.Object#setData с флагом replaceData=true.
• Если заданный класс унаследован от Seemple.Array, экземпляр обновляется новыми данными, используя метод Seemple.Array#recreate.
• Если не указана функция updateCallback и если класс не унаследован от Seemple.Object или Seemple.Array, экземпляр расширяется свойствами объекта, который код пытается присвоить.

Особенностью метода является отсутствие ограничений на источник класса. В качестве класса может выступать любая функция-конструктор. которая инициализируется с помощью оператора new, а не только наследники Seemple.

Этот метод используется для преобразования значения свойства при его изменении. Например, вам нужно, чтоб значение свойства всегда было либо определенного типа, либо целым числом, либо быть не менее нуля и не более ста и т. д.

Обратите внимание, что у метода есть статичный аналог, который работает в точности так же, но принимает любой объект в качестве первого аргумента, cдвигая остальные аргументы вправо.

const mediate = require('seemple/mediate');
const object = {};
mediate(object, key, mediator);
// вместо this.mediate(key, mediator);

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

Метод Seemple#on добавляет обработчик события для экземпляра класса Seemple. Полный список возможных событий с описанием см. здесь: eventNames.

Обратите внимание, что у метода есть статичный аналог, который работает в точности так же, но принимает любой объект в качестве первого аргумента, cдвигая остальные аргументы вправо.

const on = require('seemple/on');
const object = {};
on(object, names, callback, triggerOnInit, context);
// вместо this.on(names, callback, triggerOnInit, context);

В метод Seemple#on можно передать объект с парами событие-обработчик, чтобы избежать многократного вызова метода и сократить код.

Метод позволяет добавить обработчик события на экземпляр класса Seemple, устраняя "дребезжание" обработчика. Функция может быть вызвана лишь один раз за определенный промежуток времени. В остальном, метод работает так же, как и Seemple#on.

У метода есть статичный аналог.

В метод Seemple#onDebounce можно передать объект с парами событие-обработчик, чтобы избежать многократного вызова метода и сократить код.

Метод работает так же, как и Seemple#on но передаваемый обработчик может быть вызван только один раз.

Обратите внимание, что у метода есть статичный аналог

В метод Seemple#once можно передать объект с парами событие-обработчик, чтобы избежать многократного вызова метода и сократить код.

Начиная с версии 1.1, Seemple.js включает в себя простой DOM парсер, обрабатывающий синтаксические конструкции, заключенные в двойные фигурные скобки. Метод parseBindings первым аргументом принимает HTML строку, DOM узел или селектор, соответствующий DOM узлу.

Так как метод является DOM шаблонизатором (а не строковым HTML шаблонизатором), все дочерние DOM узлы переданного элемента остаются в своём прежнем состоянии (например, DOM события не затираются).

Поддерживаемый синтаксис.

1. HTML привязка ```html <!-- Создаст текстовый узел на месте {{user.name}} и свяжет свойство name из объекта user с этим узлом JS: this.user = {name: 'Joe'}

--> Hello, {{user.name}}

2. Привязка элементов форм.
```html
<!--
Свяжет свойство "x" экземпляра с текстовым
полем (двусторонняя привязка)
JS: this.x = 'some value';
-->
<input type="text" value="{{x}}">

<!--
Для привязки textarea и select нужно использовать атрибут value
-->
<textarea value="{{x}}"></textarea>
<select value="{{x}}">...</select>

<!--
Свяжет свойство "x" экземпляра с чекбоксом
(двусторонняя привязка)
JS: this.x = true;
-->
<input type="checkbox" checked="{{x}}">

3. Привязка атрибутов. ```html <!-- Значение атрибута href будет зависеть от значений свойств "category" и "someObject.page" (односторонняя привязка) JS: this.category = 'seemple'; this.someObject = { page: 42 };

--> A link

```

Если фигурные скобки не устраивают, поменяйте их на что-то другое, используя Seemple.parserBrackets

Зачем нужен такой метод?

В случае, если вы разрабатываете большую форму со стандартными HTML5 полями, метод поможет сохранить время на объявление многочисленных привязок. Кроме этого, parseBindings полезен в случае создания очень простой коллекции, не требующей реализации сложной модели.

Метод очень похож на Seemple#selectAll, но возвращает лишь один элемент или null

У метода есть статичный аналог.

После создания песочницы методом Seemple#bindNode, можно получать и использовать элементы, находящиеся в ней. Кроме этого, метод поддерживает селектор :bound(KEY).

У метода есть статичный аналог.

Список поддерживаемых флагов:

• silent - не вызывать события change и change:KEY
• silentHTML - не менять состояние привязанных элементов
• force - вызвать события change и change:KEY даже если значение свойства не изменилось
• forceHTML - изменить состояние привязанного элемента, даже если значение свойства не изменилось. Эта опция нужна, если привязанный элемент был отрисован после привязки (например, в select были добавлены теги option)
• skipMediator - предотвращает трансформацию свойства медиатором (см. Seemple#mediate)
• skipCalc - предотвращает работу зависимостей, созданных с помощью Seemple#calc

У метода есть статичный аналог.

После добавление обработчиков событий с помощью метода Seemple#on, Seemple#onDebounce или Seemple#once, событие можно генерировать вручную с помощью этого метода.

Обратите внимание, что у метода есть статичный аналог.

Используя этот метод, можно удалить недавно добавленную, но уже не нужную связь между свойством и элементом.

Вариация метода позволяет передать масссив объектов, содержащих информацию об одном байндинге каждый. Элемент массива должен содержать следующие свойства:

• key - имя свойства
• node - элемент, для которого был объявле байндинг с key (не обязательно)

Эта вариация метода удобна тем, что её синтаксис совпадает с одной из вариаций метода Seemple#bindNode, позволяя присвоить байндинги переменной для быстрого удаления.

Функция Class позволяет использовать классическое ООП в тех случаях, когда нельзя воспользоваться синтаксисом ECMAScript 2015 classes.

Этот статичный метод работает так же, как и Seemple#bindNode и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#bindOptionalNode и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#bindSandbox и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#calc и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Функция принимает любой объект и возвращает экземпляр недоступного извне класса, который перенимает универсальные методы, позволяя их цепной вызов для работы с переданным объектом.

Универсальные методы - это такие методы, которые одновременно есть в прототипе Seemple и имеют статичный аналог (например, Seemple#bindNode и Seemple.bindNode).

Этот статичный метод работает так же, как и Seemple#instantiate и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Возвращает байндер, соответствующий элементу. Если таковой не найден, возвращает undefined. Функция перебирает Seemple.defaultBinders для поиска байндера.

Этот статичный метод работает так же, как и Seemple#mediate и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#off и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#on и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#onDebounce и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#once и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#parseBindings и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#remove и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#select и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#selectAll и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#set и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#trigger и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

Этот статичный метод работает так же, как и Seemple#unbindNode и все его вариации, но принимает в качестве первого аргумента любой JavaScript объект.

По умолчанию, Seemple.js использует в качестве библиотеки ту, которая находится по ссылке window.$. Если такой переменной нет в глобальном пространстве имен, либо же она не включает в себя необходимый набор методов, то используется встроенная микро библиотека.

Метод useDOMLibrary заставляет фреймворк использовать ту библиотеку, которую вы захотите использовать, не смотря на отсутствие таковой в глобальном пространстве имен или по другой причине (например, если используется две разных версии jQuery на странице). Необходимо, чтобы метод был запущен перед объявлением каких-либо байндингов.

Значение свойства можно преобразить с помощью переданной функции mappingFn.

Значение свойства можно преобразить с помощью переданной функции mappingFn.

Байндер работает так же, как и Seemple.binders.display, но вместо изменения видимости элемента, изменяется наличие элемента на странице. Байндер полезен для:

• Крупных приложений: в зависимости от состояния роутера показать ту или иную страницу;
• Для реализации бесконечного скроллинга;
• Для других задач, где нужно спрятать элемент, но его наличие в DOM дереве не обязательно.

Значение свойства можно преобразить с помощью переданной функции mappingFn.

Значение свойства можно преобразить с помощью переданной функции mappingFn.

Значение свойства можно преобразить с помощью переданной функции mappingFn.

Seemple.binders.text позволяет вывести содержимое свойства как есть. Значение свойства можно преобразить с помощью переданной функции mappingFn.

Этот метод применяется тогда, когда нужно объявить свойства, отвечающие за данные, но значения этих свойств еще не известны.

Метод очень похож на Array.prototype.forEach и является альтернативой циклу for..of.

Этот метод делает две вещи:

1. Устанавливает заданное значение заданному свойству.

2. Добавляет ключ свойства в список данных, что делает свойство доступным для использования в методах Seemple.Object#each, Seemple.Object#keys, Seemple.Object#toJSON).

Если передать флаг replaceData, установленный как true объект события, то остальные свойства будут удалены из списка свойств, отвечающих за данные.

В остальном, метод работает так же, как и Seemple#set.

Метод работает рекурсивно, вызывая toJSON для всех свойств, у которых есть метод с таким именем. Для отмены рекурсии передайте false первым аргументом.

Seemple.Array включает в себя все методы, входящие в нативный JavaScript массив:

• join
• pop
• push
• reverse
• shift
• unshift
• slice
• splice
• sort
• filter
• forEach
• some
• every
• map
• indexOf
• lastIndexOf
• reduce
• reduceRight
• copyWithin
• find
• findIndex
• fill
• includes
• entries
• keys
• concat

При этом, они работают точно так же, как и методы Array.prototype. Есть лишь несколько оговорок:

• Метод forEach возвращает себя вместо undefined
• Методы, которые в оригинальном виде возвращают новый массив (splice, slice, filter, map...), возвращают новый экземпляр Seemple.Array.
• Методы keys, values и entries возвращают массив вместо итератора.

Кроме всего, методы генерируют события связанные с любой модификацией массива. Подробнее см. Seemple.Array.

Ознакомившись с Seemple.Array#METHOD становится понятно, что методы не поддерживают передачу объекта события, так как в точности повторяют синтаксис и количество аргументов встроенного Array. Синтаксис МЕТОД_ позволяет передать в обработчик события какие-нибудь данные либо установить служебные флаги, отвечающие за поведение массива после вызова метода.

Список доступных флагов:

• silent - отключает генерацию событий
• dontRender - отключает рендеринг
• skipItemMediator - отключает медиаторы

При каждом добавлении элементов в массив, встроенный обработчик проверяет, является ли добавленный элемент экземпляром Model и конвертирует его в таковой, если проверка не пройдена. Рекомендуется наследовать Model от класса Seemple.Object или Seemple.Array (на случай, если требуется получить коллекцию коллекций), чтоб получить возможность конвертации массива в обычный массив методом Seemple.Array#toJSON.

Для более гибкого контроля класса элементов (например, если для одних элементов нужно использовать одну Модель, а для других - другую), используйте Seemple.Array#mediateItem.

Этот метод служит для того, чтоб перехватить и трансформировать добавленные в массив элементы. Обратите внимание, метод переопределяет свойство Seemple.Array#Model.

Виртуальный метод onItemRender можно использовать в качестве замены события render.

При этом, у отрисованного элемента вызывается виртуальный метод onRender с единственным аргументом - объектом события.

Этот метод работает почти так же, как и метод orderBy из lodash. Он принимает ключ или массив ключей - первым аргументом, порядок (asc/desc) или массив порядков - вторым.

Метод позволяет конвертировать любой массив (или объект, подобный массиву) в экземпляр Seemple.Array. Если ничего не передано в качестве первого аргумента, экземпляр очищается.

Этот метод заново рендерит элементы массива в контейнере массива. Если узел, который ассоциирован с элеменом масива уже создан, метод, вместо перерисовки с нуля, "перевставляет" его в контейнер или песочницу массива.

Метод может быть полезным на случай, когда элементы добавлены в массив перед объявлением песочницы или контейнера.

Чтоб заставить массив перерисоваться, независимо от наличия отрендеренных узлов (например, вы используете кастомный шаблонизатор в itemRenderer), передайте в метод объект со свойством forceRerender равным true.

В случае, если коллекция заранее отрисована на странице (например, с помощью сервера), метод может воссоздать коллекцию из отрендеренных HTML узлов.

<!-- One, Two, Three заранее отрисованы -->
<ul class="collection-node">
    <li>One</li>
    <li>Two</li>
    <li>Three</li>
    <script type="text/html" class="renderer">
        <li></li>
    </script>
</ul>

class MyModel extends Seemple.Object {
    constructor(data) {
        super(data);
        this.addDataKeys('value');
    }
    onRender() {
        this.bindNode('value', ':sandbox', Seemple.binders.html())
    }
});

class MyCollection extends Seemple.Array {
    get itemRenderer() {
        return ':sandbox .renderer';
    }
    constructor() {
        this
            .bindNode('sandbox', '.collection-node')
            .restore(':sandbox li');
    }
});

const myCollection = new MyCollection();
myCollection.push({
    value: 'Four'
});

console.log(myCollection.toJSON());
// [{value: 'One'}, {value: 'Two'}, {value: 'Three'}, {value: 'Four'}]

Если аргумент selector не задан, то коллекция будет воссоздана из элементов, входящих в контейнер ("container" или "sandbox").

При воссоздании, на каждом элементе массива генерируется событие render и вызываются методы onRender и onItemRender (см документацию), как и при обычном рендеринге.

Метод работает рекурсивно, вызывая toJSON для входящих объектов, у которых есть метод с таким именем. Для отмены рекурсии передайте false первым аргументом.