Содержание

1. Что такое дополнения (plugin)?
2. Установка дополнения и их поддержка
3. Загрузка/Выгрузка дополнений
4. Опции дополнений
5. Написание дополнений
6. Переведено

1:   Что такое дополнения (plugin)?

Дополнения (pluginы) это фрагменты кода, которые позволяют модифицировать
работу приложения album. Вероятно создание дополнений - это
один из самых простых способов от создания новых элементов
EXIF комментариев до создания базы данных изображений, основанных
на собственном алгоритме иерархии, а не на иерархии файловой системы.

2:   Установка дополнения и их поддержка

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

% album -configure

Позже, при работе с приложением album, эту команду запускать еще раз не нужно.

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

  /etc/album/plugins/
  /usr/share/album/plugins/
  $HOME/.album/plugins/

Все эти папки для дополнений можно указать приложению при запуске с опцией 
'--data_path', но все же по умолчанию определено:

  /etc/album/
  /usr/share/album/
  $HOME/.album/

Иными словами вы можете указать новое расположение папок опцией
 --data_path, а затем добавить папку конкретного дополнения путем
указание пути к ней, через опцию --plugin_path.

Сами файлы дополнений обычно имеют префикс ".alp", при использовании
дополнения его указывать не нужно. К примеру, у вас есть дополнения, 
установленное в:

/etc/album/plugins/utils/mv.alp

То вам при обращении к нему можно просто указать:  utils/mv

3:   Загрузка/Выгрузка дополнений

Чтобы увидеть все установленные в данный момент времени дополнения
введите команду:

% album -list_plugins

А, чтобы посмотреть информацию об указанном дополнении (использующим
путь 'utils/mv'?, к примеру):

% album -plugin_info utils/mv

Дополнения будут сохранены как часть конфигурации для данной галереи,
поэтому не надо будет каждый раз их указывать по-новой при последующих
запусках, за исключением дополнений, которые работают однократно, таких 
как 'utils/mv')

Вы можете использовать опции -no_plugin и -clear_plugin для отключения
дополнений, которые уже сохранены как часть конфигурации приложения
album. Как и другие обычные опции, предназначенные для отключения 
чего-либо, опция -no_plugin отключит указанное дополнение, а -clear_plugin 
отключит все дополнения.  Любые опции, которые были указаны для дополнения,
будут стерты тоже.

4:   Опции дополнений

Сами дополнения способны воспринимать опции командной строки, чтобы посмотреть
использование можно ввести команду:

% album -plugin_usage utils/mv

Но когда указывают опции для дополнений, вам необходимо указать и то, 
к каккому дополнению имеет отношения данная опция, поэтому 
вместо обычного стиля указаний опций:

% album -some_option

При этом опция для дополнения отделяется двоеточием:

% album -some_plugin:some_option

К примеру, вы можете указать 'index' созданный дополнением
'utils/capindex', тогда следуюет ввести команду:

% album -plugin utils/capindex  -utils/capindex:index blah.html

Получается не очень коротко, но можно укоротить названия для
дополнения, при условии если он не будет конфликтовать с другим
названием другого дополнения (с тем же самым именем).

% album -plugin utils/capindex  -capindex:index

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

Одно предупреждение... Как было упомянуто выше, когда используется дополнения
они сохраняется в конфигурации приложения album. Если вы хотите добавить
опции, к приложению, которые обычно используются совместно с данным
дополнением, то необходимо либо упомянуть дополнение снова, либо
использоваться полное название когда указываются обычные опции.

К примеру, рассмотрим:

% album -plugin some/example/thumbGen Photos/Spain

Предположим, что после этого, необходимо использовать опцию "fast" для
thumbGen, то вот так ничего работать не будет работать:

% album -thumbGen:fast Photos/Spain

А вот это будет работать нормально:

% album -plugin some/example/thumbGen -thumbGen:fast blah.html Photos/Spain
% album -some/example/thumbGen:fast Photos/Spain

5:   Написание дополнений

Фактически дополнение - это маленькие программные модули perl, которые
"добавляются" в код приложения album.

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

Перечь все установленных модулей можно увидеть путем ввода команды:

% album -list_hooks

Так же вы можете получить дополнительную информацию о программном коде:

% album -hook_info <hook_name>

Мы можем использовать приложения album для генерации каркаса дополнения:

% album -create_plugin

Для этой работы, необходимо четко понимать как работает приложение, и,
что позволяют получить опции.

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

Регистрация дополнений, производится путем вызова функции album::hook().
Для вызова функций в кода приложения album, используется пространство
имен приложения album.
К примеру, для регистрации программного кода для clean_name 
дополнения hook производится вызов:

album::hook($opt,'clean_name',\&my_clean);

Затем если приложение album 
Then whenever album does a clean_name it will also call the plugin
subroutine called my_clean (which we need to provide).

To write my_clean let's look at the clean_name hook info:

  Args: ($opt, 'clean_name',  $name, $iscaption)
  Description: Clean a filename for printing.
    The name is either the filename or comes from the caption file.
  Returns: Clean name

Аргументы, которые соответствует подрограмме my_clean указаны
в первой строке. Если необходимо конвертировать их
в строчные буквам, то нужно использовать:

sub my_clean {
  my ($opt, $hookname, $name, $iscaption) = @_;
  return uc($name);
}

Объяснение аргументов:

$opt        Это обозначение для все опций приложения album.
            Здесь оно не используется. Но иногда оно может понадобится,
            если необходимо вызвать какую-либо встроенную функцию
            приложения album. Это же справедливо если использует аргумент
             $data.
$hookname   In this case it will be 'clean_name'.  This allows us
            to register the same subroutine to handle different hooks.
$name       This is the name we are going to clean.
$iscaption  This tells us whether the name came from a caption file.
            To understand any of the options after the $hookname you
            may need to look at the corresponding code in album.

In this case we only needed to use the supplied $name, we called
the perl uppercase routine and returned that.  The code is done, but now
we need to create the plugin framework.
 
Некоторые программные модули, позволяют заместить программный код
самого приложения album. К примеру, необходимос написать 
программный модуль, который будет генерировать иконки
предпросмотра для pdf файлов (приложение 'convert' именно этот 
подход). Можно зарегистрировать программный для модуля 
'thumbnail' и получить только поле 'undef', если не pdf файл
не найден, но когда pdf файл найден, создается иконка
предпросмотра, и только потом происходит возврат. Когда
приложение album возвращает иконку предпросмотра, то
он же и будет ее использовать, пропуская собственный фрагмент
программного кода для создания иконок предпросмотра.

Теперь пришла пора закончить написание нашего дополнения для 
преобразования в происные буквы. Дополнение должны делать
следующее:

1) Поддерживать 'start_plugin' подпрограмму.  Т.е. тот фрагмент кода
   где происходит регистрация дополнительных программных модулей
   и соответствующих им опций командной строки.

2) Подрограмма 'start_plugin' должна возращать информацию дополнения
   в hash, в которой необходимо указать следующие поля:
   author      => Имя автора
   href        => URL (или mailto, конечно) для автора
   version     => Номер версии для дополнения
   description => Текстовое описание дополнения

3) По окончанию дополнение возвращает '1' (аналогично как и perl модуль).

Ниже представлен наш пример, код дополнения clean_name полностью:


sub start_plugin {
  my ($opt) = @_;

  album::hook($opt,'clean_name',\&my_clean);

  return {
    author => 'David Ljung Madison',
    href => 'http://MarginalHacks.com/',
    version => '1.0',
    description => "Conver image names to uppercase",
  };
}

sub my_clean {
  return uc($name);
}

1;


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

  captions/formatting/NAME.alp

Фактически, если посмотреть examples/formatting/NAME.alp 
можно обнаружить, что дополнение уже там находится, и, что
фактически оно одно и тоже.

Если необходимо, чтобы дополнение имело доступ к опциям
командной строки, то нужно использовать конструкцию 'add_option.'
И это должно быть сделано в разделе start_plugin. 
Вот некоторые примеры:

  album::add_option(1,"fast",album::OPTION_BOOL, usage=>"Делает это быстро");
  album::add_option(1,"name", album::OPTION_STR, usage=>"Ваше имя");
  album::add_option(1,"colors",album::OPTION_ARR, usage=>"Цвет списка");

Для большей информации, посмотрите код 'add_option' в приложении album 
и ознакомьтесь со все вариантами его использования (в приложении album
и в дополнениях, которые испольузют 'add_option')

Для чтения опций, которые пользователь может установить, 
используется option():

  my $fast = album::option($opt, "быстро");

Чтобы пользователь не вводил неправильные значения опций, можно использовать
usage():

  album::usage("-colors array can only include values [red, green, blue]");

Если вашему дополнению нужно загрузить модули, которые
не являются часть стандартного дистрибутива Perl, посмотрите
пример plugins/extra/rss.alp.

Так же можно вызывать любой фргамент программного кода в скрипте
приложение album, путем использования двоеточие. Чтобы точно знать
как это можно сделать посмотрите примеры:


  album::add_head($opt,$data, "<meta name='add_this' content='to the <head>'>");
  album::add_header($opt,$data, "<p>This gets added to the album header");
  album::add_footer($opt,$data, "<p>This gets added to the album footer");


Лучший способ понять как написать дополнения - это посмотреть другое
работающее дополнение. Вероятно надо будет скопировать какую-либо
его часть и запустить его отдельно, чтобы понять как оно работает.
В будущем возможно появятся специальные программы для создание дополнений
для приложения album.

Есть опция, которая позволяет создать шаблон дополнения:

% album -create_plugin

6:   Переведено
Чубаровым И.Ю. (Tchubarov I, aka krolik, ceramic64@yandex.ru)