MarginalHacks album - Création de thèmes - Documentation

| A l b u m S i x - - C r � � a t i o n d e t h � � m e s

### Home
### Themes/Examples
### Languages
### Plugins
### License
### Download
### Documentation English Deutsch Español Français Nederlands Русский Italiano magyar
### Mailing List
### CHANGELOG
### Praises
### Contact
| Table Of Contents Métodes Editer le code HTML d'un thème existant Le moyen facile : simmer_theme pour les graphiques Partir de zéro : l'API des thèmes Soumettre des thèmes Conversion des thèmes v2.0 aux thèmes v3.0 Traduit par:
    1:   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.

    2:   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.

    3:   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 qu'un
    fichier Font ou Style.css, alors l'utilitaire simmer_theme vous permettra de
    réaliser des thèmes.

    Fichiers :
    Font/Style.css
    Ce fichier détermine les fontes utilisées par le thème. Le fichier "Font" est
    le plus ancien système, décrit ci-dessous. Créez un fichier Style.css et
    définissez des styles pour : body (le corps), title (le titre), main (la page
    principale), credit (le crédit) 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'">
    --------------------------------------------------

    CREDIT
    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).

    Null.gif
    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 :

    Images de la barre
    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).

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

    Images de fond
    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.

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

    Next.gif, Prev.gif, Back.gif
    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.

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

    Images des bordures
    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 :

      4 morceaux  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 :

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

      12 morceaux  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.

      Bordures chevauchantes  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
    n'est pas 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 "Themes/FunLand" pour un exemple simple.

    Images polyglottes
    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 "Themes/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 :

    % album -list_html_trans > trans.html

    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-8 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 !

    4:   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:

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

    Chemins et options
    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

    En-tête et pied-de-page
    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 :

    Objets (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

    Propriétés des objets
    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'<img src> 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

    Albums parent
    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

    Images
    This_Image                L'objet image pour une page d'image
    Image($img,$type)         Les étiquettes d'<img> 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

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

    Quelques routines utiles
    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 $lines 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 <img> à 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.

    5:   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.

    6:   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 un 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), "</a>";
    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/<br>//g if $nobr;
                                  print $name,"</a>";
    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()

    7:   Traduit par:

    Jean-Marc [jean-marc.bouche AT 9online.fr]
Created by make_faq from Marginal Hacks

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |