Création de thèmes

<span lang="fr">
ITEM: Métodes

Il y a des moyens faciles et d'autres compliqués pour créer un thème sur
mesure en fonction de ce que vous voulez faire.

ITEM: Editer le code HTML d'un thème existant

Si vous voulez juste modifier légèrement un thème afin qu'il corresponde à
l'environnement de votre site, il semble opportun d'éditer un thème existant.
Dans le répertoire du thème, il y a deux fichiers avec l'extension
th. album.th est le patron pour les pages de l'album (les pages des vignettes)
et image.th est le patron pour les pages des images (où vous voyez les images
moyennement réduites ou en pleine taille). Ces fichiers sont très similaire à
du code HTML excepté quelques rajouts de code <: ePerl :>. Même si vous ne
connaissez ni Perl ni ePerl, vous pouvez néanmoins éditer le code HTML pour y
apporter des changements basiques.

Des thèmes pour bien démarrer :

N'importe quel thème dans simmer_theme peut servir comme "Blue" ou "Maste". Si
vous avez seulement besoin de 4 bordures aux coins de vos vignettes, alors
jetez un oeil sur "Eddie Bauer". Si vous voulez des bordures transparentes ou
qui se recouvrent, regardez "FunLand".

Si vous voulez quelque chose avec un minimum de code, essayez "simple" mais
attention, je n'ai pas mis à jour ce thème depuis un bon bout de temps.

ITEM: Le moyen facile : simmer_theme pour les graphiques

La plupart des thèmes ont un même format basique, montrent une série de
vignettes pour des répertoires puis pour des images avec une bordure et une
ligne graphiques ainsi qu'un fond d'écran. Si c'est ce que vous voulez mais
que vous souhaitez créer de nouveaux graphiques, il y a un outil qui vous
permettra de construire des thèmes.

Si vous créez un répertoire avec des images et un fichier CREDIT ainsi q'un
fichier Font ou Style.css, alors l'utilitaire simmer_theme vous permettra de
réaliser des thèmes.

Fichiers :
<b>Font/Style.css</b>
Ce fichier détermine les fontes utilisées par le thème. Le fichier "Font" est
le plus ancien système. Par exemple :

--------------------------------------------------
$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'">
--------------------------------------------------


Sinon, créez le fichier Style.css, puis définissez des styles pour : le corps,
le titre, la page principale, le crédit et toute autre chose que vous voulez.
Regardez FunLand comme exemple simple.

<b>CREDIT</b>
Le fichier de crédit comporte deux lignes et est utilisé pour l'index des
thèmes à MarginalHacks. Si vous ne nous soumettez jamais votre thème, alors
vous n'avez pas besoin de ce fichier (mais faites-le s'il vous plaît !). En
tout cas, les deux lignes (et seulement deux lignes) sont :

1) une courte description du thème (à faire tenir sur une seule ligne),
2) Votre nom (qui peut être à l'intérieur d'un mailto: ou d'un lien internet).

<b>Null.gif</b>
Chaque thème créé par simmer a besoin d'une image "espace" c'est-à-dire une
image au format gif transparent de dimensions 1x1. Vous pouvez simplement la
copier depuis un autre thème créé par simmer.

Fichiers d'images optionnels :

<b>Images de la barre</b>
La barre est composée de Bar_L.gif (à gauche), Bar_R.gif (à droite) et
Bar_M.gif au milieu. L'image de la barre du milieu est étirée. Si vous avez
besoin d'une barre centrale qui ne soit pas étirée, utilisez :
  Bar_L.gif, Bar_ML.gif, Bar_M.gif, Bar_MR.gif, Bar_R.gif
Dans ce cas, Bar_ML.gif et Bar_MR.gif ne seront pas étirées (voir le thème
"Craftsman" pour un exemple de cette technique).

<b>Locked.gif</b>
Une image de cadenas pour tous les répertoires ayant un fichier nommé
.htaccess.

<b>Images de fond</b>
Si vous voulez une image en fond d'écran, spécifiez-la dans le fichier Font
dans la section $BODY comme dans l'exemple ci-dessus. La valeur de la variable
$PATH sera remplacée par le chemin d'accès aux fichiers du thème.

<b>More.gif</b>
Quand une page d'album comporte plusieurs sous-albums à lister, l'image
'More.gif' est affichée en premier.

<b>Next.gif, Prev.gif, Back.gif</b>
Ces images sont respectivement utilisées pour les boutons des flèches arrière
et avant et pour le bouton pour remonter dans la hiérarchie des albums.

<b>Icon.gif</b>
Cette image, affichée dans le coin supérieur gauche des albums parents, est
souvent le texte "Photos" seulement.

<b>Images des bordures</b>
Il y a plusieurs méthodes pour découper une bordure, de la plus simple à la
plus complexe, l'ensemble dépendant de la complexité de la bordure et du
nombre de sections que vous voulez pouvoir étirer :

  <b>4 morceaux</b>  Utilisez  Bord_L.gif, Bord_R.gif, Bord_T.gif, Bord_B.gif
    (les coins vont avec les images droites et gauches)
    Les bordures en 4 morceaux ne s'étirent en général pas très bien et de
    fait ne fonctionnent pas bien sur les pages d'images. En général, vous
    pouvez couper les coins des images droites et gauches pour faire :

  <b>8 morceaux</b>  Incluez aussi Bord_TL.gif, Bord_TR.gif, Bord_BL.gif,
    Bord_BR.gif
    Les bordures en 8 morceaux vous permettez généralement d'étirer et de
    gérer la plupart des images recadrées.

  <b>12 morceaux</b>  Incluez aussi Bord_LT.gif, Bord_RT.gif, Bord_LB.gif,
    Bord_RB.gif
    12 morceaux permettent d'étirer des bordures ayant des coins plus
    complexes comme par exemple les thèmes Dominatrix ou Ivy.

  <b>Bordures chevauchantes</b>  Peuvent utiliser des images transparentes qui
  peuvent partiellement chevaucher vos vignettes. Voir ci-dessous.

Voici comment des morceaux pour des bordures normales sont disposés :

 bordure à 12 morceaux
      TL  T  TR      bordure à 8 morceaux    bordure à 4 morceaux
      LT     RT            TL  T  TR            TTTTTTT
      L  IMG  R            L  IMG  R            L IMG R
      LB     RB            BL  B  BR            BBBBBBB
      BL  B  BR

Notez que chaque rangée d'images doit avoir la même hauteur, alors que ce
<b>n'est pas</b> le cas pour la largeur (c'est-à-dire hauteur TL = hauteur T =
hauteur TR).
Ceci n'est pas totalement vrai pour les bordures qui se chevauchent !

Une fois que vous avez créé ces fichiers, vous pouvez lancer l'utilitaire
simmer_theme (un outil téléchargeable depuis MarginalHacks.com) et votre thème
deviendra prêt à être utilisé !

Si vous avez besoin de bordures différentes pour les pages d'images, alors
utilisez les mêmes noms de fichiers maix en les préfixant par 'I' comme par
exemple IBord_LT.gif, IBord_RT.gif,...

Les bordures chevauchantes autorisent des effets réellement fantastiques avec
les bordures des images.  Actuellement, il n'y a pas de support pour des
bordures chevauchantes différentes pour les images.

Pour utiliser les bordures chevauchantes, créez les images :
      Over_TL.png   Over_T.png   Over_TR.png
      Over_L.png                 Over_R.png
      Over_BL.png   Over_B.png   Over_BR.png

Puis, déterminez combien de pixels des bordures vont déborder (en dehors de la
photo). Mettez ces valeurs dans des fichiers: Over_T.pad Over_R.pad Over_B.pad
Over_L.pad.
Voir le thème "FunLand" pour un exemple simple.

<b>Images polyglottes</b>
Si vos images comportent du texte, vous pouvez les traduire dans d'autres
langues et, ainsi, vos albums pourront être générés dans d'autres
langages. Par exemple, vous pouvez créer une image "More.gif" hollandaise et
mettre ce fichier dans le répertoire 'lang/nl' de votre thème (nl est le code
de langage pour le hollandais).
Quand l'utilisateur lancera album en hollandais (album -lang nl) alors le
thème utilisera les images hollandaises s'il les trouve. Le thème "Blue"
comporte un tel exemple simple. Les images actuellement traduites sont :
  More, Back, Next, Prev and Icon

Vous pouvez créer une page HTML qui donne la liste des traductions
immédiatement disponibles dans les thèmes avec l'option -list_html_trans :

<code>% album -list_html_trans > trans.html</code>

Puis, visualisez le fichier trans.html dans un navigateur. Malheureusement,
plusieurs langages ont des tables d'encodage des caractères différents et une
page HTML n'en dispose que d'une seule. La table d'encodage est utf-u mais
vous pouvez éditer la ligne "charset=utf-8" pour visualiser correctement les
différents caractères utilisés dans les langages en fonction des différentes
tables d'encodage (comme par exemple l'hébreu).

Si vous avez besoin de plus de mots traduits pour les thèmes, faites-le moi
savoir et si vous créez des images dans une nouvelle langue pour un thème,
envoyez-les moi s'il vous plaît !


ITEM: Partir de zéro : l'API des thèmes

Ceci est une autre paire de manches : vous avez besoin d'avoir une idée
vraiment très claire de la façon dont vous voulez qu'album positionne vos
images sur votre page. Ce serait peut-être une bonne idée de commencer en
premier par modifier des thèmes existants afin de cerner ce que la plupart des
thèmes fait. Regardez également les thèmes existants pour des exemples de code
(voir les suggestions ci-dessus).

Les thèmes sont des répertoires qui contiennent au minimum un fichier
'album.th'. Ceci est le patron du thème pour les pages de l'album. Souvent,
les répertoires contiennent aussi un fichier 'image.th' qui est un patron du
thème pour les images ainsi que des fichiers graphiques / css utilisés par le
thème. Les pages de l'album contiennent les vignettes et les pages des images
montrent les images pleine page ou recadrées.

Les fichiers .th sont en ePerl qui est du perl encapsulé à l'intérieur
d'HTML. Ils finissent par ressembler à ce que sera l'album et les images HTML
eux-mêmes.

Pour écrire un thème, vous aurez besoin de connaître la syntaxe ePerl. Vous
pouvez trouver plus d'information sur l'outil ePerl en général à MarginalHacks
(bien que cet outil ne soit pas nécessaire pour l'utilisation des thèmes dans album).

Il y a une pléthore de routines de support disponibles mais souvent une
fraction d'entre elles seulement est nécessaire (cela peut aider de regarder
les autres thèmes afin de voir comment ils sont construits en général).

Table des fonctions:

<b>Fonctions nécessaires</b>
Meta()                    Doit être appelée depuis la section <head> du HTML
Credit()                  Affiche le crédit ('cet album a été créé par..')
                          Doit être appelée depuis la section <body> du HTML
Body_Tag()                Appelée depuis l'intérieur du tag <body>.

<b>Chemins et options</b>
Option($name)             Retourne la valeur d'une option / configuration
Version()                 Retourne la version d'album
Version_Num()             Retourne le numéro de la version d'album en chiffres
                            uniquement (c'est-à-dire. "3.14")
Path($type)               Retourne l'information du chemin pour le $type de :
  album_name                Nom de l'album
  dir                       Répertoire courant de travail d'album
  album_file                Chemin complet au fichier d'album index.html
  album_path                Chemin des répertoires parent
  theme                     Chemin complet du répertoire du thème
  img_theme                 Chemin complet du répertoire du thème depuis les
                              pages des images
  page_post_url             Le ".html" à ajouter sur les pages des images
  parent_albums             Tableau des albums parents (segmentation par album_path)
Image_Page()              1 si on est en train de générer une page d'image, 0
                            si c'est une page de vignettes
Page_Type()               Soit 'image_page' ou 'album_page'
Theme_Path()              Le chemin d'accès (via le système de fichiers) aux fichiers du thème
Theme_URL()               Le chemin d'accès (via une URL) aux fichiers du thème

<b>En-tête et pied-de-page</b>
isHeader(), pHeader()     Test pour et afficher l'en-tête
isFooter(), pFooter()     La même chose pour le pied-de-page

En général, vous bouclez à travers les images et les répertoires en utilisant
des variables locales :

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

Ceci affichera le nom de chaque image. Nos types d'objets sont soit 'pics'
pour les images soit 'dirs' pour les répertoires-enfants. Ici se trouvent les
fonctions relatives aux objets :

<b>Objets</b> (le type est soit 'pics' (défaut) soit 'dirs')
First($type)             Renvoie comme objet la première image ou le premier sous-album.
Last($type)              Renvoie le dernier objet
Next($obj)               Etant donné un objet, renvoie l'objet suivant
Next($obj,1)             La même chose mais retourne au début une fois la fin atteinte
Prev($obj), Prev($obj,1) Similaire à Next()

num('pics') ou juste num() Nombre total d'images de cet album
num('dirs')                Nombre total de sous-albums
Egalement:
num('parent_albums')       Nombre total d'albums parents conduisant à cet album

Consultation d'objet :
get_obj($num, $type, $loop)
                          Trouve un objet à partir de son numéro (type 'pics' ou 'dirs').
                          Si la variable $loop est positionnée alors le
			  compteur rebouclera au début lors de la recherche

<b>Propriétés des objets</b>
Chaque objet (image ou sous-album) possède des propriétés.
L'accès à certaines propriétés se fait par un simple champ :

Get($obj,$field)            Retourne un simple champ pour un objet donné

Champ                     Description
-----                     ----------
type                      Quel type d'objet ? Soit 'pics' soit 'dirs'
is_movie                  Booléen: est-ce que c'est un film ?
name                      Nom (nettoyé et optionnel pour les légendes)
cap                       Légende de l'image
capfile                   Fichier optionnel des légendes
alt                       Etiquette (tag) alt
num_pics                  [répertoires seulement, -dir_thumbs] Nombre d'images
			    dans le répertoire
num_dirs                  [répertoires seulement, -dir_thumbs] Nombre de
			    sous-répertoire dans le répertoire

L'accès à des propriétés se fait via un champ et un sous-champ. Par exemple,
chaque image comporte une information sur ses différentes tailles : plein
écran, moyenne et vignette (bien que la taille moyenne soit optionnelle).

Get($obj,$size,$field)      Retourne la propriété de l'image pour une taille donnéee

Taille        Champ       Description
------        -----       ----------
$size         x           Largeur
$size         y           Hauteur
$size         file        Nom du fichier (sans le chemin)
$size         path        Nom du fichier (chemin complete)
$size         filesize    Taille du fichier en octets
full          tag         L'étiquette (tag) (soit 'image' soit 'embed') -
			    seulement pour 'full'

Il y a aussi des informations relatives aux URL dont l'accès se fait en
fonction de la page d'où on vient ('from' / depuis) et l'image ou la page vers lequel
on va ('to' / vers) :

Get($obj,'URL',$from,$to)   Renvoie un URL pour un objet 'depuis -> 'vers
Get($obj,'href',$from,$to)  Idem mais utilise une chaîne de caractères avec 'href'
Get($obj,'link',$from,$to)  Idem mais met le nom de l'objet à l'intérieur d'un
			      lien href

Depuis       Vers         Description
------       ----         ----------
album_page   image        Image_URL vers album_page
album_page   thumb        Thumbnail vers album_page
image_page   image        Image_URL vers image_page
image_page   image_page   Cette page d'image vers une autre page d'image
image_page   image_src    L'URL d'&lt;img src&gt; pour la page d'image
image_page   thumb        Page des vignettes depuis la page d'image

Les objets répertoires ont aussi :

Depuis       Vers         Description
------       ----         ----------
album_page   dir          URL vers le répertoire depuis la page de son album-parent


<b>Albums parent</b>
Parent_Album($num)        Renvoie en chaîne de caractères le nom de l'album
			    parent (incluant le href)
Parent_Albums()           Retourne une liste de chaînes de caractères des
			    albums parents (incluant le href)
Parent_Album($str)        Crée la chaîne de caractères $str à partir de
			    l'appel  à la fonction Parent_Albums()
Back()                    L'URL pour revenir en arrière ou remonter d'une page

<b>Images</b>
This_Image                L'objet image pour une page d'image
Image($img,$type)         Les étiquettes d'&lt;img&gt; pour les types 'medium',
			    'full' et 'thumb'
Image($num,$type)         Idem mais avec le numéro de l'image
Name($img)                Le nom nettoyé ou légendé pour une image
Caption($img)             La légende pour une image

<b>Albums enfants</b>
Name($alb)		  Le nom du sous-album
Caption($img)             La légende pour une image



<b>Quelques routines utiles</b>
Pretty($str,$html,$lines) Formate un nom.
    Si la variable $html est définie alors le code HTML est autorisé
    (c'est-à-dire utilise 0 pour <title> et associés). Actuellement, préfixe
    seulement avec la date dans une taille de caractères plus petite
    (c'est-à-dire '2004-12-03.Folder').
    Si la variable $line est définie alors le multiligne est
    autorisé. Actuellement, suis seulement la date avec un retour à la ligne 'br'.
New_Row($obj,$cols,$off)  Devons-nous commencer une nouvelle ligne après cet
			  objet ?
			  Utiliser la variable $off si l'offset du premier
			  objet démarre à partir de 1
Image_Array($src,$x,$y,$also,$alt)
                          Retourne un tag HTML &lt;img&gt; à partir de $src, $x,...
Image_Ref($ref,$also,$alt)
			  Identique à Image_Array, mais la variable $ref peut
			  être une table de hachage de Image_Arrays indexée par
			  le langage (par défaut, '_').
			  album choisit l'Image_Array en fonction de la
			  définition des langages.
Border($img,$type,$href,@border)
Border($str,$x,$y,@border)
                          Crée une image entière entourée de bordures. Voir
			  'Bordures' pour de plus amples détails.


Si vous créez un thème à partir de zéro, considérez l'ajout du support pour
l'option -slideshow. Le moyen le plus facile de réaliser cette opération est
de copier / coller le code "slideshow" d'un thème existant.


ITEM: Soumettre des thèmes

Vous avez personnalisé un thème ? Je serais ravi de le voir même s'il est
totalement spécifique à votre site internet.

si vous avez un nouveau thème que vous souhaiteriez rendre publique,
envoyez-le moi ou envoyez une adresse URL où je puisse le voir. N'oubliez pas
de mettre le fichier CREDIT à jour et faites-moi savoir si vous donnez ce
thème à MarginalHacks pour une utilisation libre ou si vous souhaitez le
mettre sous une license particulière.




ITEM: Conversion des thèmes v2.0 aux thèmes v3.0

La version v2.0 d'album a introduit une interface de thèmes qui a été réécrite
dans la version v3.0 d'album. La plupart des thèmes de la version 2.0 (plus
spécialement ceux qui n'utilisent pas la plupart des variables globales)
fonctionneront toujours mais l'interface est obsolète et pourrait disparaître
dans un futur proche.

La conversion des thèmes de la version 2.0 à la version 3.0 n'est pas bien
difficile.

Les thèmes de la version 2.0 utilisent des variables globales pour tout un tas
de choses. Celles-ci sont maintenant obsolètes. Dans la version 3.0, vous
devez conserver une trace des images et des répertoires dans des variables et
utiliser des 'itérateurs' qui sont fournis. Par exemple :

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

Ceci parcourra toutes les images et affichera leur nom.
Le tableau ci-dessous vous montre comment réécrire des appels codés avec
l'ancien style utilisant une variable globale en des appels codés avec le
nouveau style qui utilise une variable locale. Cependant pour utiliser ces
appels, vous devez modifier vos boucles comme ci-dessus.

Voici une tableau de conversion pour aider au passage des thèmes de la version
2.0 à la version 3.0 :

# Les variables globales ne doivent plus être utilisées
# OBSOLETE - Voir les nouvelles méthodes d'itérations avec variables locales
# ci-dessus
$PARENT_ALBUM_CNT             Réécrire avec : Parent_Album($num) et Parent_Albums($join)
$CHILD_ALBUM_CNT              Réécrire avec : my $dir = First('dirs');  $dir=Next($dir);
$IMAGE_CNT                    Réécrire avec : my $img = First('pics');  $pics=Next($pics);
@PARENT_ALBUMS                Utiliser à la place : @{Path('parent_albums')}
@CHILD_ALBUMS, @CHILD_ALBUM_NAMES, @CHILD_ALBUM_URLS, ...

# Anciennes méthodes modifiant les variables globales
# OBSOLETE - Voir les nouvelles méthodes d'itérations avec variables locales
# ci-dessus
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()

# chemins et autres
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)

# Albums parents
Parent_Albums_Left            Obsolète, voir '$PARENT_ALBUM_CNT' ci-dessus
Parent_Album_Cnt              Obsolète, voir '$PARENT_ALBUM_CNT' ci-dessus
Next_Parent_Album             Obsolète, voir '$PARENT_ALBUM_CNT' ci-dessus
pJoin_Parent_Albums           print Parent_Albums(\@_)

# Images, utilisant la variable '$img'
pImage()                      Utiliser $img à la place et :
                              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()

# Routines pour les albums enfant utilisant la variable '$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)

# Inchangé
Meta()                        Meta()
Credit()                      Credit()

ITEM: Traduit par:

Jean-Marc [jean-marc.bouche AT 9online.fr]
</span>
