Создание собственных тем

<span lang="ru">
ITEM:   Методы

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

ITEM:   Редактирование HTML файлов существующих тем

Если вы хотите только слегка изменить тему, чтобы, например, она 
соответствовала дизайну вашего сайта, то самый простой путь - это
редактирование уже существующей темы. В папках тем имеется два
*.th файла. album.th - это шаблон для страниц самой галереи 
(для страницы с иконками предпросмотра) и image.th - шаблон для
построения страниц с полноразмерными изображениями. Структура этих
файлов очень простая, за исключением некототрых вставок с элементами
<: ePerl :> кода. Даже если вы не знаете, что такое Perl или
ePerl вы все равно можете прекрасно редактировать элементы HTML-файла, 
которые соответствуют общепринятым стандартам и тем самым осуществить 
небольшую корректировку темы.

Простые и понятные темы:

Если вам надо получить галерею без лишних элементов - обратите внимание на
 "Blue" или "Maste."  Если же вас привлекает счетверенная окантовка 
вокруг иконок предпросмотра посмотрите тему "Eddie Bauer." Если же
хотите что-то оригинальное, например наслаиващиеся и прозрачные рамки то,
смотрите тему FunLand.

Если вы хотите получить что-то совсем минималистическое, с минимальным
количеством кода, попробуйте тему "simple", но учтитет она очень давно
не обновлялась, поэтому она вполне может неккоректно работать с новейшими
типами графических файлов.

ITEM:   Простейший путь simmer_theme из графики.

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

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

Если вы создаете папку с изображениями, файл с благодарностями (см. ниже),
файлы шрифтов (Font) и стиля (Style.css), то новая тема будет создана автоматически.

Файлы:

Font/Style.css
Это файл, который определяет шрифт, который будет использован в теме.
"Font" - файл, системе должен быть известен раннее (см. ниже).
Создание же файла Style.css file позволяет определить все стили для:
тела, заголовка, пояснений и т.п.

Посмотрите тему FunLand как один из простых примеров.

Либо можно использовать только файл шрифта.  Пример такого файла представлен
ниже:

--------------------------------------------------
$TITLE_FONT = "size='4' color='#ffffff' face='Times New Roman,Georgia,Times'";
$MAIN_FONT = "face='Times New Roman,Georgia,Times'";
$CREDIT_FONT = "size='-1' face='Verdana' color='#ffffff'";
$BODY = "background='$PATH/bkgrnd.gif' link='#0099FF'">
--------------------------------------------------

Благодарности
Файл благодарностей - это те самые две строки, которые выводятся в галереях, созданными
приложением album, чтобы дать ссылки на ресурс MarginalHacks.
Если вы не собираетесь присылать тему нам, то вам, в общем, не стоит особенно беспокоится
об этом файле. Но, если же вам по крайней мере нравится сама идея, благодарности,
посмотрите как нужно оформить этот файл:

1) Краткое описание темы (все должно быть в одной строке)
2) Ваше имя (вы можете внутри указать mailto: or href link)

Null.gif
Для каждой темы необходим прозрачный рисунок типа gif, размером всего 1x1.
Вы можете его скопировать из любой другой темы.

Необязательные графические файлы для оформления тем:

Полосы
Полосы в темах сосздаются из файлов: 
Bar_L.gif, Bar_R.gif and Bar_M.gif 
(слева, справа, в середине - соответственно).
Полоса по середине растягивается. Если вам нужно, чтобы середина не была
растянута используется другие файлы:
Bar_L.gif, Bar_ML.gif, Bar_M.gif, Bar_MR.gif, Bar_R.gif
И затем файл Bar_ML.gif и Bar_MR.gif will, чтобы растянуть пространство
справа и слева.  (Чтобы понять что это - посмотрите тему Craftsman в
качестве примера).

Locked.gif
Это изображения для отображения папок, котоыре были закрыты через .htaccess

Изображения фонов
Если вы хотитет использовать изображения фона, то его надо указать
в файле шрифтов в $BODY разделе, как показано в последнем примере.
При этом переменная $PATH должна быть замещена путем к файлам темы

More.gif
Когда страница имеет галерении более низкого уровня, то этот файл
просто отображает слова 'More.gif' в форме графическго изображения.

Next.gif, Prev.gif, Back.gif
Это файлы стрелок для предыдущего, последующего и обратного элемента галереи.

Icon.gif
Файл который выводится в левом верзнем углу меню галереи, часто
он просто содержит только слово "Photos" ("Фотографии")

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

  4 элемента  Использует Bord_L.gif, Bord_R.gif, Bord_T.gif, Bord_B.gif
    (Углы слева и справа)
    4-х элементные рамки обычно не растягиваются, т.к. они не будут
    хорошо работать на страницах с полноразмерными изображениями,
    вы можете только сделать углы справа и слева от изображения:

  8 элементов  Так включает файлы Bord_TL.gif, Bord_TR.gif, Bord_BL.gif, Bord_BR.gif
    8-ми элементые рамки очень хорошо получается растягивать на страницах
    с полноразмерными изображениями

  12 элементов  Включает файлы Bord_LT.gif, Bord_RT.gif, Bord_LB.gif, Bord_RB.gif
    12-ти элементные рамки позволяют не только растягивать элементы рамки, но
    и вводить дополнительно сложные элементы-украшения на углас изображения 
    (посмотрите темы Dominatrix6 или Ivy)

  Overlay Borders  Can use transparent images that can be partially
    overlaying your thumbnail.  See below.

Ниже показана обычная структура распределения элементов рамок:

    12 элементов
      TL  T  TR           8 элементов         4 элемента
      LT     RT            TL  T  TR            TTTTTTT
      L  IMG  R            L  IMG  R            L IMG R
      LB     RB            BL  B  BR            BBBBBBB
      BL  B  BR

Стоит обратить внимание на то, что даже изображения формата raw
должны быть одной и той же высоты, несмотря на то, что ширина у них
как правило не одинаковая одинаковая (т.е. высота TL= высоте T
= высоте TR), правда это не относится к рамкам с перекрывающимися
элементами.

Когда вы создатите эти файлы, то можете запустить дополнительное
приложение simmer-theme (его можно скачать с сайта MarginalHacks.com),
после чего ваша тема будет готова к использованию!

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

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

Для использования рамок с элементами перекрытия, надо создать изображения:
      Over_TL.png   Over_T.png   Over_TR.png
      Over_L.png                 Over_R.png
      Over_BL.png   Over_B.png   Over_BR.png

Затем надо обозначить как много точек рамки будут снаружи фотографии.
И уже после, указать эти значения в файлах: 
Over_T.pad Over_R.pad Over_B.pad Over_L.pad
Для примера посмотрите тему "Themes/FunLand".

Изображения для различных языков
Если ваши изображения имеют текст, вы можете его перевести на другие языки
так, что галереи могут быть сгенерированы для других языков. К примеру, вы
моежет создать голандскийй файл изображения "More.gif" и посместить его в
'lang/nl/More.gif' в папку с темой (nl - это код языка Голландии).
Когда пользователь запустит приложение album в Голландии (с опцией 
album -lang nl), то тема будет использовать изображение, понятное
голандцам (т.е. то, которое будет найдено по указанному выше пути). 
В теме Blue имеется простой пример того, как этот подход работает.
На данный момент времени переведены изображения для:
  More, Back, Next, Prev and Icon

Вы можете создать HTML таблицу, которая покажет доступные языки 
для тем, путем вызова приложения album с опцией -list_html_trans:

% album -list_html_trans > trans.html

После чего посмотрите файл trans.html в вашем интернет-браузере.
К сожалению, разные языки имеют разную раскладку, а HTML страница всегда
имеет только одну. Но в HTML документе будут симвлолы в utf-8, поэтому
всегда можно вручную отредактировать параметр "charset=utf-8", чтобы
правильно видеть буквы различных языков.

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

ITEM:   (на будущее) API для тем

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

Любая папка с темой должная содержать как миним один файл - 'album.th'.
Это шаблон темы. Часто в папках можно увидеть файлы 'image.th', 
который является шаблоном для изображения, так же в папке находятся
скрипты стиля и вспомогательные графические файлы. Страницы самой галереи
содержат иконки предпросмотра и полноразмерные изображения.

Файлы .th - написаны на ePerl, который является диалектом языка Perl, 
специально разработанного для работы в HTML документе. Собственно
эти файлы и делают большую часть работы по соазданию галереи как таковой.

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

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

Функциональная таблица:

Требуемые функции
Meta()                    Должен быть вызван в HTML
Credit()                  Дает благодарность (то, что пишется внизу: 'this album created by..')
                          Должен быть вызван в HTML
Body_Tag()                Вызывается внутри текущего ярлыка.

Paths and Options
Option($name)             Дает значение опции или конфигурационной установки
Version()                 Возвращает версию приложения album 
Version_Num()             Возврашает только номвер версии приложения album (например, "3.14")
Path($type)               Возвращает путь для $type:
  album_name                Название этой галереи
  dir                       Текущая рабочая папка
  album_file                Полный путь к index.html
  album_path                Путь к "родительским" папкам
  theme                     Полный путь к папке с темами
  img_theme                 Полный путь к папке с темами из папки с графическими файлами галереи
  page_post_url             ".html" для добавления на страницы с изображениями
  parent_albums             Массив "родительских" галерей (album_path split up)
Image_Page()              1 если происходит генераци только страниц с изображениями, 0 - для меню галереи
Page_Type()               Или страница с изображениями 'image_page' или меню галереи 'album_page'
Theme_Path()              Путь к файлам темы в масштабе имен файловой системы
Theme_URL()               URL пуьб к файлам темы

Верзний и нижний колонтитул
isHeader(), pHeader()     Тест для печати верхнего колонтитула
isFooter(), pFooter()     То же самое для нижнего колонтитула

Главный цикл используется следущие локальные переменные:

  my $image = First('pics');
  while ($image) {
    print Name($image);
    $image = Next($image);
  }

Этот скрипт печатает названия кажлого изображения. Типы объектов или 
'pics' (для изображений) или 'dirs' для папок "потомков". 
Имеется несколько функций объекта:

Объекты (тип или 'pics' (по умолчанию) или 'dirs')
First($type)             Дает первый графический файл или объект галереи более низкого уровня.
Last($type)              Прошлый объект
Next($obj)               Возращает следующий объект
Next($obj,1)             То же самое, но при достижении последнего переходит к началу.
Prev($obj), Prev($obj,1)  Аналогичен Next()

num('pics') or just num() Общее число изображений в этой галерее
num('dirs')               Общее число галерей более низкого уровня (галерей "потомков")
Also:
num('parent_albums')      Общее число "прородителей" этой галереи.

Object lookup:
get_obj($num, $type, $loop)
                          Находится объекты по номеру ('pics' или 'dirs').
                          Если установлен цикл $loop то поиск будет бесконечным.

Свойства объектов
Каждый объект (изображение или галерея более низкого уровня) имеет свойства.
Некоторые свойства доступны через так называемые поля:

Get($obj,$field)            Дает одно поле объекта

Поле                     Описание
-----                     ----------
type                      Какой тип объекта?  Или 'pics', или 'dirs'
is_movie                  Логическое значение: это видео?
name                      Название (необязательно - берется из комментария)
cap                       Комментарий к изображению
capfile                   Необязательный файл комментариев
alt                       Альтернативный ярлык
num_pics                  [только для папок, -dir_thumbs] число pics в папке
num_dirs                  [только для папок, -dir_thumbs] число dirs в папке

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

Get($obj,$size,$field)      Получить значение поля для данного размера

Свойство      Поле        Описание
----          -----       ----------
$size         x           Ширина
$size         y           Высота
$size         file        Название файла (без пути)
$size         path        Название файла (полный путь)
$size         filesize    Размер файла в байтах
full          tag         Ярлык (или 'image', или 'embed') - но только для 'full'

Так же имеется информация об URL, которая позволяет осуществить
доступ к странице находясь в 'from' к изображению или странице, 
указанной в 'to':

Get($obj,'URL',$from,$to)   Получить URL для объекта из->в
Get($obj,'href',$from,$to)  То же самое, но данные возвращаются как 'href' строка.
Get($obj,'link',$from,$to)  То же самое, но данные будут для объекта с указанным 
			    именем внутри ссылки href.

Из           В            Описание
----         --           ----------
album_page   image        Адрес изображения для страницы галереи из album_page
album_page   thumb        Иконка предпросмотра из album_page
image_page   image        Адрес изображения из image_page
image_page   image_page   Страница с изображение из другой страницы с изображением
image_page   image_src    Адрес URL &lt;img src&gt; для страницы с изображением
image_page   thumb        Иконока предпросмотра для страницы с изображением

Папки с объектами так же имеют свойства:

Из           В            Определение
----         --           ----------
album_page   dir          URL к папке из страницы с "родительской" галереи

<b>"Родительские" галереи</b>
Parent_Album($num)        Получить строку "родительской" галереи (включая href)
Parent_Albums()           Получить список стро "родительской" галереи (включая href)
Parent_Album($str)        Присоединить вызов ($str) для Parent_Albums()
Back()                    URL для возврата на первую страницу.

<b>Изображения</b>
This_Image                Объект изображение для страницы с изображениями
Image($img,$type)         Ярлык &lt;img&gt; для средних, полных и "иконочных" изображений
Image($num,$type)         То же самое но для числа изображений
Name($img)                Чистое и комментарий для изображения
Caption($img)             Подпись к изображению

<b>Галереи "потомков"</b>
Name($alb)
Caption($img)             Подпись к изображению

<b>Элементы для упрощения</b>
Pretty($str,$html,$lines) Очень удобный формат имени.
    Если $html то HTML разрешено (т.е., используюя 0 для &lt;title&gt; и т.п.)
    Постоянно только устанавливаются префексы для дат самым маленьким шрифтом ('2004-12-03.Папка')
    Если $lines то "многострочность" разрешена
    Постоянно только разрешены даты с символом конца строки 'br'.
New_Row($obj,$cols,$off)  Should we start a new row after this object?
                          Use $off if the first object is offset from 1
Image_Array($src,$x,$y,$also,$alt)
                          Returns an &lt;img&gt; tag given $src, $x,...
Image_Ref($ref,$also,$alt)
                          Like Image_Array, but $ref can be a hash of
                          Image_Arrays keyed by language ('_' is default).
                          album picks the Image_Array by what languages are set.
Border($img,$type,$href,@border)
Border($str,$x,$y,@border)
                          Create the full bordered image.
                          See 'Borders' for more information.

Если вы создали тему, то подумайте о том чтобы добавить поддержку
слайд-шоу (при использовании опции -slideshow). Самый легкий путь осуществить
эту идею добавить фрагементы кода, отмеченный словом "slideshow" из существующей
темы.

ITEM:   Как прислать свою тему для добавление в состав приложения

У вас есть собственная тема? Будет очень приятно ее увидеть, даже если она
сделана под конкретный сайт со своим стилевым оформлением.

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

ITEM:   Конвертация тем v2.0 в темы v3.0

Интерфейс тем приложения album v2.0 впоследствии был изменен. Поэтому большинство
тем v2.0 (особеннно тех, в которых не используется много глобальных переменных)
будут все еще продолжать нормально работать, но, в недалеком будущем, нормальный
внешний вид галереи может быть сильно нарушен. 

Чтобы этого не произошло несложно провести конвертацию тем из v2.0 в v3.0.

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

  my $image = First('pics');
  while ($image) {
    print Name($image);
    $image = Next($image);
  }

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

Здесь представлена схема преобразования для помощи в конвертации тем v2.0 в v3.0:

# Глобальные переменные не надо использовать
# ВСЕ УБРАТЬ - как получить локальные переменные в примере см. выше
$PARENT_ALBUM_CNT             Rewrite with: Parent_Album($num) and Parent_Albums($join)
$CHILD_ALBUM_CNT              Rewrite with: my $dir = First('dirs');  $dir=Next($dir);
$IMAGE_CNT                    Rewrite with: my $img = First('pics');  $pics=Next($pics);
@PARENT_ALBUMS                Can instead use: @{Path('parent_albums')}
@CHILD_ALBUMS, @CHILD_ALBUM_NAMES, @CHILD_ALBUM_URLS, ...

# Старые глобальные переменные:
# ВСЕ УБРАТЬ - как получить локальные переменные в примере см. выше
Next_Image(), Images_Left(), Image_Cnt(), Image_Prev(), Image_Next()
Set_Image_Prev(), Set_Image_Next(), Set_Image_This()
Next_Child_Album(), Child_Album_Cnt(), Child_Albums_Left()

# Пути и методы
pAlbum_Name()                 Path('album_name')
Album_Filename()              Path('album_file')
pFile($file)                  print read_file($file)
Get_Opt($option)              Option($option)
Index()                       Option('index')
pParent_Album($str)           print Parent_Album($str)

# "Родительские" галереи
Parent_Albums_Left            Deprecated, see '$PARENT_ALBUM_CNT' above
Parent_Album_Cnt              Deprecated, see '$PARENT_ALBUM_CNT' above
Next_Parent_Album             Deprecated, see '$PARENT_ALBUM_CNT' above
pJoin_Parent_Albums           print Parent_Albums(\@_)

# Изображения, использующие переменную '$img'
pImage()                      Use $img instead and:
                              print Get($img,'href','image');
                              print Get($img,'thumb') if Get($img,'thumb');
                              print Name($img), "&lt;/a&gt;";
pImage_Src()                  print Image($img,'full')
Image_Src()                   Image($img,'full')
pImage_Thumb_Src()            print Image($img,'thumb')
Image_Name()                  Name($img)
Image_Caption()               Caption($img)
pImage_Caption()              print Get($img,'Caption')
Image_Thumb()                 Get($img,'URL','thumb')
Image_Is_Pic()                Get($img,'thumb')
Image_Alt()                   Get($img,'alt')
Image_Filesize()              Get($img,'full','filesize')
Image_Path()                  Get($img,'full','path')
Image_Width()                 Get($img,'medium','x') || Get($img,'full','x')
Image_Height()                Get($img,'medium','y') || Get($img,'full','y')
Image_Filename()              Get($img,'full','file')
Image_Tag()                   Get($img,'full','tag')
Image_URL()                   Get($img,'URL','image')
Image_Page_URL()              Get($img,'URL','image_page','image_page') || Back()

# Галерея "потомок", использующая переменную '$alb'
pChild_Album($nobr)           print Get($alb,'href','dir');
                              my $name = Name($alb);
                              $name =~ s/&lt;br&gt;//g if $nobr;
                              print $name,"&lt;/a&gt;";
Child_Album_Caption()         Caption($alb,'dirs')
pChild_Album_Caption()        print Child_Album_Caption($alb)
Child_Album_URL()             Get($alb,'URL','dir')
Child_Album_Name()            Name($alb)

# Без изменения
Meta()                        Meta()
Credit()                      Credit()


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

