Cration de thmes

<span lang="fr">
ITEM: Mtodes

Il y a des moyens faciles et d'autres compliqus pour crer un thme sur
mesure en fonction de ce que vous voulez faire.

ITEM: Editer le code HTML d'un thme existant

Si vous voulez juste modifier lgrement un thme afin qu'il corresponde 
l'environnement de votre site, il semble opportun d'diter un thme existant.
Dans le rpertoire du thme, 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 rduites ou en pleine taille). Ces fichiers sont trs similaire 
du code HTML except quelques rajouts de code <: ePerl :>. Mme si vous ne
connaissez ni Perl ni ePerl, vous pouvez nanmoins diter le code HTML pour y
apporter des changements basiques.

Des thmes pour bien dmarrer :

N'importe quel thme 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 thme depuis un bon bout de temps.

ITEM: Le moyen facile : simmer_theme pour les graphiques

La plupart des thmes ont un mme format basique, montrent une srie de
vignettes pour des rpertoires 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 crer de nouveaux graphiques, il y a un outil qui vous
permettra de construire des thmes.

Si vous crez un rpertoire avec des images et un fichier CREDIT ainsi qu'un
fichier Font ou Style.css, alors l'utilitaire simmer_theme vous permettra de
raliser des thmes.

Fichiers :
<b>Font/Style.css</b>
Ce fichier dtermine les fontes utilises par le thme. Le fichier "Font" est
le plus ancien systme, dcrit ci-dessous. Crez un fichier Style.css et
dfinissez des styles pour : body (le corps), title (le titre), main (la page
principale), credit (le crdit) et tout ce que vous voulez.

Regardez FunLand pour un exemple basique.

Autrement, utilisez un fichier Font. Un exemple de fichier Font est :

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


<b>CREDIT</b>
Le fichier de crdit comporte deux lignes et est utilis pour l'index des
thmes  MarginalHacks. Si vous ne nous soumettez jamais votre thme, alors
vous n'avez pas besoin de ce fichier (mais faites-le s'il vous plat !). En
tout cas, les deux lignes (et seulement deux lignes) sont :

1) une courte description du thme ( faire tenir sur une seule ligne),
2) Votre nom (qui peut tre  l'intrieur d'un mailto: ou d'un lien internet).

<b>Null.gif</b>
Chaque thme 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 thme cr par simmer.

Fichiers d'images optionnels :

<b>Images de la barre</b>
La barre est compose de Bar_L.gif ( gauche), Bar_R.gif ( droite) et
Bar_M.gif au milieu. L'image de la barre du milieu est tire. Si vous avez
besoin d'une barre centrale qui ne soit pas tire, 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 tires (voir le thme
Craftsman pour un exemple de cette technique).

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

<b>Images de fond</b>
Si vous voulez une image en fond d'cran, spcifiez-la dans le fichier Font
dans la section $BODY comme dans l'exemple ci-dessus. La valeur de la variable
$PATH sera remplace par le chemin d'accs aux fichiers du thme.

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

<b>Next.gif, Prev.gif, Back.gif</b>
Ces images sont respectivement utilises pour les boutons des flches arrire
et avant et pour le bouton pour remonter dans la hirarchie des albums.

<b>Icon.gif</b>
Cette image, affiche dans le coin suprieur gauche des albums parents, est
souvent le texte "Photos" seulement.

<b>Images des bordures</b>
Il y a plusieurs mthodes pour dcouper une bordure, de la plus simple  la
plus complexe, l'ensemble dpendant 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 gnral pas trs bien et de
    fait ne fonctionnent pas bien sur les pages d'images. En gnral, 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 permettent gnralement d'tirer et de
    grer la plupart des images recadres.

  <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 thmes 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 disposs :

 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 range d'images doit avoir la mme 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 tlchargeable depuis MarginalHacks.com) et votre thme
deviendra prt  tre utilis !

Si vous avez besoin de bordures diffrentes pour les pages d'images, alors
utilisez les mmes noms de fichiers maix en les prfixant par 'I' comme par
exemple IBord_LT.gif, IBord_RT.gif,...

Les bordures chevauchantes autorisent des effets rellement fantastiques avec
les bordures des images.  Actuellement, il n'y a pas de support pour des
bordures chevauchantes diffrentes pour les images.

Pour utiliser les bordures chevauchantes, crez 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, dterminez combien de pixels des bordures vont dborder (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 thme "Themes/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 gnrs dans d'autres
langages. Par exemple, vous pouvez crer une image "More.gif" hollandaise et
mettre ce fichier dans le rpertoire 'lang/nl' de votre thme (nl est le code
de langage pour le hollandais).
Quand l'utilisateur lancera album en hollandais (album -lang nl) alors le
thme utilisera les images hollandaises s'il les trouve. Le thme "Themes/Blue"
comporte un tel exemple simple. Les images actuellement traduites sont :
  More, Back, Next, Prev and Icon

Vous pouvez crer une page HTML qui donne la liste des traductions
immdiatement disponibles dans les thmes 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 caractres diffrents et une
page HTML n'en dispose que d'une seule. La table d'encodage est utf-8 mais
vous pouvez diter la ligne "charset=utf-8" pour visualiser correctement les
diffrents caractres utiliss dans les langages en fonction des diffrentes
tables d'encodage (comme par exemple l'hbreu).

Si vous avez besoin de plus de mots traduits pour les thmes, faites-le moi
savoir et si vous crez des images dans une nouvelle langue pour un thme,
envoyez-les moi s'il vous plat !


ITEM: Partir de zro : l'API des thmes

Ceci est une autre paire de manches : vous avez besoin d'avoir une ide
vraiment trs claire de la faon dont vous voulez qu'album positionne vos
images sur votre page. Ce serait peut-tre une bonne ide de commencer en
premier par modifier des thmes existants afin de cerner ce que la plupart des
thmes fait. Regardez galement les thmes existants pour des exemples de code
(voir les suggestions ci-dessus).

Les thmes sont des rpertoires qui contiennent au minimum un fichier
'album.th'. Ceci est le patron du thme pour les pages de l'album. Souvent,
les rpertoires contiennent aussi un fichier 'image.th' qui est un patron du
thme pour les images ainsi que des fichiers graphiques / css utiliss par le
thme. Les pages de l'album contiennent les vignettes et les pages des images
montrent les images pleine page ou recadres.

Les fichiers .th sont en ePerl qui est du perl encapsul  l'intrieur
d'HTML. Ils finissent par ressembler  ce que sera l'album et les images HTML
eux-mmes.

Pour crire un thme, vous aurez besoin de connatre la syntaxe ePerl. Vous
pouvez trouver plus d'information sur l'outil ePerl en gnral  MarginalHacks
(bien que cet outil ne soit pas ncessaire pour l'utilisation des thmes dans album).

Il y a une plthore de routines de support disponibles mais souvent une
fraction d'entre elles seulement est ncessaire (cela peut aider de regarder
les autres thmes afin de voir comment ils sont construits en gnral).

Table des fonctions:

<b>Fonctions ncessaires</b>
Meta()                    Doit tre appele depuis la section <head> du HTML
Credit()                  Affiche le crdit ('cet album a t cr par..')
                          Doit tre appele depuis la section <body> du HTML
Body_Tag()                Appele depuis l'intrieur 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 numro 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                       Rpertoire courant de travail d'album
  album_file                Chemin complet au fichier d'album index.html
  album_path                Chemin des rpertoires parent
  theme                     Chemin complet du rpertoire du thme
  img_theme                 Chemin complet du rpertoire du thme 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 gnrer 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'accs (via le systme de fichiers) aux fichiers du thme
Theme_URL()               Le chemin d'accs (via une URL) aux fichiers du thme

<b>En-tte et pied-de-page</b>
isHeader(), pHeader()     Test pour et afficher l'en-tte
isFooter(), pFooter()     La mme chose pour le pied-de-page

En gnral, vous bouclez  travers les images et les rpertoires 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 rpertoires-enfants. Ici se trouvent les
fonctions relatives aux objets :

<b>Objets</b> (le type est soit 'pics' (dfaut) soit 'dirs')
First($type)             Renvoie comme objet la premire 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 mme chose mais retourne au dbut 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 numro (type 'pics' ou 'dirs').
                          Si la variable $loop est positionne alors le
			  compteur rebouclera au dbut lors de la recherche

<b>Proprits des objets</b>
Chaque objet (image ou sous-album) possde des proprits.
L'accs  certaines proprits 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                  Boolen: est-ce que c'est un film ?
name                      Nom (nettoy et optionnel pour les lgendes)
cap                       Lgende de l'image
capfile                   Fichier optionnel des lgendes
alt                       Etiquette (tag) alt
num_pics                  [rpertoires seulement, -dir_thumbs] Nombre d'images dans le rpertoire
num_dirs                  [rpertoires seulement, -dir_thumbs] Nombre de sous-rpertoire dans le rpertoire

L'accs  des proprits se fait via un champ et un sous-champ. Par exemple,
chaque image comporte une information sur ses diffrentes tailles : plein
cran, moyenne et vignette (bien que la taille moyenne soit optionnelle).

Get($obj,$size,$field)      Retourne la proprit de l'image pour une taille donnee

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'accs 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 chane de caractres avec 'href'
Get($obj,'link',$from,$to)  Idem mais met le nom de l'objet  l'intrieur 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 rpertoires ont aussi :

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


<b>Albums parent</b>
Parent_Album($num)        Renvoie en chane de caractres le nom de l'album parent (incluant le href)
Parent_Albums()           Retourne une liste de chanes de caractres des albums parents (incluant le href)
Parent_Album($str)        Cre la chane de caractres $str  partir de l'appel   la fonction Parent_Albums()
Back()                    L'URL pour revenir en arrire 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 numro de l'image
Name($img)                Le nom nettoy ou lgend pour une image
Caption($img)             La lgende pour une image

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



<b>Quelques routines utiles</b>
Pretty($str,$html,$lines) Formate un nom.
    Si la variable $html est dfinie alors le code HTML est autoris
    (c'est--dire utilise 0 pour &lt;title&gt; et associs). Actuellement,
    prfixe seulement avec la date dans une taille de caractres plus petite
    (c'est--dire '2004-12-03.Folder').
    Si la variable $lines est dfinie 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 aprs cet objet ?
			  Utiliser la variable $off si l'offset du premier objet dmarre  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 indexe par
			  le langage (par dfaut, '_').
			  album choisit l'Image_Array en fonction de la dfinition des langages.
Border($img,$type,$href,@border)
Border($str,$x,$y,@border)
                          Cre une image entire entoure de bordures. Voir
			  'Bordures' pour de plus amples dtails.


Si vous crez un thme  partir de zro, considrez l'ajout du support pour
l'option -slideshow. Le moyen le plus facile de raliser cette opration est
de copier / coller le code "slideshow" d'un thme existant.


ITEM: Soumettre des thmes

Vous avez personnalis un thme ? Je serais ravi de le voir mme s'il est
totalement spcifique  votre site internet.

Si vous avez un nouveau thme 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
thme  MarginalHacks pour une utilisation libre ou si vous souhaitez le
mettre sous une license particulire.




ITEM: Conversion des thmes v2.0 aux thmes v3.0

La version v2.0 d'album a introduit une interface de thmes qui a t rcrite
dans la version v3.0 d'album. La plupart des thmes de la version 2.0 (plus
spcialement ceux qui n'utilisent pas la plupart des variables globales)
fonctionneront toujours mais l'interface est obsolte et pourrait disparatre
dans un futur proche.

La conversion des thmes de la version 2.0  la version 3.0 n'est pas bien
difficile.

Les thmes de la version 2.0 utilisent des variables globales pour tout un tas
de choses. Celles-ci sont maintenant obsoltes. Dans la version 3.0, vous
devez conserver une trace des images et des rpertoires dans des variables et
utiliser des 'itrateurs' 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 rcrire des appels cods avec
l'ancien style utilisant une variable globale en des appels cods avec le
nouveau style qui utilise une variable locale. Cependant pour utiliser ces
appels, vous devez modifier vos boucles comme ci-dessus.

Voici un tableau de conversion pour aider au passage des thmes de la version
2.0  la version 3.0 :

# Les variables globales ne doivent plus tre utilises
# OBSOLETE - Voir les nouvelles mthodes d'itrations avec variables locales
# ci-dessus
$PARENT_ALBUM_CNT             Rcrire avec : Parent_Album($num) et Parent_Albums($join)
$CHILD_ALBUM_CNT              Rcrire avec : my $dir = First('dirs');  $dir=Next($dir);
$IMAGE_CNT                    Rcrire 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 mthodes modifiant les variables globales
# OBSOLETE - Voir les nouvelles mthodes d'itrations 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            Obsolte, voir '$PARENT_ALBUM_CNT' ci-dessus
Parent_Album_Cnt              Obsolte, voir '$PARENT_ALBUM_CNT' ci-dessus
Next_Parent_Album             Obsolte, 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>
