Intégration dans un site
- Objectif : Intégrer Albulle dans un site existant
- Niveau de difficulté : Avancé
A contrario de l'installation autonome, le mode intégration est l'utilisation d'Albulle dans un site existant. Albulle a été pensé pour pouvoir s'intégrer au mieux à votre site Web. Cet article présente les étapes nécessaires pour réaliser une telle opération.
Préambule
Je pars du principe que vous êtes déjà passé par la documentation de l'installation en mode autonome. Si ça n'est pas le cas, je vous invite à la lire avant de passer à l'intégration.
Il y a deux façons de faire pour réaliser l'intégration :
- Méthode I : paramétrer Albulle depuis son fichier de configuration principal,
- Méthode II : réaliser le paramétrage en utilisant la surcharge de la configuration : il faut mettre un peu plus de code mais cela a l'avantage de laisser la configuration d'Albulle en utilisation standard, ce qui peut vous permettre d'envisager deux accès à vos galeries : soit en mode intégré soit dans une page externe en mode standard.
Quelle que soit la méthode que vous choisirez, il vous faudra quoi qu'il arrive adapter un thème à votre interface pour qu'Albulle s'intègre visuellement à votre design !
Méthode I : La classique
Modification des paramètres
Ouvrez config.php et commencez par définir la constante JB_AL_INTEGRATION_SITE à true (ligne 178). Enregistrez et testez : vous obtenez alors une page sans style avec le titre et le sous-titre.
Si vous ne souhaitez pas conserver l'entête qui contient le titre et le sous-titre, définissez la constante JB_AL_AFFICHER_ENTETE à false (ligne 55). Enregistrez et testez : vous n'avez plus d'entête !
Appel du script
Il faut maintenant faire l'appel au fichier explore.php là où vous le souhaitez dans votre code à vous. Vous noterez qu'il est obligatoire de définir la constante JB_AL_ROOT avec le chemin d'accès au dossier d'Albulle avant l'appel. Voici le code à copier (code quasiment identique à ce qui se trouve dans le index.php de l'installation par défaut) :
define( 'JB_AL_ROOT', 'chemin/vers/dossier/albulle/' ); $sPageAlbulle = require_once( JB_AL_ROOT.'core/explore.php' ); // Le code qui suit montre simplement l'existence des deux variables à utiliser au bon endroit pour votre site echo $sThmCssMetas; echo $sPageAlbulle ;
- $sThmCssMetas est une variable qui contient les liens vers les fichiers CSS et javascripts à placer dans vos metas à vous (entre <head>…</head>).
- $sPageAlbulle est la variable qui contient le code XHTML de la page d'Albulle en mode intégré, soit le cadre principal <div id=“albulle”>…</div>.
A vous d'exploiter ces variables correctement dans votre code !
Démarrer une session
Avant dernière chose, si vous ne l'avez pas déjà fait dans votre code : démarrer une session.
Albulle repose principalement sur l'objet qui gère le panier de fichiers. Ce panier utilise une variable de session pour fonctionner. Lors de la création du panier, il vérifie s'il n'y a pas déja une session et s'il n'y en a pas, il la créé. Or une session doit être démarrée avant tout affichage dans le navigateur (cf Doc Php). Comme vous intégrez Albulle dans un site, il est possible que nous n'ayez pas organisé votre code de façon à n'afficher la page qu'une fois les traitements effectués. Pour éviter un Warning il vous faut donc rajouter la ligne suivante au tout début de votre code (votre index.php par exemple) :
session_start();
Créer un thème
Dernière chose mais non des moindres : créer un thème adapté à votre site ! Pour cela je vous renvoie à l'article qui traite le sujet.
Méthode II : La surcharge
Cette méhode est beaucoup plus rapide à mettre en place mais nécessite de taper un peu plus de code ; mais s'il n'y a que ça, pourquoi s'en priver ? Dans ce cas, on ne touche à rien à la configuration actuellement en place : nous allons juste surcharger les éléments qu'il faut pour pouvoir intégrer Albulle.
Exemple de code
Voici le code à placer où bon vous semble dans votre code :
define( 'JB_AL_ROOT', 'chemin/vers/dossier/albulle/' ); define( 'JB_AL_AFFICHER_ENTETE', false ); define( 'JB_AL_DOSSIER_THEME_ACTIF', 'albulle/' ); define( 'JB_AL_INTEGRATION_SITE', true ); $sPageAlbulle = require_once( JB_AL_ROOT.'core/explore.php' ); // Le code qui suit montre simplement l'existence des deux variables à utiliser au bon endroit pour votre site echo $sThmCssMetas; echo $sPageAlbulle ;
- Voir le point “Appel du script” pour l'explication des deux variables.
- Je vous renvoie au point “Démarrer une session” pour le reste !
L'intégration et les URL
Il y a généralement deux écoles dans la construction des sites Internet dynamiques :
- Ceux qui préfèrent centraliser les accès aux différentes pages de leur site par l'intermédiaire d'un script unique dont l'appel possède un paramètre qui indique la page à charger : index.php?page=toto,
- Ceux qui au contraire, crééent un script par page : index.php, toto.php, ….
Si vous êtes dans le deuxième cas, et que vous n'utilisez pas de paramètres dans vos URL, vous n'êtes pas concerné par ce chapitre. En revanche, si vous utilisez un paramètre pour arriver à votre galerie, restez ici et lisez attentivement ce qui suit. Cela vous évitera très certainement de longues heures d'incompréhension .
Vous êtes encore là ? Bien, vous utilisez donc des paramètres pour aiguiller la navigation dans votre site. Il faut donc dire à Albulle qu'il doit générer ses propres URL en conservant vos paramètres pour la continuité du fonctionnement de votre site. C'est le rôle du paramètre JB_AL_CONSERVER_URL_HOTE.
Vous devez mettre ce paramètre à true pour activer la conservation des paramètres de l'URL appelante. Pour ce faire, selon la méthode que vous avez choisie, modifiez le paramètre dans le fichier de configuration par défaut ou ajoutez une définition dans le code de surcharge (veuillez à placez cette ligne avant l'inclusion faite par require_once()) :
define('JB_AL_CONSERVER_URL_HOTE', true);
Tout le monde suit ? Ok, continuons !
Pour que votre site et Albulle puissent fonctionner de concert et sans encombre, vous allez devoir faire attention à une chose : vos paramètres. Explications :
- Premièrement, Albulle utilise ses propres variables pour fonctionner,
- Et deuxièmement, si une variable se trouve écrite deux fois dans la même URL, seule la première occurence qui apparaît est prise en compte.
De ce fait, si vous utilisez un paramètre qui est utilisé par Albulle, ce dernier ne fonctionnera pas correctement. Albulle efface systématiquement certaines variables pour s'assurer que ce sont ses propres variables qui seront prises en compte. Vous ne devez donc pas utiliser un paramètre qui est déjà utilisé par Albulle.
La liste suivante énumère les paramètres qui vous sont interdits :
rep, page, act, img, diapo, voir, diaporama
Conclusion : si vous utilisez un des paramètres cités, vous devez changer pour choisir un autre nom de variable qui ne soit pas dans cette liste.
Conseils d'intégration
Pour que l'intégration se fasse au mieux, il est préférable que le terrain d'accueil soit propice à recevoir Albulle. En d'autres termes, votre code devrait suivre une certaine organisation pour garantir le bon fonctionnement de votre site.
Préambule
Là encore, plusieurs écoles existent. Selon les besoins, un site peut être structuré de différentes façons :
- La basique : chaque script est en fait une page de code HTML dans lequel on imbrique du code PHP. C'est souvent par cette méthode que l'on apprend à faire des pages dynamiques. C'est une façon de faire qui va permettre de rendre une page dynamique très rapidement mais qui atteind vite ses limites dès lors que le projet prend de l'ampleur.
- L'intermédiaire : la basique n'étant satisfaisante que sur des petits script, il devient très vite nécessaire de faire une séparation entre le code PHP et la présentation HTML des données. Tout le coeur d'un script est codé avant de générer la page HTML, le code PHP imbriqué étant réduit à l'affichage de variables et de boucles pour les données répétitives. Rootulle est un exemple type de cette façon de faire.
- L'avancée : le code PHP et le code HTML sont complètement séparés. Il devient hors de question de mettre du code PHP dans le code HTML. On utilise alors un moteur de gabarits qui va se charger de générer le code HTML avec les données que la couche PHP lui fournira. Albulle fonctionne selon ce principe.
Pour celles et ceux qui développent déjà selon le niveau intermédiaire et/ou avancée, je pense que vous n'avez peut-être pas besoin de poursuivre cette lecture ; une intégration ne devrait pas vous poser de problème ! Pour les autres, la suite devrait vous intéresser…
Organisation
Pour une intégration sans douleur, il vaut mieux que la structure de votre site corresponde au moins au niveau intérmédiaire que je viens de décrire pour la simple et bonne raison que le code d'appel d'Albulle en mode intégré vous renvoie deux variables : une pour les métas, une autre pour le cadre qui contient la galerie (<div id=“albulle”>…</div>). Il est donc plus judicieux de placer cet appel avant que vous n'affichiez vos métas pour pouvoir y intégrer celles d'Albulle.
Prenons un exemple pour que tout cela soit bien clair :
<?php session_start(); ... votre code PHP ... // Code d'appel d'Albulle (ce code peut varier selon la méthode d'intégration choisie ; cf. plus haut) define( 'JB_AL_ROOT', 'chemin/vers/dossier/albulle/' ); $sPageAlbulle = require_once( JB_AL_ROOT.'core/explore.php' ); ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="fr" lang="fr"> <head> ... vos méta-données ... <?php echo $sThmCssMetas; ?> </head> <body> ... votre code HTML ... <?php echo $sPageAlbulle; ?> ... votre code HTML ... </body> </html>
Voilà ! A vous de travailler maintenant .