О зимлетах №4: Изучаем Definition File зимлета. Все самое популярное.

В этой статье рассмотрены две вещи: что такое XML файл и каков его создать; definition file зимлета, в котором хранится краткое описание его деятельности. Здесь приведены лишь самые популярные при разработке тэги. Чтобы узнать о менее известных тэгах, читайте статью "О зимлетах №5", где все подробно рассказано с большим количеством примеров.

Введение.

Привет, уважаемый читатель. В первых статьях мы были на Вы, но теперь, когда мы уже хорошо познакомились, я предлагаю перейти на Ты. Тем более, что ты уже программист зимлетов, а программисты общаются только на Ты!

И так, если ты читаешь эту статью, значит ты уже прочитал все предыдущие и тебя они заинтересовали, тебе захотелось узнать больше. Это похвально, а мне очень приятно, что смог тебя заинтересовать. В этой статье я расскажу о Definition File зимлета, а также о XML и какие бывают основные команды.

XML за 5 минут.

XML — это расширяемый язык разметки. Он очень удобен для описания различных структур данных. Написать программу на нем нельзя, но можно преподнести в красивой форме информацию почти любых типов.

Весь код XML состоит из тэгов. Что это такое? Это слово, заключенное в угловые скобки, например <zimlet>.

Бывают открывающие и закрывающие тэги:

  • <zimlet> - открывающий тэг;
  • </zimlet> - закрывающий тэг.

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

<zimlet>
    <contentObject>
    </contentObject>
</zimlet>

Однако, если вложенные тэги не планируются, то можно обойтись без пары открывающего и закрывающего тэгов (для этого необходимо поставить косую черту в конце имени тэга):

<zimlet />

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

<zimlet name="My Zimlet" version="1.0" description="Hello World Zimlet"></zimlet>

Последнее, о чем стоит сказать, так это о комментариях (частях кода, которые будет читать только человек, так как для компьютера они не представляют никакой ценности). Они оформляются очень просто:

<!-- Здесь можно писать все, что угодно! -->

Комментарии удобно использовать не только для документирования кода, но и для его форматирования. Например, тебе хочется удалить часть кода XML, но при этом не хочется его терять. В этом случае будет достаточно его просто закомментировать.

Иногда, чтобы различать тэги между собой, например, когда тэг в своем теле может иметь только определенный набор других тэгов и никакие другие, вводят уровни тэгов. Тэги, которые не входят ни в одно тело друго тэга называются тэгами первого уровня (или верхними тэгами), вложенные в них тэги — второго, и так далее.

Все, теперь ты знаешь XML. Просто, да? А название звучит грозно: «XML». По английски это eXtensible Markup Language.

Строим зимлет.

Теперь пришло время рассказать о всех тэгах, которые могут быть использованы в Definition File. Их довольно много. Для начала приведу их полный список:

  • <zimlet>
  • <summary>
  • <include>
  • <includeCSS>
  • <resource>
  • <handlerObject>
  • <serverExtension>
  • <contentObject>
  • <contextMenu>
  • <portlet>
  • <zimletPanelItem>
  • <param>
  • <menuItem>
  • <toolTip>
  • <matchOn>
  • <regex>
  • <onClick>
  • <onDoubleClick>
  • <canvas>
  • <dragSource>
  • <actionUrl>
  • <toolTipText>
  • <portletProperties>
  • <userProperties>
  • <property>
  • <item>

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

Стоит заранее сказать, что самым главным и всеобъемлющим тэгом является <zimlet>, то есть все остальные тэги должны быть вложенными в него или вложенными во вложенные в него (и так далее).

Полное описание всех тэгов можно найти здесь.

Тэг <zimlet>.

У тэга <zimlet> может быть три параметра:

Атрибут Обязателен/Необязателен Описание
name Обязателен Имя зимлета. Должно быть таким же, как имя ZIP архива зимлета. Должно быть уникальным среди всех установленных на твоем компьютере зимлетов.
version Обязателен Номер версии зимлета в двойных кавычках.
description Обязателен Небольшое описание, которое будет высвечиваться, например, при наведении мышкой на зимлет (только для тех, у которых есть визуальное представление).

В таблице ниже перечислены популярные тэги, которые можно вставлять непосредственно внутрь тэга <zimlet>:

Тэги необходимо указывать строго в таком порядке Имя Все тэги опциональны, но некоторые из них могут повторяться несколько раз Описание
1 <summary> Не более одного Расширенное описание зимлета
2 <include> Сколько угодно Файл Java Script, который необходимо подсоединить
2 <resource> Сколько угодно Сторонние файлы, которые требуются для работы
3 <handlerObject> Не более одного Объект Java Script, который будет вызван на этапе инициализации
4 <contentObject> Не более одного Определяет способ обработки контента
5 <userProperties> Не более одного Дополнительные настройки пользователя

Теперь перейдем к подробному описанию каждого тэга.

Тэг <summary>.

Данный тэг содержит подробное описание зимлета. Он не имеет параметров. В нем может быть указано, как работать с зимлетом, зачем он нужен и какие у него есть особенности.

Пример:

<summary>Этот зимлет поможет Вам собирать Gentoo из исходников всего за пару кликов!</summary>

Тэг <include>.

Данный тэг позволяет подгружать файлы с Java Script кодом. Если быть точнее, то лучше сказать «связывать код с зимлетом». Можно указывать как локальный файл, так и файл в интернете. Если указано несколько файлов, то они загружаются в порядке сверху вниз.

Пример:

<include>http://www.zimletland.su/supercode.js</include>
<include>alsogoodcode.js</include>

Тэг <resource>.

Тэг используется для загрузки различный дополнительных файлов в зимлет. Это могут быть картинки, тексты, документы или базы данных. Если файл указан в Definition File, то его проще использовать из Java Script файла. Конечно, можно не осуществлять предварительную загрузку файлов, а подгружать их непосредственно во время выполнения Java Script кода, но это считается плохим тоном.

Пример:

<resource>http://api.google.com/maps.jgif</resource>
<resource>image.gif</resource>

Тэг <handlerObject>.

Этот тэг необходимо указывать, если ты подключаешь Java Script файлы. В нем указывается «точка входа», то есть тот класс, конструктор которого будет вызван при инициализации зимлета.

Пример:

<handlerObject>com_zimbra_myzimletHandlerObject</handlerObject>

Тэг <contentObject>.

В этом тэге описывается, как обрабатывать различный контент в Zimbra: тело сообщения, заголовок, заметка в записной книжке. Внутрь этого тэга необходимо поместить следующие тэги (подробней о них написано в следующей статье):

Тэги необходимо указывать строго в таком порядке Имя Все тэги опциональны, но некоторые из них могут повторяться несколько раз Описание
1 <matchOn> Не более одного Определяет правило, при котором будут выполняться дальнейшие действия
2 <onClick> Не более одного Действие при нажатии на соответствующую ссылку, которая удовлетворяет правилу, указанному в тэге <matchOn>
3 <toolTip> Не более одного Появление подсказки при наведении мышкой на соответствующую ссылку, которая удовлетворяет правилу, указанному в тэге <matchOn>
4 <contextMenu> Не более одного Пункт меню, появляющийся при нажатии правой кнопкой мыши на соответствующую ссылку, которая удовлетворяет правилу, указанному в тэге <matchOn>

У тега есть все один опциональный параметр type, который носит описательный характер и никак не влияет на выполнение зимлета.

Пример:

<contentObject type="mytype">
    <matchOn>
        <regex attrs="ig">lab|user|remodel|zimbra</regex>
    </matchOn>
    <toolTip>Hello World! Tool Tip</toolTip>
</contentObject>

Итог.

Мы рассмотрели все самые популярные тэги в этой статье. Есть еще небольшое множество тэгов, о которых тоже стоит знать. О них рассказано в следующей статье цикла, после прочтения которой ты уже сможешь делать собственные зимлеты полностью самостоятельно!

920