winWrapper – обертка для окна/фрейма браузера

Для текущего окна, в которое загружается скрипт, обертка создается автоматически. Получить обертку текущего окна можно двумя способами: "window._wrapper" или просто "_wrapper". Для других окон или фреймов обертка создается при помощи конструкции "new winWrapper(win)", где win - ссылка на объект window, для которого создается обертка.

Категорически не рекомендуется создавать несколько оберток для одного окна, так как при этом в некоторых браузерах полностью нарушается работа скрипта. Если обертка для какого-либо окна уже создана - Вы должны использовать ее, а не создавать новую.

{strip}

Основные свойства
Свойство	Описание
win	Ссылка на объект window.
doc	Ссылка на объект document.

Дополнительные свойства
Свойство	Описание
shiftLeft	дополнительное горизонтальное смещение (по умолчанию – 0), при манипуляции HTML-элементами.
shiftTop	дополнительное вертикальное смещение (по умолчанию – 0), при манипуляции HTML-элементами.
cookieVal	объект, содержащий Куки в формате "ключ:значение".
cookieExtra	строка дополнительных параметров при записи куки.
bv	объект browserVersion.

Методы для получения "оберток" HTML-элементов
Метод	Описание
checkElement	проверка наличия элемента по ID.
getElement	получить обернутый элемент по ID.
getForm	получить обернутый тег form по имени или порядковому номеру.
getFormElement	получить обернутый тег элемента формы по именам или порядковым номерам.
getImage	получить обернутый тег img по имени или ID.
getElmWrapper getElementWrapper	получить обертку html-элемента (например, элемента полученного средствами DOM).
makeElement	создать новый элемент средствами DOM и присвоить ему атрибуты и дочерние элементы.
getCloneElement	получить обертку клона элемента, по ID.

Методы для манипуляций с объектами window/document
Метод	Описание
getDocFrame	получить document frame.
getWindowLeft	положение окна по горизонтали, относительно экрана.
getWindowTop	положение окна по вертикали, относительно экрана.
getWindowWidth	ширина окна.
getWindowHeight	высота окна.
getDocumentWidth	ширина документа.
getDocumentHeight	высота документа.
getScrollX	скроллинг по горизонтали.
getScrollY	скроллинг по вертикали.

Дополнительные общие методы окна
Метод	Описание
createStyle	Создать новый дескриптор (например, класс) в таблице стилей.
loadStyle	Подгрузить дополнительную таблицу стилей (по URL).
getCookie	получить Куки по имени ключа.
setCookie	установить Куки.
deleteCookie	удалить Куки.
getSid	получить Session ID.
setSid	установить Session ID.

Специальные методы
Метод	Описание
getClosedFunction	Получение специальной функции-замыкания.
setTimeout	Запуск таймера.
setInterval	Запуск циклического таймера.
openPopUp	Открытие Pop Up, с возможностью создания обертки для него.

Подписка на событие, сброс подписки
Метод	Описание
setOnloadListener	Подписаться на onLoad.
removeOnloadListener	Убрать подписку на onLoad.
setOnUnloadListener	Подписаться на onUnLoad.
addListener	Подписаться на любое событие window или document.
removeListener	Убрать подписку с любого события window или document.

{/strip}

Свойство win

Синтаксис: объект.win;

Значением свойства win является ссылка на объект window окна/фрейма, для которого создана обертка.

Свойство doc

Синтаксис: объект.doc;

Значением свойства doc является ссылка на объект document окна/фрейма, для которого создана обертка.

Свойство shiftLeft

Синтаксис: объект.shiftLeft;

Значением свойства shiftLeft дополнительное горизонтальное смещение (по умолчанию – 0), при манипуляции HTML-элементами.

Свойство shiftTop

Синтаксис: объект.shiftTop;

Значением свойства shiftTop дополнительное вертикальное смещение (по умолчанию – 0), при манипуляции HTML-элементами.

Свойство cookieVal

Синтаксис: объект.cookieVal;

Значением свойства cookieVal объект, содержащий Куки в формате "ключ:значение".

Свойство cookieExtra

Синтаксис: объект.cookieExtra;

Значением свойства cookieExtra строка дополнительных параметров при записи куки.

Свойство bv

Синтаксис: объект.bv

Значение свойства bv является объектом browserVersion.

Метод checkElement

Синтаксис: объект.checkElement(ID-элемента); Аргументы: ID-элемента — любое строковое выражение Результат: булево значение

Метод checkElement позволяет проверить наличие элемента с указанным ID. Как правило, метод checkElement вызывают перед методом getElement, для того чтобы проверить существование объекта, прежде чем создавать для него обертку. Но в большинстве случаев Вам этот метод не нужен - достаточно просто дать второму аргументу метода getElement значение 1 или true.

Метод getElement

Синтаксис: объект.getElement(ID-элемента[,игнорировать_ошибки]?); Аргументы: ID-элемента — любое строковое выражение игнорировать_ошибки — логическое выражение Результат: JavaScript-объект - обертка элемента

Метод getElement возвращает ссылку на обертку элемента с указанным ID.

Аргумент игнорировать_ошибки используется в тех случаях, когда Вы не хотите получать сообщение об ошибках, при отсутствии указанного элемента.

Метод getForm

Синтаксис: объект.getForm(имя/номер-формы[,игнорировать_ошибки]?); Аргументы: имя/номер-формы — любое строковое выражение игнорировать_ошибки — логическое выражение Результат: JavaScript-объект - обертка элемента

Метод getForm возвращает ссылку на обертку формы с указанным именем или порядковым номером. В отличие от метода getElement здесь вместо средств DOM используется встроенный объект document.forms, поэтому форма, к которой Вы хотите получить доступ может не иметь ID.

Метод getFormElement

Синтаксис: объект.getFormElement(имя/номер-формы,имя/номер-элемента[,игнорировать_ошибки]?); Аргументы: имя/номер-формы — любое строковое выражение имя/номер-элемента — любое строковое выражение игнорировать_ошибки — логическое выражение Результат: JavaScript-объект - обертка элемента

Метод getFormElement возвращает ссылку на обертку элемента с указанным именем или порядковым номером у заданной формы. Аналогично методу getForm здесь не используются средства DOM.

Метод getImage

Синтаксис: объект.getImage(ID/имя-рисунка[,игнорировать_ошибки]?); Аргументы: ID/имя-рисунк — любое строковое выражение игнорировать_ошибки — логическое выражение Результат: JavaScript-объект - обертка элемента

Метод getImage возвращает ссылку на обертку элемента с указанным ID или именем. В отличие от метода getElement здесь вместо средств DOM используется встроенный объект document.images.

Методы getElmWrapper, getElementWrapper

Синтаксис: объект.getElmWrapper(html-объект); или объект.getElementWrapper(html-объект); Аргументы: html-объект — объект html-кода Результат: JavaScript-объект - обертка элемента

Методы getElmWrapper, getElementWrapper являются синонимами и возвращают ссылку на обертку элемента переданного им как аргумент.

Метод makeElement

Синтаксис: объект.makeElement(Название тэга[,атрибуты,дочерний элемент]?); Аргументы: Название тэга — любое строковое выражение атрибуты — объект формата JSON дочерний элемент — DOM-объект, или его обертка, или строковое выражение Результат: JavaScript-объект - обертка элемента

Метод makeElement создает новый DOM-объект и возвращает обертку на него.
Если передан аргумент "атрибуты" в формате: {"attrName1":"attrValue1","attrName2":"attrValue2",...}, то они сразу будут присвоены созданному объекту.
Если передан аргумент "дочерний элемент", то он так-же будет внесен в созданный объект. Если в качестве третьего аргумента передано строковое выражение, то из него будет автоматически создан текстовый узел и аналогичным образом внесен в созданный объект.

Метод getCloneElement

Синтаксис: объект.getCloneElement(ID-элемента[,игнорировать_ошибки]?); Аргументы: ID-элемента — любое строковое выражение игнорировать_ошибки — логическое выражение Результат: JavaScript-объект - обертка элемента

Метод getCloneElement оень похож на getElement с той лишь разницей, что данный метод возвращает ссылку на обертку не самого элемента с указанным ID, а на обертку его клона.

Хочу обратить внимание на два момента:

атрибут ID у клона удаляется, т.о. у вас не возникнет конфликтных ситуаций из-за того что при повторных запросах у вас может появится более одного элемента с одинаковым Id;
для того чтобы элемент можно было использовать его надо обязательно поместить в html-код при помощи средств DOM (именно сам элемент, а не его обертку полученную при помощи данной функции).

Метод getDocFrame

Синтаксис: объект.getDocFrame(); Результат: JavaScript-объект

Метод getDocFrame возвращает ссылку на объект documentElement.

Метод getWindowLeft

Синтаксис: объект.getWindowLeft(); Результат: числовое значение

Метод getWindowLeft возвращает значение (в пикселах) координаты верхнего левого угла окна, относительно экрана, по горизонтали.

Метод getWindowTop

Синтаксис: объект.getWindowTop(); Результат: числовое значение

Метод getWindowTop возвращает значение (в пикселах) координаты верхнего левого угла окна, относительно экрана, по вертикали.

Метод getWindowWidth

Синтаксис: объект.getWindowWidth(); Результат: числовое значение

Метод getWindowWidth возвращает ширину окна (в пикселах).

Метод getWindowHeight

Синтаксис: объект.getWindowHeight(); Результат: числовое значение

Метод getWindowHeight возвращает высоту окна (в пикселах).

Метод getDocumentWidth

Синтаксис: объект.getDocumentWidth(); Результат: числовое значение

Метод getDocumentWidth возвращает ширину документа (в пикселах).

Метод getDocumentHeight

Синтаксис: объект.getDocumentHeight(); Результат: числовое значение

Метод getDocumentHeight возвращает высоту документа (в пикселах).

Метод getScrollX

Синтаксис: объект.getScrollX(); Результат: числовое значение

Метод getScrollX возвращает значение скроллинга (в пикселах) по горизонтали.

Метод getScrollY

Синтаксис: объект.getScrollY(); Результат: числовое значение

Метод getScrollY возвращает значение скроллинга (в пикселах) по вертикали.

Метод createStyle

Синтаксис: объект.createStyle(selector,style[,index]?); Аргументы: selector — любое строковое выражение style — любое строковое выражение index — числовое значение

Метод createStyle позволяет создавать новые селекторы стилей.
Строка selector — селектор, например: div b, .someClass или #top.
Строка style — описание стиля, например color: #000 или border: 1px solid #F00.
Число index — номер в коллекции, которое займёт это правило (По умолчанию идет добавление в последнюю коллекцию).

Метод loadStyle

Синтаксис: объект.loadStyle(url); Аргументы: url — любое строковое выражение

Метод loadStyle позволяет загружать дополнительные таблицы стилей с указанного URL.

Метод getCookie

Синтаксис: объект.getCookie(name); Аргументы: name — любое строковое выражение Результат: строковое выражение

Метод getCookie позволяет получить значение куки с указанным именем. Если запрашиваемого значения не существует - метод возвращает значение null

Метод setCookie

Синтаксис: объект.setCookie(name,value[,expires,path,secure]?); Аргументы: name — любое строковое выражение value — любое строковое выражение expires — любое строковое выражение path — любое строковое выражение secure — любое строковое выражение

Метод setCookie позволяет установить значение куки с указанным именем.

ToDo: описать использование cookieExtra и конфига.

Метод deleteCookie

Синтаксис: объект.deleteCookie(name[,path]?); Аргументы: name — любое строковое выражение path — любое строковое выражение

Метод deleteCookie позволяет удалить значение куки с указанным именем.

Метод getSid

Синтаксис: объект.getSid(); Результат: строковое выражение

Метод getSid позволяет получить значение session ID. Имя сессии может быть получено как из куки, так и из Get-запроса. Имя переменной, которая используется для передачи session ID - задается в конфиге wrapper.

Метод setSid

Синтаксис: объект.setSid(value); Аргументы: value — любое строковое выражение

Метод setSid позволяет изменить значение session ID.

Метод getClosedFunction

Синтаксис: объект.getClosedFunction(object,method[,arguments]?); Аргументы: object — любой объект method — любое строковое выражение arguments — любой массив Результат: объект типа function

Метод getClosedFunction позволяет получить специальную функцию-замыкание, при вызове которой будет вызван метод указанного Вами объекта. При необходимости в этот метод будут переданы аргументы заданные здесь в виде массива. Что такое замыкание - Вы подробно можете прочитать здесь. Как правило, эту процедуру Вам придется вызывать для передачи сформированной функции в качестве аргумента в другую функцию, если Вам надо сохранить связь с конкретным объектом.

Метод setTimeout

Синтаксис: объект.setTimeout(time,object,method[,arguments]?); Аргументы: time — числовое значение object — любой объект method — любое строковое выражение arguments — любой массив Результат: объект типа timer

Метод setTimeout позволяет вызвать метод указанного Вами объекта с задержкой на указанное время. При необходимости в этот метод будут переданы аргументы заданные здесь в виде массива. Объект, возвращаемый данным методом, может быть использован потом для сброса таймера clearTimeout(таймер).

Метод setInterval

Синтаксис: объект.setInterval(time,object,method[,arguments]?); Аргументы: time — числовое значение object — любой объект method — любое строковое выражение arguments — любой массив Результат: объект типа timer

Метод setInterval позволяет периодически вызвать метод указанного Вами объекта с указанным Вами периодом. При необходимости в этот метод будут переданы аргументы заданные здесь в виде массива. Объект, возвращаемый данным методом, может быть использован потом для сброса таймера clearInterval(таймер).

Метод openPopUp

Синтаксис: объект.openPopUp(object,method,url[,name,property]?); Аргументы: object — любой объект method — любое строковое выражение url — любое строковое выражение name — любое строковое выражение property — любое строковое выражение Результат: объект типа timer

Метод openPopUp позволяет Вам создать PopUp-окно, с последующим вызовом метода указанного Вами объекта для инициализации этого окна. Аргументы: url, name, property - будут переданы в стандартную JavaScript-функцию open(url,name,property), поэтому более подробно с форматом этих аргументов Вы можете познакомиться в описании к этой функции (например, здесь). После создания PopUp-окна будет вызван указанный Вами метод и в него будут передана, в качестве первого аргумента, ссылка на объект window этого окна. В вызванном методе Вы сможете создать новый wrapper для этого PopUp-окна, используя переданный аргумент и подписать его на события (например, на "onload" или на "onunload").

Метод setOnloadListener

Синтаксис: объект.setOnloadListener(object[,method]?); Аргументы: object — любой объект method — любое строковое выражение Результат: объект

Метод setOnloadListener позволяет подписаться на событие onLoad. Если второй аргумент не указан, то в момент возникновения события будет вызываться метод с названием "onload", в противном случае - будет вызываться указанный Вами метод. Также см. примечание.

Метод removeOnloadListener

Синтаксис: объект.removeOnloadListener(object[,method]?); Аргументы: object — любой объект method — любое строковое выражение

Метод removeOnloadListener позволяет убрать подписке на любые событие onLoad. Если в момент подписки Вы указывали второй аргумент, то для удаления этой подписки Вы также должны его указать.

Метод setOnUnloadListener

Синтаксис: объект.setOnUnloadListener(object[,method]?); Аргументы: object — любой объект method — любое строковое выражение Результат: объект

Метод setOnUnloadListener позволяет подписаться на событие onUnLoad. Если второй аргумент не указан, то в момент возникновения события будет вызываться метод с названием "onunload", в противном случае - будет вызываться указанный Вами метод. Также см. примечание.

Метод addListener

Синтаксис: объект.addListener(object,event[,method,useCapture]?); Аргументы: object — любой объект event — любое строковое выражение method — любое строковое выражение useCapture — булево значение Результат: объект

Метод addListener позволяет подписаться на любые события объектов window и document. Название события (event) может делаться либо полностью строчными буквами, либо в Венгерской нотации. Вы также можете опускать префикс "on" в названии события, если это будет определено в конфиге wrapper. Если третий аргумент не указан, то в момент возникновения события будет вызываться метод, название которого соответствует второму аргументу, в противном случае - будет вызываться указанный Вами метод. Аргумент: useCapture - в данной версии пока не используется, но в будущем с помощью него можно будет использовать либо "Capture", либо "Bubbling" в момент подписки. Также см. примечание.

Метод removeListener

Синтаксис: объект.removeListener(object,event[,method,useCapture]?); Аргументы: object — любой объект event — любое строковое выражение method — любое строковое выражение useCapture — булево значение

Метод removeListener позволяет убрать подписку на любые события объектов window и document. Список аргументов этого метода совпадает со списком аргументов метода Метод addListener и при удалении подписки Вы должны указать эти аргументы с точно такими же значениями, как и при подписке.

примечание ко всем методам, связанным с подпиской

Все методы связанные с подпиской возвращают Вам некий объект, не имеющий ни методов, ни свойств. Но вы можете задать этому объекту любые свойства. Затем в момент возникновения события этот объект будет передан методу, обрабатывающему событие в качестве второго аргумента (первым аргументом всегда идет объект event-wrapper). Таким образом, если у Вас один метод используется для обработки нескольких событий - вы можете таким способом передавать в него дополнительную информацию, которая будет иметь свои значения для каждой подписки.