Frontview Add-on – это программный модуль, который можно инсталлировать на ReadyNAS для расширения сервисов, вызываемых через Frontview. add-on может содержать демон сервиса с элементом управления, который выводится в Frontview. Если в Frontview открыть страницу Services → Installed Add-ons, то будет показаны два уже инсталлированных add-on — BitTorrent и ReadyNAS Photos.
Пользователи могут включать и отключать add-on, ставя флажок в соответствующем поле, и на странице Installed Add-ons изменять конфигурацию add-on либо открывать новую страницу.
Начало
Для начала мы создадим, упакуем и протестируем простой add-on, а затем поясним, что делает каждый компонент add-on и где нужно сохранять изменения.
До начала программирования Frontview add-on рекомендуется ознакомиться со следующими дисциплинами:
- Linux shell environment и скрипты shell
- Программирование Web 2.0 (HTML, Javascript, XML, AJAX)
- Perl или C для поддержки CGI back-end
Потребуется RAIDiator версии 4.1.3 или более поздней.
Для создания нашего первого add-on нужно выполнить четыре шага.
Шаг 1: Загрузка Frontview Add-on SDK
Сначала нужно загрузить Frontview Add-on SDK. SDK содержит необходимые шаблоны для add-on, включая create script для быстрой разработки add-on и build script для упаковки add-on в нужный двоичный формат, который понимает Frontview.
Рекомендуется создавать и упаковывать add-on непосредственно на вашем ReadyNAS, но можно выполнить эту процедуру и на любой другой платформе Linux. Если вы выбрали первый вариант, то настройте доступ по SSH, а также свое рабочее окружение. Инструкции по этим операциям можно найти здесь.
Щелкните по следующей картинке для загрузки Add-on SDK. Он записан в формате tar-gzip, поэтому можно щелкнуть правой кнопкой и сохранить этот архив.
Для извлечения файлов перейдите в пустой каталого и запустите следующую команду:
# tar xvzf addon_sdk.tgz
Выведется следующий список файлов:
README
bin/build_addon
bin/create_addon
bin/xmlutil.sparc
bin/xmlutil.x86
template/language/de/ADDON.str
template/language/en-us/ADDON.str
template/language/fr/ADDON.str
template/language/ja/ADDON.str
template/language/ko/ADDON.str
template/language/zh-cn/ADDON.str
template/language/zh-tw/ADDON.str
template/ADDON.conf
template/ADDON.html
template/ADDON.js
template/ADDON.xml
template/ADDON_HANDLER.pl
template/ADDON_service
template/install.sh
template/remove.sh
template/running.sh
template/start.sh
template/stop.sh
Шаг 2: Создание шаблона для Add-on
У вас подготовлено окружение add-on SDK и теперь можно создавать с помощью SDK простой add-on. Первый наш add-on не будет ничего делать — мы только убедимся, что его можно инсталлировать, он виден в Frontview и его можно удалить.
Из базового каталога SDK введите следующую команду:
# bin/create_addon
Команда задаст вам серию вопросов о add-on и создаст нужные файлы шаблонов для построения add-on. Если вы неправильно ответите на какой-то вопрос, то запустите команду снова. Эту утилиты нужно запустить только один раз для создания необходимых исходных файлов, которые позднее можно модифицировать. Помните, что ее повторный запуск с тем же именем add-on приведет к перезаписыванию исходных файлов.
При создании add-on на консоли выведется:
Welcome to the Frontview Add-on Wizard
Enter a name for the add-on (please keep it short): Foo Bar
FOOBAR will be used as the tag for the add-on and
will be used as the base name for your add-on files.
Is this okay? (y/n) y
Enter a brief description for “Foo Bar” (no single quotes):This is the best add-on ever created for the ReadyNAS. Everyone will be so thrilled to see what this add-on does.
Description will read:
This is the best add-on ever created for the ReadyNAS. Everyone will be so thrilled to see what this add-on does.
Is this okay (y/n) y
Enter the version of the add-on [1.0]:
Version: 1.0
Is this okay (y/n) y
If you would like to make changes to your input, please make them in FOOBAR.xml. A base source code tree has been generated using the information that you provided. You’ll find the following files
FOOBAR/install.sh
FOOBAR/remove.sh
FOOBAR/start.sh
FOOBAR/stop.sh
FOOBAR/running.sh
FOOBAR/FOOBAR.html
FOOBAR/FOOBAR.js
FOOBAR/FOOBAR.xml
FOOBAR/FOOBAR_HANDLER.pl
FOOBAR/FOOBAR.conf
FOOBAR/language/en-us/FOOBAR.str
FOOBAR/language/de/FOOBAR.str
FOOBAR/language/fr/FOOBAR.str
FOOBAR/language/ja/FOOBAR.str
FOOBAR/language/ko/FOOBAR.str
FOOBAR/language/zh-cn/FOOBAR.str
FOOBAR/language/zh-tw/FOOBAR.str
After you make appropriate changes to the files above, you can build your add-on with build_addon. You need to be in the FOOBAR directory and run ../bin/build_addon.
заглавными буквами без пробелов. В нашем примере создается add-on с именем “Foo Bar” и его тэг будет “FOOBAR”.
После завершения этой операции исходные файлы add-on будут помещены в каталоге тэгов.
Шаг 3: Построение первого Add-on
Теперь можно преобразовать исходные файлы add-on в двоичне. Для этого нужно перейти в каталог add-on. Выполните следующие команды (они относятся к примеру с “Foo Bar” add-on).
# cd FOOBAR
# ../bin/build_addon
Successfully built "Foo Bar" add-on package as "FooBar_1.0.bin".
Команда build_addon используется каждый раз, когда нужно заново создать образ add-on с изменениями. Ее результатом будет файл addon.bin в вашем каталоге add-on. Этот файл будет распознан Frontview как add-on когда вы выгрузите его из закладки System → Update → Local .
Шаг 4: Тестирование Add-on
Теперь загрузим новый add-on из System → Update → Local.
После щелчка по Perform System Update, дождитесь подтверждения инсталляции add-on и затем откройте закладку Services → Installed Add-ons . Вы увидете, что новый add-on инсталлирован.
Поздравляем с созданием вашего первого Frontview add-on!
Понимание скриптов обслуживания
До сих все было просто. Теперь детально рассмотрим каждый компонент исходника и станет ясно, как нужно модифицировать FOOBAR add-on для получения реального add-on. Сначала рассмотрим скрипты для shell.
install.sh
Этот скрипт выполняет необходимые настройки для инсталляции add-on. Скрипт добавляет две переменные тэга в into /etc/default/services для того, чтобы проверить инсталлирован ли add-on и включен ли он. Для FOOBAR добавляются следующие переменные:
FOOBAR_SUPPORT=1
FOOBAR=1
FOOBAR_SUPPORT говорит Frontview, что FOOBAR add-on инсталлирован, а FOOBAR=1 говорит Frontview, что FOOBAR add-on включен.
Обычно содержимое install.sh не нуждается в модификации. Изменения могут потребоваться для обеспечения правильной инсталляции add-on (например, добавление учетной записи пользователя, создание базы данных и т.п.)
remove.sh
Этот скрипт удаляет add-on и затем сам удаляется. Необходимо указать в CONF_FILES список конфигурационных файлов, используемых add-on чтобы их можно было удалить. Вы также можете добавить программные файлы, которые нужно удалить, в PROG_FILES.
Если вы модифицировали какой-то файл конфигурации системы или создали базу данных, то их нужно правильно очистить в этом скрипте. Рекомендуется не оставлять никаких следов от add-on. Записи add-on, добавленные в /etc/default/services через install.sh, автоматически удаляются.
start.sh
Этот скрипт запускает сервис add-on. Он может быть похож на скрипты запуска, записанные в /etc/init.d. Альтернативный способ — использование команд демонов запуска и остановки start-stop-daemon , например
start-stop-daemon –start -b -m –pidfile /var/run/FOOBAR.pid –quiet –exec FOOBAR_service
FOOBAR_service – это пример скрипта shell, эмулирующего реальный сервис. Все что он делает — это заставляет систему заснуть на заданное число секунд. Вы можете заменить контент или переименовать этот сервис по своему желанию.
stop.sh
Аналогично скрипту start.sh скрипт stop.sh останавливает сервис add-on. Если для запуска сервиса вы использовали start-stop-daemon, то остановить его можно той же командой, например
start-stop-daemon –stop –pidfile /var/run/FOOBAR.pid –signal QUIT –quiet
В скрипте stop.sh нужно использовать тот же файл .pid, который используется в start.sh.
running.sh
Этот скрипт проверяет, работает ли сервис add-on выдает 0 если так и есть и отличное от нуля значение если сервис остановлен. Этот скрипт говорит Frontview какой светодиод горит для add-on – зеленый или серый.
Обычно здесь только требуется проверить, работает ли процесс. Можно установить в скрипте переменную ADDON_PROCESS на имя процесса или, если требуется больше, внести необходимые изменения в скрипт.
Понимание исходных файлов
Теперь посмотрим на остальные файлы
FOOBAR.html
Файл add-on HTML содержит элемент UI, который отображается во фрейме управления add-on. Отметим, что только содержимое внутреннего поля контролируется файлом HTML и не используется стандартные управляющие элементы add-on framework (например, версии, флажки и кнопки Remove and Save). Содержимое этого файла HTML должно работать координировано с файлом add-on Javascript (FOOBAR.js) и Perl (или не-Perl) CGI handler (FOOBAR_HANDLER.pl).
Если файл HTML отсутствует, то серая рамка и ее содержимое внутри фрейма add-on не будут отображаться.
FOOBAR.js
Файл add-on Javascript автоматически включается в Frontview add-on framework и определенные в этом файле функции вызываются из файла add-on HTML.
FOOBAR.xml
Помните, как мы запускали команду create_addon ? Она автоматически генерирует FOOBAR.xml на основе информации, которую вы ввели.
<?xml version="1.0" encoding="UTF-8" ?>
<addon>
<name>FOOBAR</name>
<friendly_name>Foo Bar</friendly_name>
<version>1.0</version>
<get_url>FOOBAR_HANDLER.pl</get_url>
<set_url>FOOBAR_HANDLER.pl</set_url>
<preaction>FOOBAR_preaction</preaction>
<onloadaction>FOOBAR_onloadaction</onloadaction>
</addon>
Допустимые тэги для addon:
name - имя тэга для add-on
friendly_name – имя add-on name, которое было указано для create_addon
version - версия add-on, которая была указана для create_addon
get_url – handler, который возвращает данные XML для HTML-страницы
set_url – handler, выполняющий обработку форм для HTML-страницы
preaction - функция Javascript (в FOOBAR.js), которая вызывается до загрузки HTML-страниц
onloadaction - функция Javascript (в FOOBAR.js), которая вызывается после загрузки HTML-страницы
language/*/FOOBAR.str
Frontview использует тэги строк для всех своих строк и аналогичным образом так же действуют Frontview add-ons. Это обеспечивает гибкость при работе с разными языками. Как вы видите, при запуске create_addon генерируются следующие файлы string map:
language/en-us/FOOBAR.str
language/de/FOOBAR.str
language/fr/FOOBAR.str
language/ja/FOOBAR.str
language/ko/FOOBAR.str
language/zh-cn/FOOBAR.str
language/zh-tw/FOOBAR.str
Формат таблиц файлов string map (например, FOOBAR.str) следующий:
PREFIX_STRINGTAG1::::String1 Text
PREFIX_STRINGTAG2::::String2 Text
Frontview использует соглашение о тэгах строк, которые должны состоять из заглавных букв, за который идут 4 двоеточия, а за ними — соответствующий текст. Определения тэгов разделяются символом новой строки. Имена тэгов даются в соответствии с правилом Frontview — префикс, за которым идет описание тэга. Префикс может быть PROMPT, LABEL, SUCCESS или ERROR.
PROMPT - Текст приглашения слева от поля ввода. Обычно эти тэги завершаются двоеточием.
LABEL - Текст метки — это текст произвольного формата с описанием, инструкцией и т.п.
SUCCESS - Текст, который информирует об успешном выполнении операции.
ERROR - Текст, информирующей о возникновении ошибке при выполнении операции.
Теперь рассмотрим файл language/en-us/FOOBAR.str.
LABEL_SERVICE_FOOBAR_INFO::::<b>Foo Bar.</b> This is the best add-on ever created for the ReadyNAS. Everyone will be so thrilled to see what this add-on does.
PROMPT_FOOBAR_RUNTIME_SECS::::Run-time (in secs):
Наверное, вы заметили, что все файлы FOOBAR.str за исключением хранящихся в каталогах en-us и ja, – это пустые файлы. Это демонстрирует, насколько просто можно организовать поддержку локализованной версии вашего add-on. При простом изменение настроек языка браузера с English на другой поддерживаемый язык add-on будет выводится на этом языке. Поскольку у нас имеется строгое определение для японского языка, то изменение языка браузера на японский даст такой результат:
Описание add-on по-прежнему выводится на английском, но приглашение теперь выводится на японском. Если посмотреть файл language/ja/FOOBAR.str, то видно, что на японский переведена только подсказка.
LABEL_SERVICE_FOOBAR_INFO::::<b>Foo Bar.</b> This is the best add-on ever created for the ReadyNAS. Everyone will be so thrilled to see what this add-on does.
PROMPT_FOOBAR_RUNTIME_SECS::::実行時間 (秒):
FOOBAR.conf
Этот файл используется Apache для того, чтобы разрешить выполнение add-on handler. Этот файл не надо менять.
FOOBAR_HANDLER.pl
Это Perl handler, который обрабатывает операции с кнопками Save и Remove из add-on. Этот handler представлен как пример обработки команд и полученные в результате данные XML возвращаются на HTML-страницу add-on. Обработка XML-данных выходит за рамки этой статьи, но вы можете использовать эти и другие add-on Perl чтобы выяснить, как это происходит.
Необязательно писать add-on handler только на Perl — можно использовать и C. Нужно только определить handler в XML-файле add-on (см. далее). Мы рекомендуем использовать Perl как front-end для двоичного кода на C если вы предпочитаете именно этот языка, поскольку сейчас библиотечные вызовы для удаления, разрешения и блокировки add-on доступны только для Perl.
Рассмотрим исходный код.
Сначала в следующие файлы нужно включить определения и общие функции add-on.
do "/frontview/lib/cgi-lib.pl";
do "/frontview/lib/addon.pl";
Чтение в %in hash всех исходных переменных форм, полученных от команды HTML submit.
# initialize the %in hash
%in = ();
ReadParse();
Получение запрошенной информации. $operation – это get или set. $command может иметь 3 значения— RemoveAddOn, ToggleService, или ModifyAddOnService. Мы кратко объясним эти команды.
my $operation = $in{OPERATION};
my $command = $in{command};
my $enabled = $in{"CHECKBOX_FOOBAR_ENABLED"};
Чтение в строке language string файлы для этого add-on. Это настроит язык браузера и вызовет нужный файл string map.
get_default_language_strings("FOOBAR");
Инициализаци XML payload заголовком. Мы присоединим к этой переменной payload позднее.
my $xml_payload = "Content-type: text/xml; ...?>";
Если операция – get, то Show_FOOBAR_xml() возвратит XML payload для контейнера add-on. Обычно при этом передается конфигурация add-on, поэтому это будет отображаться при загрузке страницы add-on.
if( $operation eq "get" )
{
$xml_payload .= Show_FOOBAR_xml();
}
Если операция – set, то обрабатываются возможные команды set. Предопределенные вызовы Remove_Service_xml и Toggle_Service_xmlare будут удалять add-on и переключаться в зависимости от того, включен ли add-on. Modify_FOOBAR_xmlcall определен в этом файле для обработки изменений формы ввода и его можно модифицировать в зависимости от ваших потребностей.
elsif( $operation eq "set" )
{
if( $command eq "RemoveAddOn" )
{
# Remove_Service_xml() removes this add-on
$xml_payload .= Remove_Service_xml("FOOBAR");
}
elsif( $command eq "ToggleService" )
{
# Toggle_Service_xml() toggles the enabled state of the add-on
$xml_payload .= Toggle_Service_xml("FOOBAR", $enabled);
}
elsif( $command eq "ModifyAddOnService" )
{
# Modify_FOOBAR_xml() processes the input form changes
$xml_payload .= Modify_FOOBAR_xml();
}
}
Если нужно выполнить команду shell с правами root, то используйте функции spool_file() и empty_spool(), например:
$SPOOL .= "
df -h > /tmp/df.out
";
spool_file("${ORDER_SERVICE}_FOOBAR", $SPOOL);
empty_spool();
Эта команда сделает спулинг команд shell из $SPOOL в файл /var/spool/frontview/60_FOOBAR (${ORDER_SERVICE} is 60). При вызове empty_spool() файл будет выполнен из-под root. Используйте спулинг осторожно — ошибка root может привести к потере данных.
Если у вас возникнут вопросы по SDK, то разместите их на форуме ReadyNAS Developer Network forum.
