Анатомия виджетов: манифест

Оригинал: https://windowsteamblog.com/blogs/windowsphone/archive/2009/08/12/widget-anatomy-the-manifest.aspx

Автор оригинального поста: Джордж Пераца (Jorge Peraza)

Оригинальный пост опубликован 12 августа 2009 года

Это первый пост из серии, где мы планируем подробно описать все основные аспекты работы с фреймворком для виджетов в Windows Mobile 6.5.

Манифест виджета – это XML-файл, детально описывающий тот или иной виджет для Windows Mobile и поясняющий, что с этим виджетом можно делать. Это первый файл, к которому операционная система обращается при установке и запуске виджета, так что манифест исключительно важен, несмотря на то, что сам по себе он чрезвычайно прост.

Виджеты в Windows Mobile 6.5 базируются на стандарте W3C Widgets 1.0: Packaging and Configuration, датированном 22 декабря 2008 года. Пока этот стандарт продолжает эволюционировать, наша реализация обеспечивает обратную совместимость – есть всего несколько исключений, и мы расскажем о самых значимых из них в этой серии блог-постов. Чтобы немного сэкономить ваше время, я не буду заставлять вас читать стандарт W3C, а скажу главное – чтобы виджет считался работающим, для него обязательно должен быть определен манифест, и файл манифеста должен называться config.xml. Формально манифест виджета может быть пустым, и при этом что-то даже будет установлено, поскольку все элементы файла config.xml не являются обязательными. Но, несмотря на это, я все же рекомендую вам определить хотя бы тот минимальный набор элементов, что представлен в примере ниже:

 <?xml version="1.0" encoding="utf-8" ?>
<widget xmlns="https://www.w3.org/ns/widgets"
        version="1.0"
        id="https://someSite.com/MyUniqueWidgetID">
  <name>My first widget</name>
  <content src="widget.htm" type="text/html" />
  <access network="true" />
  <icon src="icon.png"/>
  <icon src="icon.ico"/>
  <description>
    This is my first widget,
    it won't make a lot of money on the
    marketplace but at least is cute!
  </description>
  <author href="https://www.windowsphone.com/blog"
          email="jorgeperaza@hotmail.com">Jorge Peraza</author>
  <license>
    Example license (based on MIT License)
    Copyright (c) 2008 The Foo Bar Corp.
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
    OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  </license>
</widget>

Элемент “widget”: что заставляет меня… Меня?

Первый элемент, который я хотел бы детально разобрать, - это <widget>,
родительский элемент для всех остальных элементов конфигурации, и он может быть
определен только один раз. Для этого элемента может быть задано множество атрибутов,
но сейчас мы удостоим вниманием только два из них:

• version="1.0".
  Этот атрибут задает номер версии виджета и используется при установке нового виджета
  с тем же самым id, для проверки – следует ли разрешить обновление приложения или
  нет.
• id="https://someSite.com/MyUniqueWidgetID". Этот атрибут исключительно важен
  – он содержит уникальный идентификатор виджета, который используется фреймворком
  для идентификации установленных виджетов. Значением атрибута должен быть корректный
  URL, однако, этот URL не обязательно должен быть работающим.

Названия некоторых дочерних элементов, например, <name>,
<description>, <author>
и <license> говорят сами за себя, поэтому я не буду
нагонять на вас скуку и подробно их описывать. Видите, иногда я могу быть очень
милым :)

Вместо этого давайте поговорим о другом дочернем элементе, который наоборот очень
важен – это <content src="widget.htm" type="text/html" />, он сообщает фреймворку, какой
исходный файл следует загрузить для запуска виджета. Возможно, вы заметили, что
в атрибуте type указан MIME-тип… однако, в Windows Mobile 6.5 поддерживается только
тип "text/html", так что даже и не мечтайте!

Следующая интересная нам группа дочерних элементов – это <icon src="icon.png"/>,
позволяющая задать одну или несколько иконок для виджета. Иконки – это «лицо» виджета,
они делают его в какой-то степени уникальным. Однако существует несколько ограничений,
о которых создателям виджетов следует знать. Windows Mobile Professional (устройства
с сенсорными экраном) поддерживает иконки как в формате PNG, так и в формате JPG,
однако, Windows Mobile Standard (устройства без сенсорного экрана) поддерживает
иконки только в формате ICO (пожалуйста, не спрашивайте меня ни о чем :)). Поэтому,
чтобы виджет нормально выглядел на обеих платформах, я рекомендую вам включить иконки
во всех перечисленных форматах, но первыми указать файл PNG или JPG.

И наконец, давайте поговорим об элементе <access network="true" />,
который хоть и последний в моем списке, но не последний по важности. Этот элемент
необязательный, но если вы хотите получить доступ к ресурсам сети, элемент должен
быть определен, и атрибуту network
должно быть присвоено значение "true".
В противном случае, элемент можно пропустить, но имейте в виду, что доступа к сотовой
сети у виджета не будет, и к звонкам, соответственно, тоже.

Я потратил столько сил, определил все поля в манифесте… можно ли теперь получить
к ним доступ из моего виджета?

Я рад, что вы задали этот вопрос, и ответ на него – конечно да! Сделать это можно,
используя API метаданных виджета, доступ к которому любезно предоставляет объект
javascript “widget”. Ниже перечислены наиболее важные свойства, с помощью которых
можно получать нужную информацию из манифеста:

• widget.version
• widget.identifier
• widget.name
• widget.description
• widget.authorEmail
• widget.authorName
• widget.authorURL
• widget.height
• widget.width
• widget.locale

На сегодня это все. Продолжайте следить за обновлениями блога, мы будем публиковать
новую информацию, которая, надеемся, поможет вам писать виджеты с удовольствием!

Перевод: Светлана Шиблева