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, а на обертку его клона.

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

  1. атрибут ID у клона удаляется, т.о. у вас не возникнет конфликтных ситуаций из-за того что при повторных запросах у вас может появится более одного элемента с одинаковым Id;
  2. для того чтобы элемент можно было использовать его надо обязательно поместить в 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). Таким образом, если у Вас один метод используется для обработки нескольких событий - вы можете таким способом передавать в него дополнительную информацию, которая будет иметь свои значения для каждой подписки.