Документация v4.0

[s0rr0w]

Введение

StateController (далее SC) логически разбит на два независимых процесса: процесс установки значения состояния и процесс обхода дерева нод. Состояние может изменяться в процессе работы несколько раз, может вообще не устанавливаться.

Состояния

Состоянием является имя переменной в процессе установки значения состояния, или идентификатор события в процессе обхода дерева нод. Синтаксис состояния должен удовлетворять правилам создания JS-переменной. При установке значения состояния создается свойство объекта states экземпляра SC. При обходе дерева нод, имя состояния используется в качестве имени события.

Типы обхода дерева нод

Существует два типа обхода дерева нод:

* типизированный

* нетипизированный

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

Описание объекта

Поля

states

Описание

Объект states является именованым массивом инициализированных состояний объекта, которые возникли в процессе работы SC.

Публичные методы

setStateValue

Описание

Устанавливает значение переменной состояния.

Параметры вызова

* name

имя переменной состояния

* value

значение переменной состояния

getStateValue

Описание

Возвращает значение переменной состояния.

Параметры вызова

* name

имя переменной состояния

launchTreeWalk

Описание

Запускает обход дерева.

Параметры вызова

* target

контейнер, внутри которого происходит обход по дереву нод

* states

список состояний через запятую, на которые должен реагировать обходчик по дереву

* [execOptions]

объект с дополнительными параметрами запуска

Существуют следующие предустановленные параметры запуска:

propagation

Фильтр нод, на которые распространяется функция реагирования обходчика по дереву нод.

По умолчанию значение равно "*", т.е. обходчик обходит все ноды внутри контейнера.

Значение parent означает распространение действия обходчика только на ноду контейнера.

Значение childNodes означает распространение действия обходчика на ноду контейнера и на все дочерние ноды контейнера.

Можно указывать названия нод через запятую, в верхнем регистре, если необходимо отфильтровать только ноды с определенным именем. Например A,SPAN,DIV. При этом распространение действия обходчика будет на ноду контейнера и на все ноды с указанными именами.

Разрешено использовать только один из четырех вариантов, без смешивания.

levels

Уровни состояний, написанные через запятую. По умолчанию значение levels равно "all".

Приватные методы

createStateObj

parseAttribute

Методы не нужны для работы с SC, поэтому функциональность не описывается.

Глобальный объект

Описание

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

Глобальные функции

GSC_setVal

Описание

Устанавливает значение переменной состояния для объекта globalStateController.

Параметры вызова

* name

имя переменной состояния

* value

значение переменной состояния

Пример использования

GSC_setVal( "show_menu", true ); // window.globalStateController.states.show_menu = true;

GSC_getVal

Описание

Возвращает значение переменной состояния объекта globalStateController

Параметры вызова

* name

имя переменной состояния

Пример использования

GSC_getVal( "show_menu", true ); // true

GSC_launch

Описание

Запускает обход дерева. Используется объект globalStateController

Параметры вызова

* target

контейнер, внутри которого происходит обход по дереву нод

* states

список состояний через запятую, на которые должен реагировать обходчик по дереву

* [execOptions]

объект с дополнительными параметрами запуска

Пример использования

GSC_launch ( "container", "show_menu", { levels: "10", propagation: "childNodes"} );

GSC_setValAndLaunch

Описание

Устанавливает значение переменной состояния и запускает обход дерева нод. Используется объект globalStateController

Параметры вызова

* name

имя переменной состояния

* value

значение переменной состояния

* target

контейнер, внутри которого происходит обход по дереву нод

* [execOptions]

объект с дополнительными параметрами запуска

Пример использования

GSC_setValAndLaunch ( "show_menu", true, "container", { levels: "10", propagation: "childNodes"} );

Обработчики SC

Синтаксис

Для присвоения обработчика или нескольких обработчиков любой ноде используется атрибут SC. Значение атрибута будет обрабатываться контроллером состояний.

<node SC="scHandlers" />

Синтаксис scHandlers:

directive 1[|directive 2|...|directive n]

где directive

[level*]js_function_name:state[:option 1:option 2:...:option n][--allowNonDirect]

Каждая директива отделяется друг от друга символом "|". Директива состоит из уровня, имени JS-функции, имени состояния-события, дополнительных параметров, управляющей опции allowNonDirect.

Уровень должен быть числовым значением.

Функция-обработчик - имя JS-функции, которая будет исполнена при определенных условиях.

Дополнительные параметры не должны содержать символов ":", "*", "|", "--". Желательно использовать синтаксис js-переменных или использовать числа в качестве дополнительных параметров.

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

Пример использования

<div SC="sc_show_node:show_menu">

<div SC="sc_show_node:show_menu|sc_show_node:show_sub_menu">

<div SC="2*sc_switch_class_name:activate:hiddenBlock--allowNonDirect">

Обработчики JS

Обработчикам передаются следующие параметры:

* controller

ссылка на экземпляр объекта контроллера состояний

* node

ссылка на ноду, которая содержит обработчик

* scData

объект с инициализирующими параметрами

* execParams

объект с дополнительными параметрами запуска

Теоретически, можно создавать несколько экземпляров контроллера состояний, на практике, в большинстве случаев, используется всего один - globalStateController.

scData имеет следующую структуру:

* allowNonDirect

флаг запуска обработчика в случае нетипизированных событий

* args

массив аргументов, которые передаются обработчику

* func

имя функции-обработчика

* indx

позиция директивы в списке директив атрибута SC

* level

уровень запуска

* state

имя состояния, на которое реагирует обработчик

Принцип работы

Состояние логически является переменной и событием одновременно. Имя состояния выступает типом события. Установка значения переменной состояния никак не влияет на обход дерева нод.

Запуск обхода нод производится для какого-либо участка дерева нод документа. Первым проверяется нода контейнера, потом остальные ноды внутри указанного контейнера. Ограничить зону "видимости" обходчика можно с помощью параметра запуска propagation. У каждой ноды ищется атрибут SC, и, если атрибут найден, разбирается значение данного атрибута. Потом выполняются те обработчики, имя состояния которых соответствует имени события, при этом учитываются параметры level и --allowNonDirect.

Edited October 17, 2009 by s0rr0w