====== Personnaliser Albulle ou comment créer un thème ======
* **Objectif** : modifier l'apparence d'Albulle
* **Niveau de difficulté** : difficile
Pour créer un thème il vous faut un minimum de connaissances en XHTML/CSS. Certaines modifications peuvent nécessiter de connaître PHP.Avant d'éditer les fichiers, je vous invite à lire l'[[:accueil|avertissement]] présent à l'accueil de la documentation si ce n'est pas déjà fait !
===== Tour d'horizon =====
Commençons par faire un tour de tout ce qu'il y a à savoir avant de pouvoir créer son thème.
==== Structure d'un thème ====
Les thèmes se situent dans le dossier **albulle/themes/**. **Un thème = un dossier** dont le contenu est le suivant :
^ Structure d'un thème ^^^
^ Nom ^ Type ^ Description ^
|css |dossier |Contient les **feuilles de styles** utilisées par le thème. |
|**html** |dossier |Contient les **patrons XHTML** qui définissent la structure des pages générées. |
|images |dossier |Dossier utilisé pour stocker toutes les **images du thème**. |
|js |dossier |Les éventuels **fichiers de code javascript** peuvent être stockés ici (le fichier de lightbox s'y trouve). |
|html.php |fichier |En créant ce fichier, vous avez la possibilité de **surcharger la façon dont les pages sont générées**. Il s'agit de code PHP et sa création est réservée à ceux qui ont un niveau avancé en PHP. |
//Un élément mis en gras est un élément obligatoire.//
Le dossier **html** ne doit **ni changer de nom**, **ni changer de place** car c'est un dossier qui est reconnu automatiquement par Albulle.
En revanche, vous êtes **libres** d'organiser le reste à votre convenance.
=== Le dossier CSS ===
L'organisation de ce dossier est libre. A vous de choisir, selon vos habitudes de développement, comment vous souhaitez structurer vos feuilles de styles. Pour ceux qui ne sauraient par où commencer, voici mon organisation des feuilles de styles.
En général, la liste des fichiers que je créé dès lors que je commence un thème est la suivante :
- **index.css** : c'est le seul fichier qui sera appelé dans l'entête HTML des pages web. Il ne me sert qu'à faire les inclusions des fichiers qui suivent.
- **layout.css** : ce fichier rassemble les class et id uniquement des éléments qui définissent la mise en page (titre + centre + pied ou titre + colonne gauche + colonne droite + pied, ...).
- **structure.css** : ici, je mets les informations de tous les éléments qui seront placés dans les différentes zones définies dans le fichier précédent.
- **color.css** : lui ne sert que pour définir les couleurs (de fonds, de textes, de bordures, ...) et les images constituantes du thème.
- **typo.css** : est utilisé pour définir les polices de caractères (familles, tailles, styles, espacements, ...).
- **fix-ie.css** : et enfin, le spécial, appelé uniquement quand la page est affiché depuis Internet Explorer, qui contient diverses corrections pour que les pages s'affichent correctement dans ce navigateur.
Voici ce que contient le fichier **index.css** :
@include url(layout.css);
@include url(structure.css);
@include url(color.css);
@include url(typo.css);
Pour le contenu des autres fichiers, c'est à vous de jouer :-D !
=== Le dossier "html" ===
Très important, il contient les **briques XHTML** qui constituent la structure finale des différentes pages générées. Chacun des fichiers doit se terminer par l'extension **.thm.php**. Le thème par défaut livré avec Albulle est constitué d'un certain nombre de patrons dont voici la liste :
^ Patrons XHTML du thème par défaut ^^
^ Nom ^ Description ^
|arborescence |Contient les 3 types d'éléments de l'arborescence des dossiers. Ce fichier est un peu particulier et son fonctionnement sera détaillé un peu plus loin. |
|diapo |Contient le cadre (
) qui définit la diapositive courante lorsque le mode diaporama est activé. |
|dossier_vide |Patron du cadre affiché lorsque le dossier courant est vide. |
|form_defilement_auto |Il s'agit du formulaire qui permet de lancer le défilement automatique du diaporama. |
|header |Entête HTML des pages qui seront générées (Ouverture de la balise et définition des métas données (). |
|index |Squelette principal des pages. |
|menu_panier |Définit la liste (
) du menu du panier. |
|metas |Définit les balises appelées depuis le fichier **header**. |
|pagination |Patron du cadre des liens de pagination. |
|popup |Squelette de l'affichage des photos dans une popup Javascript. |
|rappel_sous_dossier |Squelette du bloc de rappel des sous-dossiers. |
|texte |Patron utilisé pour afficher un simple texte de contenu. |
|vignette |Squelette d'une vignette pour la liste des photos de la page en cours (utilisé en mode galerie ainsi qu'en mode diaporama). |
===== Le pseudo-langage =====
Un **thème Albulle** est écrit en code XHTML et est lié au moteur du script via un **pseudo-langage** composé de **pseudo-éléments** qui permettent d'écrire du code générique et ainsi réduire considérablement la quantité de code à rédiger.
Le **principe d'un pseudo-langage** est le suivant : tout **pseudo-élément** placé dans le code HTML d'un gabarit sera remplacé par son contenu une fois le traitement des données terminé afin d'afficher les pages du site. Les **pseudo-éléments** sont comme des marqueurs qu'**Albulle** recherche et reconnait (c'est l'action de **"parser"** un gabarit).
Le **pseudo-langage** d'Albulle est un **langage passif**, c'est-à-dire que vous ne pouvez définir vos propres pseudos-éléments à moins de modifier le coeur d'Albulle (cf personnalisation avancée).
Ce pseudo-langage est relativement simple et rassemble différents **types de pseudos-éléments** :
==== Les pseudos-variables simples ====
Une **pseudo-variable simple** (nommée plus couramment pseudo-variable), permet l'affichage d'un texte simple qui provient soit d'un élément de configuration (le titre du site, le sous-titre, ...), soit de données diverses (nom d'une photo, poids, nom d'un dossier, texte de la page, ...) ou encore d'éléments générés par **Albulle**.
Une **pseudo-variable** se présente sous la **forme** :
{NOM_DE_LA_PSEUDO_VARIABLE}
==== Les pseudos-variables d'inclusion ====
Une **pseudo-variable d'inclusion** (ou "inclusion" pour faire plus court) se comporte de la même façon qu'une pseudo-variable simple. C'est ce qui est à l'origine qui est différent : le contenu d'un tel marqueur est dans la plupart des cas le résultat de la génération d'un autre gabarit. Je dis dans la plupart des cas, car le contenu de certaines inclusions est généré en dur par le coeur d'Albulle (= il n'existe pas de fichier de gabarit pour ces marqueurs).
Une **inclusion** est de la **forme** :
{>NOM_INCLUSION}
==== Les blocs conditionnels ====
Un **bloc conditionnel** entoure une portion de code HTML. Cette portion de code sera alors générée ou effacée selon l'état de la condition associée au bloc.
Un bloc conditionnel est de la forme :
...code HTML...
===== Pseudos-éléments globaux =====
Certaines éléments ne sont pas locaux à un gabarit particulier et peuvent être placées indifféremment dans n'importe lequel.
==== Pseudos-variables ====
^Nom ^Description ^
|CHEMIN_ROOT |Reporte le contenu du paramètre **JB_AL_ROOT** pour construire les chemins. |
|CHEMIN_THEME |Chemin complet du thème actif. |
|REP_COURANT |Répertoire des photos ouvert. |
|VERSION |Numéro de version d'Albulle. |
|LIEN_RETOUR_SITE |Si utilisé, le lien qui permet de retourner à votre site principal. |
|NAVIGATION |Fil d'ariane de la navigation dans les dossiers. |
|ARBORESCENCE |Arborescence des dossiers de photos. |
|NOMBRE_FICHIERS_PANIER |Nombre de fichiers présents dans le panier. |
|POIDS_ESTIME |Poids estimé de l'archive résultante du panier. |
|PANIER_CAPACITES |Capacités maximum du panier. |
|MENU_PANIER |Menu de contrôle du panier. |
==== Inclusions ====
^Nom ^Description ^
|>HEADER |Inclusion du gabarit [[personnalisation#header.thm.php|header]]. |
|>BARRE_MENU |Inclusion du gabarit [[personnalisation#pagination.thm.php|pagination]]. |
|>TEXTE_DOSSIER |Inclusion du gabarit [[personnalisation#texte.thm.php|texte]] parsé soit avec le texte d'accueil soit avec le texte du dossier s'il existe. |
|>CONTENU_DROITE |Inclusion du gabarit [[personnalisation#vignette.thm.php|vignette]] pour le mode galerie et aussi du gabarit [[personnalisation#diapo.thm.php|diapo]] quand le mode diaporama est activé. |
|>SOUS_DOSSIER |Inclusion du gabarit [[personnalisation#rappel_sous_dossiers.thm.php|rappel_sous_dossiers]]. |
==== Blocs conditionnels ====
^Nom ^Description ^
|ENTETE |Permet d'afficher / cacher l'entête de page (qui contient le titre et le sous-titre). Relatif au paramètre **JB_AL_AFFICHER_ENTETE**. |
|ACCUEIL |Actif uniquement lorsque l'on se trouve sur la page d'accueil (:!: disponible depuis la version 1.1.1) |
|MODE_GALERIE |Valable quand le mode galerie est activé (:!: depuis la version 1.1.1, ce bloc est global à tous les patrons). |
|NON_INTEGRE |En mode autonome (= Albulle n'est pas inclu dans un site) toutes les portions de code contenues dans un bloc de ce nom seront affichées, sinon elles sont cachées. |
|PANIER_ACTIF |Toutes les portions de code contenues dans un bloc de ce nom seront affichées tant que le panier est actif (paramètre **JB_AL_PANIER_ACTIF**). |
===== Pseudos-éléments locaux aux gabarits =====
==== arborescence.thm.php ====
Ce gabarit est un peu particulier puiqu'il possède une forme propre qui ne doit en aucun cas être modifiée.
Vous y trouverez trois lignes, chacune d'elles correspondant à un élément de liste bien spécifique :
- La 1ère ligne représente l'élément de liste par défaut, affiché quand votre dossier de photos ne contient pas encore de sous-dossiers,
- La deuxième ligne correspond à l'élément de liste qui permet de remonter au dossier parent,
- Et la dernière ligne est le gabarit générique d'un dossier de l'arborescence.
Il est impératif de respecter l'ordre de ces trois lignes. Vous pouvez adpater le code de chacune d'elles mais vous ne devez ni supprimer, ni ajouter d'autres lignes à ce fichier.
^Pseudos-variables ^^
^Nom ^Description ^
|HREF_REMONTER |URL pour remonter dans le dossier parent. Définie uniquement si l'on se trouve dans un dossier enfant. |
|HREF_DOSSIER |URL du dossier dans l'arborescence. |
|ID_COURANT |Attribut "id", généré uniquement pour le dossier ouvert. |
|NOM_DOSSIER |Nom affiché du dossier. |
|NB_IMAGES |Si demandé dans la configuration, contient la chaîne avec le nombre d'images présentes dans le dossier. |
==== diapo.thm.php ====
Le gabarit **diapo** sert uniquement quand le **mode diaporama** est activé. Il comprend le bloc complet qui rassemble la photo, les boutons de navigation, le formulaire qui permet de lancer le défilement automatique et les blocs d'informations de l'image (informations générales et données EXIF si la photo en possède).
Certaines pseudos-variables ne sont utilisables qu'au sein d'un bloc conditionnel et quand ce bloc est affiché.
Il est important de respecter les imbrications des blocs conditionnels si vous souhaitez conserver une présentation cohérente de votre thème.
* **DIAPO_NON_VIDE** : affiché quand une photo est définie.
* **PLUSIEURS_DIAPOS** : dès lors qu'un dossier comprends plus d'une photo, ce bloc est affiché.
* **EXIF** : si la photo contient des données EXIF, tout ce qui se trouve dans ce bloc est affiché.
* **DIAPO_VIDE** : affiché lorsqu'aucune photo n'est définie (Ce cas ne peut se produire que si l'utilisateur modifie les paramètres de l'URL).
^Pseudos-variables disponibles dans le bloc **DIAPO_NON_VIDE** ^^
^Nom ^Description ^
|HREF_IMAGE |URL de l'image affichée. A placer dans l'attribut **href** du lien. |
|TARGET_BLANK |Si le paramètre **JB_AL_OUVERTURE_BLK** est **vrai**, alors cette variable est définie et contient l'attribut **target="_blank"**. |
|LIGHTBOX |Si le mode LightBox est activé (**JB_AL_OUVERTURE_JS** et **JB_AL_OUVERTURE_LBX** sont **vrais**), contient **rel="lightbox[albulle]"**. |
|JAVASCRIPT |Code Javascript de l'ouverture de la popup quand le mode Javascript est activé (**JB_AL_OUVERTURE_JS** = **faux** et **JB_AL_OUVERTURE_LBX** = **vrai**). |
|SOURCE_DIAPO |Idem **HREF_IMAGE** mais pour l'attribut **source** de la balise ****. |
|ALT_DIAPO |Texte alternatif de l'image à placer dans l'attribut **alt** de l'image. |
|NOM_PHOTO |Nom de la photo, présenté selon les paramètres choisis dans la configuration (cf. [[parametrage#donnees_a_afficher|Données à afficher : Zone vignette]]). |
|TYPE_MIME |[[http://fr.wikipedia.org/wiki/Type_MIME|Type MIME]] de l'image. |
|DIMENSIONS_PHOTO |Dimensions de l'image : "largeur x hauteur". |
|POIDS_PHOTO |Poids de la photo : poids + unité. |
^Pseudos-variables disponibles dans le bloc **PLUSIEURS_DIAPOS** ^^
^Nom ^Description ^
|BOUTON_SUIVANTE |Balise complète du lien vers l'image suivante ; vide quand on se trouve sur la dernière image. |
|BOUTON_PRECEDENTE |Balise complète du lien vers l'image précédente ; vide quand on se trouve sur la première image. |
^Pseudos-variables disponibles dans le bloc **EXIF** ^^
^Nom ^Description ^
|DONNEES_EXIF |Données EXIF contenues dans la photo. Liste non ordonnée de la forme **
Elément : valeur
...
**. |
==== dossier_vide.thm.php ====
Sert à afficher un texte par défaut lorsqu'un dossier ne possède pas encore d'images. Ce gabarit ne possède pas de pseudos-variables qui lui sont propres.
**Depuis la version 1.1**, ce gabarit ne sert que lorsque le paramètre **JB_AL_AFFICHER_TXT_VIDE** est vrai.
==== form_defilement.thm.php ====
Définit le gabarit du formulaire, affiché quand le mode diaporama est activé, qui permet de lancer le défilement automatique.
^Pseudos-variables ^^
^Nom ^Description ^
|FORM_DEFILEMENT_ACTION |Valeur à placer dans l'attribut **action** du formulaire. |
|INTERVALLE_TEMPS |Valeur placée dans l'attribut **value** du champ de saisie du temps de pause (en secondes) entre chaque image. |
|SUBMIT_NAME |Valeur de l'attribut **name** du bouton d'envoi (). |
|SUBMIT_VALUE |Valeure de l'attribut **value** du bouton d'envoi. |
==== header.thm.php ====
Gabarit des entêtes de la page générée : bloc **
** et début du bloc **
**.
^Pseudos-variables ^^
^Nom ^Description ^
|>METAS |**Inclusion** du gabarit [[personnalisation#metas.thm.php|metas.thm.php]]. |
|TITRE_PAGE |Valeur à placer dans la balise ****. |
==== index.thm.php ====
Il s'agit là du gabarit principal qui va permettre la construction finale de vos pages. C'est à partir d'**index.thm.php** que les autres gabarits vont être inclus.
Voici la **structure des blocs conditionnels** disponibles :
* **ENTETE** : cadre d'entête de la page qui contient titre et sous-titre. Ce bloc n'est affiché que si **JB_AL_AFFICHER_ENTETE** est à **vrai**.
* **PANIER_ACTIF** : affiché si la fonctionnalité du panier est active. Ce bloc n'est affiché que si **JB_AL_PANIER_ACTIF** est à **vrai**.
* **NON_INTEGRE** : en mode autonome (soit **JB_AL_INTEGRATION_SITE = faux**), ce bloc est affiché et permet d'enlever le pied de page si le mode intégré est activé.
^Pseudos-variables du bloc ENTETE ^^
^Nom ^Description ^
|TITRE_GALERIE |Titre donné à votre site dans le paramètre **JB_AL_TITRE_GALERIE**. |
|SOUS_TITRE_GALERIE|Sous-titre donné à votre site dans le paramètre **JB_AL_SOUS_TITRE_GALERIE**. |
^Pseudos-variables du bloc PANIER_ACTIF ^^
^Nom ^Description ^
|NOMBRE_FICHIERS_PANIER |Donne le nombre total de fichier actuellement présents dans le panier. |
|POIDS_ESTIME |Donne l'information du poids estimé de l'archive qui sera générée. |
|PANIER_CAPACITES |Affiche la capacité maximum du panier. |
|MENU_PANIER |Retourne le menu complet du panier généré depuis le gabarit [[personnalisation#menu_panier.thm.php|menu_panier]]. |
^Pseudos-variables générales ^^
^Nom ^Description ^
|LIEN_RETOUR_SITE |Si **JB_AL_HOME_HREF** et **JB_AL_HOME_TEXTE** sont définis, ce lien est généré pour être affiché. |
|NAVIGATION |Il s'agit du fil d'ariane, c'est-à-dire du chemin complet qui mène au dossier en cours. |
|>BARRE_MENU |Inclusion du gabarit [[personnalisation#paginsation.thm.php|pagination]]. |
|>TEXTE_DOSSIER |Si un fichier **texte.html** est présent dans le dossier en cours, il est alors disponible dans cette pseudo-variable. |
|>CONTENU_DROITE |Contient le contenu principal des pages ; soit les miniatures si le mode galerie est actif soit la diapositive courante si c'est le mode diaporama qui est activé. |
|>SOUS_DOSSIERS |Si **JB_AL_RAPPELER_SOUS_DOSSIERS** est **vrai** alors la liste des sous-dossiers du dossier en cours est disponible via cette pseudo-variable. C'est de résultat de la génération du gabarit [[personnalisation#rappel_sous_dossiers.thm.php|rappel_sous_dossiers]]. |
|ARBORESCENCE |Contient le menu des dossiers en fonction du dossier en cours (sans les balises **
** de premier rang qui doivent être codées à la main dans le gabarit). Ces éléments peuvent être modifiés en modifiant le gabarit [[personnalisation#arborescence.thm.php|arborescence]]. |
==== menu_panier.thm.php ====
Ce gabarit contient uniquement la liste à puces qui permet de générer le menu du panier.
^Pseudos-variables ^^
^Nom ^Description ^
|PANIER_URL_TELECHARCHER |URL qui permet le téléchargement du panier. |
|PANIER_URL_VOIR |URL pour demander l'exploration du panier. |
|PANIER_URL_VIDER |URL pour demander la purge du panier. |
==== metas.thm.php ====
Ce gabarit ne contient que les métas qui sont ensuite réintégrées dans le gabarit [[personnalisation#header.thm.php|header]] via la pseudo-variable d'inclusion **{>METAS}**.
C'est ici que sont fait les appels des feuilles de styles, des fichiers javascript, etc... Toutes les metas, exceptée la balise **** doivent être placées dans ce gabarit car en mode intégré, les métas sont toujours générées (alors que le gabarit [[personnalisation#header.thm.php|header]] ne l'est plus) pour le cas où vous auriez besoin de les intégrer dans les métas du script hôte.
Le gabarit contient **les blocs conditionnels** suivants :
* **LIGHTBOX** : contient les appels des fichiers javascript nécessaire au fonctionnement du mode LightBox (si activé).
* **POPUP** : contient le code javascript qui permet l'ouverture des images dans une fenêtre Popup (si activé).
* **DEFILEMENT_AUTO** : en mode diaporama, il est possible d'activer le défilement automatique. Pour ce faire, il faut placer la balise méta qui convient.
^Pseudos-variable du bloc DEFILEMENT_AUTO ^^
^Nom ^Description ^
|INTERVALLE_TEMPS |Temps d'attente entre chaque image. |
|URL_IMAGE_SUIVANTE |URL de la prochaine image à afficher. |
==== pagination.thm.php ====
Le gabarit **pagination** permet de construire le menu inclu dans le gabarit [[personnalisation#index.thm.php]] depuis la pseudo-variable d'inclusion **{>BARRE_MENU}**.
Il rassemble le bouton de changement de mode d'affichage, les boutons d'ajout/retrait de toutes les images de la page en cours au panier et la pagination du dossier courant.
^Pseudos-variables ^^
^Nom ^Description ^
|LIEN_MODE_AFFICHAGE |URL qui permet la bascule du mode d'affichage. |
|TEXTE_MODE_AFFICHAGE |Texte du lien pour le changement du mode d'affichage. |
|PAGINATION |Liste des pages disponible dans le dossier en cours. |
^Pseudos-variables du bloc PANIER_ACTIF ^^
^Nom ^Description ^
|PANIER_TOUT_AJOUTER |Balise **** complète du lien pour ajouter toutes les images de la page en cours au panier. |
|PANIER_TOUT_RETIRER |Idem que précédemment mais pour le retrait. |
==== popup.thm.php ====
Le gabarit popup est un peu particulier puisqu'il ne fait appel à aucun autre des gabarit et redéfinit intégralement une page (entêtes + corps). C'est lui qui est utilisé lorsque vous activez le mode d'affichage par popup javascript pour visualiser les images.
^Pseudos-variables ^^
^Nom ^Description ^
|POPUP_TITRE |Titre à donner la la fenêtre (balise ****). |
|POPUP_SOURCE |Chemin d'accès à l'image à afficher (à placer dans l'attribut **src** d'une balise ****. |
==== rappel_sous_dossier.thm.php ====
Gabarit de la liste des sous-dossiers qui peut éventuellement être rappelée sous les miniatures du dossier courant.
^Pseudo-variable ^^
^Nom ^Description ^
|RAPPEL_SOUS_DOSSIERS |Liste des dossiers existants dans le dossier en cours. Code XHTML complet de la forme **
...
**. |
==== texte.thm.php ====
Utilisé pour l'affichage des textes : page d'accueil (**texte_accueil.html**) et textes des dossiers (si un fichier **texte.html** est présent).
^Pseudo-variable ^^
^Nom ^Description ^
|CONTENU_TEXTE |Contenu des fichiers textes. |
==== vignette.thm.php ====
Gabarit qui définit le format d'une vignette, pour l'affichage des miniatures. Ce gabarit sera utilisé dans la boucle de construction des miniatures de la page courante.
Le gabarit comprend un **bloc conditionnel** qui lui est propre :
* **MODE_GALERIE** : affiché quand le mode galerie est activé.
Depuis la version 1.1.1, le bloc conditionnel **MODE_GALERIE** est global à tous les patrons.
^Pseudos-variables ^^
^Nom ^Description ^
|CLASSE_VIGNETTE |Classe CSS de la vignette : **vignette** pour le mode galerie, **vignetteDiapo** pour le mode diaporama. |
|DIAPO_COURANTE |Attribut **id="diapoCourante"** généré uniquement pour la vignette qui est la diapositive courante du mode diaporama. |
|HREF_IMAGE |Chemin d'accès à l'image à placer dans l'attribut **href** du lien de la miniature. |
|TARGET_BLANK |Contient l'attribut **target="_blank"** si **JB_AL_OUVERTURE_BLK** est **vrai**. |
|LIGHTBOX |Contient l'attribut **rel="lightbox[albulle]"** si le mode LightBox est activé. |
|JAVASCRIPT |Contient le code de lancement de la popup javascript si activée (attribut **onclick="..."**). |
|CHEMIN_MINIATURE |Chemin de l'image miniature. |
|CLASSE_MINIATURE |Classe CSS de la miniature. |
|ALT_IMAGE |Texte alternatif à placer dans l'attribut **alt** de la balise ****. |
^Pseudos-variables du bloc MODE_GALERIE ^^
^Nom ^Description ^
|NOM_PHOTO |Nom de la photo. |
|DIMENSIONS_PHOTO |Dimensions de la photo. |
|POIDS_PHOTO |Poids de la photo. |
^Pseudos-variables du bloc PANIER_ACTIF ^^
^Nom ^Description ^
|PUCE_AJOUT_PANIER |Balise **** du lien qui permet l'ajout ou le retrait de l'image dans le panier. |
====== Personnalisation avancée ======
* **Objectif** : modifier le moteur d'affichage d'Albulle
* **Niveau de difficulté** : expert
Par défaut, les gabarits et la structure des pages correspondent à un schéma conditionné par le moteur d'affichage d'Albulle (le fichier **core/include/html.php**). L'agencement des éléments constitutifs des pages peut être modifié dans une certaine mesure mais des limites peuvent apparaître si vous souhaitez le modifier plus en profondeur.
C'est pourquoi Albulle reconnait la surcharge du moteur d'affichage. Vous pouvez, dans votre thème, **réécrire un nouveau html.php** pour l'adapter en fonction de vos besoins. Dès lors, tout est permis ! Cela va de quelques ajustements mineurs à la possibilité de restructurer intégralement un thème en recréant des gabarits.
===== Surcharger le moteur d'affichage =====
Pour surcharger le moteur d'affichage d'Albulle il vous suffit de créer un fichier nommé **html.php** à la racine du dossier de votre thème. Albulle le reconnaîtra automatiquement et l'utilisera en lieu et place du sien.
Pour commencer en douceur vous pouvez copier-coller le moteur d'affichage par défaut dans le dossier du thème, analyser son code pour l'appréhender et lui apporter les modifications voulues.Le **thème Zen** embarque un moteur d'affichage légèrement modifié (le bloc des données EXIF n'est pas placé au même endroit et un gabarit supplémentaire est présent pour le gérer). Il peut être intéressant de comparer les différences entre le moteur par défaut et celui-là.
===== Contraintes =====
Avant de vous lancer dans la création d'un moteur d'affichage, vous devez **impérativement** prendre connaissance des quelques **contraintes à respecter** pour que votre moteur fonctionne parfaitement.
__**1ère contrainte :**__
Le **code XHTML** de la page générée doit être **retourné** à la fin de l'exécution d'**html.php** :
Ce n'est pas au moteur d'afficher le résultat.
__**2ème contrainte :**__
Une installation d'Albulle peut servir dans le cadre d'une **intégration** dans un autre site Internet. Dans ce cas, le moteur **doit définir une variable**, nommée **$sThmCssMeta** qui doit contenir les balises métas utilisées pour le bon fonctionnement d'Albulle et qui doivent être placées dans la partie **
** du site hôte.
Dans le moteur par défaut, cette variable contient le résultat de la génération du gabarit **meta.thm.php**.
L'absence de cette variable n'empêchera pas Albulle de fonctionner en mode autonome. Elle enlèvera en revanche une fonctionnalité non négligeable dans le cas d'une intégration.
===== Référence des variables =====
Deux éléments sont à votre disposition pour pouvoir monter votre propre moteur d'affichage. Ces deux éléments sont des tableaux : **$_JB_AL_VARS** et **$_MINATURES**. Le premier contient l'ensemble des **variables globales** définies et permet de récupérer certaines infos et de connaître l'état dans lequel se trouve Albulle. Le deuxième contient l'ensemble des photos de la page en cours.
Rappelons, qu'à ces ressources, sont aussi disponibles les **constantes** qui définissent la [[parametrage|configuration d'Albulle]].
==== $_JB_AL_VARS ====
^Nom ^Type ^Description ^
|a_menu_panier |array |Tableau des URL de manipulation du panier. //Voir le détail après ce tableau.// |
|a_panier |array |Contient les informations sur l'état du panier. //Voir le détail après ce tableau.// |
|b_defilement_auto |boolean |Utilisable uniquement quand le mode diaporama est actif, le paramètre permet de savoir si le défilement automatique est activé ou non. |
|b_mode_diaporama |boolean |**Vrai** si le mode diaporama est actif. |
|b_voir_panier |boolean |**Vrai** si l'utilisateur a demandé à voir le contenu du panier. |
|i_diapo_courante |integer |Indice de la diapositive en cours d'affichage. Défini quand le défilement automatique est actif. |
|i_intervalle_tps |integer |Temps d'attente (en secondes) entre chaque diapositive. Défini quand le défilement automatique est actif. |
|s_acces_theme |string |Chemin d'accès au dossier du thème actif. |
|s_arborescence |string |Chaîne XHTML qui contient l'arborescence complète des dossiers (selon le dossier courant). |
|s_classe_css_vignette |string |Classe CSS à appliquer aux vignettes. |
|s_defilement_submit_name |string |Nom du bouton de lancement/arrêt du défilement automatique. Vaut alternativement "arreter" ou "lancer". |
|s_defilement_submit_value |string |Libellé du bouton de lancement/arrêt du défilement automatique. |
|s_lien_mode_affichage |string |URL qui permet de basculer entre le mode diaporama et le mode galerie. |
|s_lien_panier_tout_ajouter |string |URL à utiliser pour ajouter toutes les images du dossier courant au panier. |
|s_lien_panier_tout_supprimer |string |URL à utiliser pour supprimer du panier toutes les images du dossier courant qui y sont présentes. |
|s_navigation |string |Fil d'ariane en fonction du dossier courant. |
|s_pagination |string |Pagination pour la navigation dans les différentes page du dossier courant. |
|s_rappel_sous_dossiers |string |Si activé dans la configuration, contient la liste des sous-dossiers du dossier courant. |
|s_rep_courant |string |Chemin d'accès au répertoire courant des photos. |
|s_texte_mode_affichage |string |Texte du lien qui permet de basculer entre les modes d'affichage. |
|s_titre_meta |string |Titre de la page courante. A utiliser pour définir la balise ****. |
|s_url_img_precedente |string |URL de l'image précédente. Définie quand le mode diaporama est actif. |
|s_url_img_suivante |string |URL de l'image suivante. Définie quand le mode diaporama est actif. |
|s_version |string |Numéro de version d'Albulle. |
=> **Détails de "a_menu_panier"**
Le contenu de la variable **$_JB_AL_VARS['a_menu_panier']** est un tableau associatif qui contient les sous-éléments suivants :
^Nom ^Type ^Description ^
|s_url_download |string |URL à appeler pour demander le téléchargement du panier. |
|s_url_voir |string |URL à appeler pour voir le contenu du panier. |
|s_url_vider |string |URL à appeler pour vider le panier. |
Exemple de code pour accéder à ces éléments :
echo $_JB_AL_VARS['a_menu_panier']['s_url_download'];
=> **Détails de "a_panier"**
Le contenu de la variable **$_JB_AL_VARS['a_panier']** est aussi un tableau associatif qui contient les sous-éléments suivants :
^Nom ^Type ^Description ^
|b_plein |boolean |**Vrai** quand le panier est plein. |
|i_nb_fichiers |integer |Nombre de fichiers présents dans le panier. |
|s_poids_estime |string |Chaîne formatée qui contient l'estimation du poids de l'archive qui sera générée depuis le contenu du panier. |
==== $_MINIATURES ====
Cette variable est un **tableau à plusieurs dimensions**. La **première dimension** est un tableau standard dont **chaque élément** représente une **miniature**. On accède à une miniature via son indice :
print_r( $_MINIATURES[$i] );
Chaque élément de cette première dimension est un **tableau associatif** qui contient toutes les informations nécessaires pour présenter les miniatures des photos dans une page :
^Nom ^Type ^Description ^
|CHEMIN_PHOTO |string |Chemin d'accès la photo. Exemple : "albulle/data/photo/un_dossier/une_image.jpg" |
|CHEMIN_PHOTO_URL |string |La même chose que l'élément précédent mais encodé (avec **urlencode()**) pour pouvoir être utilisé dans une URL. |
|LIEN_PHOTO |array |Tableau dont les éléments permettent de construire la balise du lien vers la photo réelle. //Voir les détails après le tableau.//|
|NOM_PHOTO |string |Nom de la photo ; avec ou sans extension, avec ou sans tiret bas, selon le paramétrage défini. Exemple : "mon paysage.jpg" |
|DIM_PHOTO |string |Dimensions de la photo. Exemple : "1024 x 768" |
|SIZE_PHOTO |string |Poids de la photo, avec l'unité. Exemple : "75 Ko" |
|PANIER |array |Tableau dont les éléments permette de constuire la balise du lien d'ajout ou de retrait dans le panier. |
|EXIF |array |Données EXIF de la photo. Défini uniquement lorsque le mode diaporama est actif. |
=> **Détails de "LIEN_PHOTO"**
Le tableau **LIEN_PHOTO** contient les éléments suivants (selon le paramétrage défini, certains éléments seront vides) :
^Nom ^Type ^Description ^
|HREF |string |URL de l'image à placer dans l'attribut **href** du lien. |
|TARGET |string |Contient l'attribut **' target="_blank"'** ou une chaîne vide selon les paramètres établis pour l'ouverture des images. |
|JAVASCRIPT |string |Contient l'attribut **' onclick="..."'** ou une chaîne vide.|
|LIGHTBOX |string |Contient l'attribut **''** ou une chaîne vide. |
|CHEMIN_MIN |string |Chemin de la miniature. |
|CLASSE_CSS |string |Contient le nom de la classe CSS à appliquer à la balise **** de la vignette. Valeurs possibles : "miniature" ou "miniature_defaut" si l'image cible fait plus de 5Mpx et que la miniature n'a pas pu être générée. |
|ALT |string |Chaîne à placer dans l'attribut **alt** du lien. Contient le chemin de la photo. |
=> **Détails de "PANIER"**
^Nom ^Type ^Description ^
|MODE |string | Contient **"ajout"** ou **"retrait"** selon que la photo, respectivement, **ne se trouve pas** ou **se trouve** dans le panier. |
|URL |string |URL qui permet soit **d'ajouter** soit **de retirer** l'image du panier. |
Exemples de lecture des informations :
// Lire le nom de la 4ème photo
echo $_MINIATURES[3]['NOM_PHOTO'];
// Obtenir l'URL de cette miniature
echo $_MINIATURES[3]['LIEN_PHOTO']['HREF'];
__**Cas du mode diaporama :**__
Quand le mode diaporama est actif, un **élément supplémentaire** est présent pour la photo en cours d'affichage (et uniquement pour celle là) :
// Accès à la diapositive affichée
print_r( $_MINIATURES[$_JB_AL_VARS['i_diapo_courante']] );
L'élément supplémentaire est **"LIEN_DIAPO"** et ses sous-éléments sont les suivants :
^Nom ^Type ^Description ^
|HREF |string |Idem que pour **LIEN_PHOTO**. |
|TARGET |string |Idem que pour **LIEN_PHOTO**. |
|JAVASCRIPT |string |Idem que pour **LIEN_PHOTO**. |
|LIGHTBOX |string |Idem que pour **LIEN_PHOTO**. |
|ALT |string |Idem que pour **LIEN_PHOTO**. |