====== 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.
Cet article s'adresse plutôt aux personnes qui ont un bagage minimum en PHP et XHTML/CSS.
Avant d'éditer index.php, je vous invite à lire l'[[:accueil|avertissement]] présent à l'accueil de la documentation si ce n'est pas déjà fait !
===== Préambule =====
Je pars du principe que vous êtes déjà passé par la documentation de l'[[installation_autonome|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 :
* [[integration_dans_un_site#methode_i_la_classique|Méthode I]] : paramétrer Albulle depuis son **fichier de configuration principal**,
* [[integration_dans_un_site#methode_ii_la_surcharge|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 !
Je vous invite fortement à consulter le fichier **index_exemples.php** du dossier **extras/** présent dans l'archive que vous avez téléchargée. Il contient des informations complémentaires qui pourront vous intéresser. Ca fait un peu de lecture supplémentaire, mais c'est pour parfaire votre maîtrise d'Albulle.
Personnellement je préfère l'utilisation de la 2ème méthode (la surcharge), c'est plus simple et plus souple à mon sens. Cela dit, je mets les explications pour la méthode I à des fins pédagogiques pour que vous appréhendiez au mieux la structure d'Albulle.
===== 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 ...).
* **$sPageAlbulle** est la variable qui contient le code XHTML de la page d'Albulle en mode intégré, soit le cadre principal **...
**.
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 [[http://fr.php.net/manual/fr/function.session-start.php|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 : [[personnalisation|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 "[[integration_dans_un_site#appel_du_script|Appel du script]]" pour l'explication des deux variables.
- Je vous renvoie au point "[[integration_dans_un_site#demarrer_une_session|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 (...
). 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 :
... vos méta-données ...
... votre code HTML ...
... votre code HTML ...
Voilà ! A vous de travailler maintenant :-).