amiJSAPI
amiJSAPI содержит как
объекты, расширяющие возможности Javascript, так и классы, которые необходимы
для работы со страницами и взаимодействия с плагинами.
JS API необходим для отображения данных,
полученных с сайта, без перезагрузки страницы. Для этого:
- По
запросу страницы Amiro.CMS строит её из спецблоков и данных текущего модуля. Спецблоком
может быть так же элемент JS API. Он представляет собой плагин, который выводит
все необходимые HTML данные для начала асинхронной работы спецблока.
- Изначально
выводится страница, содержащая блоки, обслуживаемые JS
API. Содержимое этих блоков, как правило, состоит из:
-
HTML кода блока
по-умолчанию;
-
HTML шаблонов, небходимых
для оформления данных, из которых состоит блок. Шаблоны для JavaScript
функционала хранятся в том же шаблоне системы, где все сеты, отображающие
содержимое спецблока. Каждый шаблон для JS API. Конструкции @@, используемые в
JS шаблоне игнорируются PHP шаблонизатором. Для вывода шаблона в HTML код
страницы используется тэг SCRIPT с атрибутом type=”text/html ”.
-
JavaScript, содержащего
основные параметры блока и инициализацию необходимого компонента JS API.
-
Как
только показано содержимое по-умолчанию API
отправляет
запрос на сервер (AMI.HTTPRequest) для получения необходимой порции
данных.
-
При
получении данных JavaScript компонент
вставляет их в необходимый шаблон (AMI.Template) и строит содержимое блока.
-
На
всех этапах API отправляет сообщения для зарегистрированных
объектов-слушателей на дополнительную обработку данных (AMI.Message).
Amiro JS API
полностью готов для создания собственных интерфейсов пользователей. Тем не
менее в объекте AMI.UI созданы несколько уже готовых компонент
пользовательского интерфейса для работы со страницей. Это:
- AMI.UI.Suggestion – подсказки для
введённой пользователем строки в текстовом поле.
- AMI.UI.MediaBox – показ media-объектов
на странице, таких как картинки, FLASH в отдельном
слое на странице.
- AMI.UI. Multiselect – замена
стандартного <select multiple=”multiple”> на графический контрол.
- AMI.UI.List – Объект,
предназначенный для работы со списочным блоком данных, таким как обыкновенный
спецблок.
Схема работы JS API на примере AMI.UI.List:

Рисунок 1
Для того чтобы упростить работу с готовыми объектами и не использовать постоянно длинные цепочки при вызове методов можно сделать переопределение объекта и работать уже с новым. Например: <script type="”text/javascript”"> var myEvent = new Object(); myEvent.prototype = AMI.Browser.Event; myEvent.set(‘var’, ‘value’, 1); </script>
AMI
– объект (далее контейнер), который содержит в себе все классы и объекты для
работы с amiJSAPI. API так же включает
в себя AMI.Browser, который содержит набор вспомогательных
функций, предоставляющих стандартный доступ к параметрам и свойствам страниц
одинаково подо всеми браузерами.
AMI.Browser – контейнер,
который содержит в себе объекты и функции, которые предназначены для стандартизации
работы с параметрами страниц, такими как определение размеров или позиций, под
всеми браузерами. Методы объекта:
AMI.Browser.Cookie – объект, в
котором хранятся методы для работы с cookie браузера.
- void set(sName, sValue, iHours) – установка
переменной cookie sName в значение sValue на заданный период iHours.
- void get(sName) – получение
значения переменной cookie sName.
- void del(sName) – удаление
переменной cookie sName.
AMI.Browser.Event – объект,
который содержит в себе методы для работы с событиями браузера (onLoad, onClick, onMouseOver и т.п.).
- object validate(oEvent) – получение
корректного объекта события, основываясь на переданном объекте oEvent.
- void addHandler(oTarget, sEvent, oHandler) – установка обработчика
oHandler события sEvent
(без «on») для объекта oTarget.
oHandler должен быть функцией, которая будет
вызвана с параметром event.
- void removeHandler(oTarget, sEvent, oHandler) – удаление
обработчика oHandler события sEvent
для
объекта oTarget.
- void stopProcessing(oEvent) – остановка распространения
события oEvent по DOM модели родителям и выполнения
действия по-умолчанию.
- object getTarget(oEvent) – получение
объекта для которого было вызвано событие oEvent.
- boolfire(oTarget, sEvent) – вызов события sEvent для объекта oTarget
без участия пользователя.
AMI.Browser.DOM – объект, методы которого позволяют
работать с объектной моделью браузера более эффективно.
- object create(sTagName, sId, sClassName, sStyles, oParentNode) – создание элемента
в объектной модели по заданному тэгу sTagName с параметрами ID sId, классом sClassName и стилями sStyles.
Если задан родительский элемент oParentNode, то созданный элемент будетпомещён
последним в его объектной модели.
- object append(oParentNode, oNode) – удаление элемента oNode из объектной модели oParentNode.
- string getStyle(oObject, sStyleName) – определение значения стиля sStyleName для элемента oObject.
API
AMI.Message – объект для
работы с сообщениями, которые посылают различные методы amiJSAPI. Позволяет
регистрировать обработчиков сообщений и обрабатывать данные, присланные через
сообщения.
- void addListener(sMessage, oCallback) – добавление обработчика oCallback для определённого сообщения sMessage API. Функция oCallback
должна принимать 2 параметра (param1 и param2), которые передаются через сообщения. Параметры
передаются как объекты, т.е. ими можно манипулировать и это отразится в том
методе, который вызвал событие.
- void removeListener(sMessage, oCallback) – удаление обработчика oCallback для события sMessage.
- void send(sMessage, param1, param2) – создание
сообщения sMessage с последующим вызовом всех обработчиков.
В процессе работы изменяется переданный в метод объект param2, который
возвращается как результат обработки.
AMI.Template – объект для
работы с шаблонами: замена переменных в шаблоне на данные, взятые из
переданного методу массива. Шаблон поддерживает простые переменные и условия с
неограниченным уровнем вложенности.
Синтаксис шаблона.
- Переменные
в шаблоне заключаются между @@.
- Условный
блок начинается с @@if(условие)@@ и
заканчивается @@endif@@. Условный
блок может содержать @@else if(условие)@@ и @@else@@.
Условие аналогично таковому в Javascript, переменные берутся из массива,
передаваемого как параметр метода parse.
Пример
шаблона:
@@if(ext_img_small != "")@@ <img src="@@ext_img_small@@" alt="" /> @@endif@@ <div class="ami_resp_row_announce_news">@@announce@@</div>
AMI.String – объект для
работы со строками, специфичными для Amiro.CMS.
- string decodeHTMLSpecialChars(content) – замена в строке content закодированных специальных символов на
обычные, например # на #, <
на < и т.п.
- mixed decodeJSON(data) – восстановление
данных JavaScript, сериализованных в строку data.
AMI.HTTPRequest – класс, который
предназначен для асинхронной загрузки данных с того же домена, на котором
работает сайт. Так же этот класс позволяет отправлять данные формы в
параллельном потоке. В обоих случая регистрируется обработчик, который будет
вызван при получении данных.
- void addVariable(key, value) – установка переменной key
со значением value, которая будет отправлена на сервер с запросом.
- void getContent(method, url, variables, callbackFunction) – формирование запроса url на сервер
методом method (POST, GET) с переменными variables.
Как результат вызывается зарегистрированный обработчик callbackFunction,
которому параметром передаётся содержимое.
- void submitForm(url, callbackFunction) – отправка данных формы url на сервер с аналогичным getContent действием.
AMI.UI – класс,
который является базовым для всех UI классов и является их контейнером. Каждый
UI класс (компонент UI) – это самостоятельный компонент, содержащий набор
функций для обработки и представления данных, полученных с сервера. AMI.UI предоставляет
функционал, который одинаково необходим всем компонентам.
- processResponce – разбор ответа
от сервера, полученного на запрос, который создала одна из компонент AMI.UI. Метод
производит базовые операции, в т.ч. выдачу сообщения об ошибке или заполнения
статусного сообщения.
Входящие в поставку UI
AMI.UI.Suggestion – класс, необходимый для вывода
подсказок при вводе значения в текстовое поле.
Объект
работает на основе плагина ami_ajax_responder, где в качестве модуля
используется search_history.
Чтобы
подключить подсказки к текстовому полю необходимо для самого поля задать ID,
например, idSearchField и прописать атрибут autocomplete=”off”. Ниже вставить следующий JavaScript
код:
var suggestionRequestData = { id_plugin: 'ami_ajax_responder', locale: 'ru', module: 'search_history', order: 'quantity', dir: 'D', limit: '10', offset: '0' }; var searchVariants = new AMI.UI.Suggestion('idSearchField', suggestionRequestData);
Инициализация
объекта и расставление обработчиков событий происходит автоматически после
создания переменной, содержащей этот объект.
AMI.UI.MediaBox – объект для отображения медиа-данных,
таких как изображения, FLASH, FLV.
Объект
AMI.UI.MediaBox уже создан и готов к использованию,
создавать его заново с помощью new не нужно. Для
открытия изображения используется метод open.
- voidaddSkin (sSkin, aExtensions, iWidthAddon, iHeightAddon) – создание темы оформления для
определённых типов.
- sSkin
содержит класс стилей, который будет использован совместно с MediaBox (пример -
MediaBoxBlack).
- aExtensions – массив
расширений файлов, к которым будет применён стиль.
- iWidthAddon – добавочная ширина
для окна с медиа-файлом.
- iHeightAddon – добавочная
высота для окна с медиа-файлом.
- void open(imageUrl, imageWidth, imageHeight) – открытие окна
с медиа-файлом.
- imageUrl – ссылка на
изображение.
- imageWidth – ширина
медиа-файла. Если не задана, то окно будет автоматически подстроено под ширину
медиа-файла после его загрузки.
- imageHeight – высота
медиа-файла. Если не задана, то окно будет автоматически подстроено под ширину
медиа-файла после его загрузки.
AMI.UI.Multiselect – замена стандартного <select multiple=”multiple”>
на графический контрол.
Класс
AMI.UI.Multiselect необходим
для замены на странице стандартного select контрола с
множественным выбором на графический, которым можно манипулировать стилями.
Возможности объекта:
- Он заменяет
собой указанный встроенный контрол, вставая на ту же позицию и сохраняя те же
размеры (если не изменена высота ряда). Если задано количество видимых рядов (size=”X”), то контрол
адаптируется так же под этот размер.
- Для окна
контрола используется свой класс, так же как и для вариантов.
- Множественное
выделеные делается кликом мыши по каждому варианту. Удерживать кнопку SHIFT нет
необходимости.
- Возможность
выделять или снять выделение сразу с нескольких вариантов одним движением мыши,
кликнув на первом варианте и перетаскивая указатель мыши над остальными
вариантами, удерживая левую кнопку мыши нажатой.
Контрол
перед созданием инициализирует все необходимые данные, получает значения из
элемента select, к которому он привязан и после этого скрывает элемент select. Тем
не менее он манипулирует данными select и при отправке формы происходит
отправка данных оригинального select. Подключается
AMI.UI.Multiselect к нужному select следующим образом: <select name="someSelect[]" id="idSomeSelect" multiple="multiple" size="5"> <option value="1">Значение 1</option> <option value="2">Значение 2</option> </select> <script type="text/javascript"> var oSomeField = new AMI.UI.Multiselect('idSomeSelect') </script>
Параметры конструктора AMI.UI.Multiselect(selectld, iWidth, iRowHeight) следующие:
- string selectId – Обязателен. ID оригинального элемента select.
- int iWidth – ширина контрола. Если параметр не
задан, то будет задана ширина элемента select, из которого создаётся контрол.
- int iRowHeight – Высота одного ряда с вариантом. Если
для select задан параметр size, то высота
будет адаптирована под необходимое количество рядов.
Классы
стилей, служащие для оформления контрола:
- mSelectFrame
– окно контрола (DIV).
- mSelectOption
– ряд с невыбранным вариантом (DIV).
- mSelectOptionSelected – ряд с выбранным вариантом (DIV).
AMI.UI.List – класс для работы со списком: запрос
данных с сервера, разбор ответа, вывод списка по заданному шаблону. Данные для
списка загружаются из плагина в Amiro.CMS
- void showProgress() – отображение слоя с прогрессом.
- void hideProgress() – скрытие слоя с прогрессом.
- void load(lastAction) – загрузка содержимого
списка с текущими параметрами. lastAction может быть
опущет, т.е. нужен только для режима автообновления, по этому параметру система
опознаёт какое действие (previous, next, load) следует
прекратить в случае отстутствия данных в возвращённом ответе от сервера. При
этом, если по результатам загрузки скрывается кнопка следующей страницы, то
отправляется сообщение ON_AMI_LIST_NEXT_DISABLE, для открытия кнопки вновь
отправляется ON_AMI_LIST_NEXT_ENABLE. Те же сообщения для кнопки предыдущих страниц: ON_AMI_LIST_PREVIOUS_DISABLE
и ON_AMI_LIST_PREVIOUS_ENABLE.
- void onContentReceived(state, content) – колбэк-функция, вызываемая при получении данных content, от запроса, инициированного load(). Переменная state указывает тип ответа: 1 – успешный, остальные – нет.
- void setListData(aRowsData) – заполнение
рядов таблицы из массива данных. Перед заполнением каждого ряда отправляется
сообщение ON_AMI_LIST_DRAW_ROW с массивом данных для одного ряда в качестве
второго параметра.
- void previousPage() – запрос на отображение предыдущей
страницы.
- void nextPage() – запрос на отображение следующей
страницы.
- void playPause(forceAction) – переключение между режимом
автообновления и остановки. Если указан режим в параметре forceAction (play
или pause), то он принудительно установится.
Объект
AMI.UI.List является самым частоприменяемым. Далее будет рассмотрен пример
создания новостного блока на странице с использованием этого объекта.
Как создать свой HTML блок, отображающий данные модуля новости (news), используя объект AMI.UI.List.
Для
использования такого плагина необходимо на странице добавить блок HTML кода, в который контроллер будет вставлять полученные
данные.
<div id=”ami_resp_outer_News”> <div id="amiNavNews"> <!--Элементы управления, если необходимо, которые не будут затронуты системой, но будут скрыты при запросе на сервер--> </div> <div id="amiProgressNews"> <!--Содержимое блока, который отображается в момент запроса данных с сервера (лоадер), если этого блока нет, то будет создан блок по-умолчанию автоматически--> </div> <div id="amiContainerNews"> <!--Блок, в котором будет построено содержимое таблицы--> </div> </div>
Вместо
«News» можно поставить свои идентификаторы, по которым
контроллер сможет определить «свои» объекты. Важно чтобы готовые ID не повторялись на странице. Содержимое,
которое выводится в блоки по указанным ID или заполняется при создании макета (ID, отмеченные
жирным шрифтом заполняются вручную):
- amiNav{postfix} – заполняется
вручную. Блок с элементами управления списка. Например, предыдущая, следующая
страницы, обновить страницу и т.п. В этом блоке возможно создавать элементы с ID amiNavPreviuosNews,
amiNavNextNews, amiNavPlayPauseNews. Для элементов с такими ID
автоматически
будут изменяться классы стилей при необходимости (скрытие, деактивирование и
т.п.).
- amiProgress{postfix} – заполняется вручную. Блок, который
выводится поверх блока с данными в момент, когда идёт загрузка. Если элемента
нет на странице, то он создаётся системой автоматически.
- amiContainer{postfix} – заполняется JS
API.
Блок, который заполняется рядами списка после получения данных.
После
этого блока должно быть определение объекта, который инициализируется из класса
AMI.UI.List. Пример: <script type=”text/javascript”> var parameters = { id_plugin: 'ami_ajax_responder', module: 'news', locale: 'ru' order: 'date', dir: 'D', limit: '20', offset: '0' id_page: 0 }; var oNewsBlock = new AMI.UI.List('News', parameters); oNewsBlock.load(); </script> <script type=”text/html” id=”templateRowNews”> <div>@@date@@ / @@header@@</div> </script>
Чтобы
включить автообновление блока, в массив parameters нужно добавить следующие
переменные:
- refreshInterval
– время в секундах между обновлениями
- refreshIntervalMultiplier
– множитель для интервала (увеличение в геометрической прогрессии).
- refreshNumber
– количество итерация обновления. Максимально – 50
- refreshType – тип перехода
на следующую порцию данных: next, previous, reload.
Первым
параметром при инициализации объекта указывается постфикс для ID блоков, вторым
– параметры, из которых будет составлен первый GET запрос. Сразу после
определения объекта ничего не произойдёт, запрос не будет сделан. Для того,
чтобы сделать сразу запрос и заполнить данными блоки делается вызов метода load().
Объект контроллера ищет блоки, с которыми он работает по перечисленным выше ID, приставив к ним постфикс, переданный первым
параметром. Аналогично ищется шаблон ряда с ID: templateRow{postfix} (в примере это – News, т.е. templateRowNews). Если любой
шаблон не будет найден, то он будет считаться равным пустой строке.
Для
загрузки списка вызывается метод load(). При загрузке
на сервер посылается запрос с указанными при инициализации данными. Сервер
формирует строку в формате JSON из массива данных, которые вернул плагин.
Клиентская
часть (Javascript) получает данные в формате JSON и
декодирует их в Javascript массив. Массив
имеет заранее определённый формат:
array( “code” => 0, // статус ошибки, 0 – если не было ошибки” // произвольные данные, которые будут доступны для //своей обработки “data” => array( “List” => array( array(‘date’ => ‘2009.12.31’, ‘header’ => ‘Скоро новый год’), array(‘date’ => ‘2010.01.12’, ‘header’ => ‘С новым годом!’), array(‘date’ => ‘2010.12.31’, ‘header’ => ‘Опять…’) ) );
После
декодирования данных AMI.UI.List строит ряды,
открывает и скрывает необходимые блоки, которые были указаны выше. Перед тем
как построить из шаблона очередной ряд контроллер посылает сообщение
ON_AMI_LIST_DRAW_ROW, параметром которого является массив с данными для шаблона
ряда. Для того, чтобы указать свои правила кодирования необходимо зарегистрировать
собственный обработчик этого события. Для этого после инициализации
дописывается соответственный Javascript код: function newsListListener(aData){ // Изменение данных для ряда aData[‘header’] = ‘<strong>’ + aData[‘header’] + ‘<strong>’; return aData; } AMI.Message.addListener('ON_AMI_LIST_DRAW_ROW', newsListListener);
Обработчиков
для одного сообщения может быть сколько угодно много. Так же можно
переопределить функцию, которая строит все ряды, чтобы самостоятельно заполнить
блок с данными модуля, имея полученные от сервера данные: oNewsBlock.setListData= function(aAllRowsData){ this.oListContent = ‘готовое содержимое блока списка’; }
Подключение библиотеки jQuery
Библиотека jQuery может быть получена из внешней CDN, полный путь к файлу указывается в разделе "Сервис" - "Настройка системы" - "Локализации" отдельно для каждой из локализаций.
В разделе администрирования сайта, доступ к функциям библиотеки
возможен через изолированный объект AMI.$, полностью соответствующий стандартному объекту jQuery той
же версии.
Пример:
AMI.$(document).ready(function(){ alert(‘Hello world!’); });
Изоляция
имени необходима для предоставления возможности подключения пользователем любой
другой версии библиотеки jQuery и исключения конфликтов, связанных с разницей
версий.
Дополнительная
библиотека jQuery UI не входит в поставку, и не может работать с объектом AMI.$. Для того, чтобы использовать
jQuery
UI на стороне раздела администрирования, ее необходимо
подключить вручную, и в месте ее подключения определить стандартные объекты jQuery:
<script> window.jQuery = window.$ = AMI.jQuery; </script> <script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.13/jquery-ui.min.js"></script>
Для того, чтобы использовать библиотеку jQuery на публичной
части, ее необходимо подключить вручную, для каждого из существующих макетов. Сделать
это можно в разделе “Макеты страниц”, на вкладке “Код для HEAD”.
При этом, для экономии трафика и ускорения времени загрузки
сайта, рекомендуется подключать jQuery из файловых хранилищ Google или Яndex, в зависимости от аудитории вашего
сайта.
Подключение из хранилища Google:
http://code.google.com/intl/ru/apis/libraries/devguide.html
Подключение из хранилища Яndex:
http://api.yandex.ru/jslibs/libs.xml
Пример подключения jQuery версии 1.4.2 из хранилища Google:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
|