v1.1
##############   MODULE MG3 pour KwsPHP   ##############
Auteur: 	Choubs <choubs at free.fr>
pour KwsPHP
Date:		08/09/2006
Révision:	14/10/2006

INDEX:
	-> RESUME
	-> DESCRIPTION
	-> FONCTIONNALITES
	-> INSTALLATION
	-> PRISE EN MAIN "BASIQUE" ( solution FTP )
	-> PRECISIONS PRATIQUES
	-> CAS PARTICULIER 01 : AUTOMATISER LE COMMENTAIRE D'UN ALBUM
	-> CAS PARTICULIER 02 : AUTOMATISER LES PARAMETRES D'UN ALBUM
	-> CAS PARTICULIER 03 : AUTOMATISER LA DESCRIPTION DES IMAGES
	-> CAS PARTICULIER 04 : TYPES DE SYNCHRONISATION
	-> CAS PARTICULIER 05 : UPLOAD
	-> CAS PARTICULIER 06 : COMMENTAIRES
	-> CAS PARTICULIER 10 : IMAGES GRAND FORMAT
	-> CAS PARTICULIER 11 : IMAGES DETAILLEES
	-> CAS PARTICULIER 12 : SITES DISTANTS
	-> CAS PARTICULIER 13 : GESTION DES PERMISSIONS

-----[ RESUME
Ce module vous permet de gérer une galerie de photos.
Il permet également d'afficher un bloc contenant une - ou plusieurs - photo aléatoire.


-----[ DESCRIPTION
La galerie "mg3" est destinée à permettre de publier rapidement dans le portail une grande quantité de photos, tout en gérant les permissions d'accès des utilisateurs. L'usage commun est de déposer par FTP* les répertoires et images de votre galerie, puis de procéder à une "synchronisation**" dans mg3. Les photos et albums deviennent alors visibles pour vos utilisateurs. Il vous est ensuite possible de définir précisément les permissions d'accès aux albums.

* FTP pour "File Transfer Protocol". Par extension, ce terme désigne les logiciels vous permettant de transférer des fichiers de votre ordinateur à un serveur distant ( votre hébergeur de site, par exemple ).

** synchronisation : opération du module "mg3" qui consiste à synchroniser la table SQL de mg3 avec les photos déposées sur le serveur qui héberge votre site.


-----[ FONCTIONNALITES
- gère les images jpg, png et gif
- exploration automatisée des répertoires du serveur
- utilisation des informations IPTC des photos
- affichage des images 
	. par galeries, 
	. par dates, 
	. par résultat de recherche, 
	. par photos récemment déposées
- recherche rapide par clic direct sur dates, lieux et mots clé
- multi-sites
- multilingue si vous le souhaitez
- upload d'images
- intégration d'une gestion d'images détaillées (cf. infra )


-----[ INSTALLATION
1/ Télécharger le module zippé de mg3 sur le site de KwsPHP

2/ Dé-zipper le fichier

3/ Transférer le nouveau répertoire "mg3" - et ses fichiers ;) - dans le répertoire "modules" de votre site
ATTENTION: les sous-répertoires "mg3/albums", "mg3/upload", "mg3/upload/thumbnail" doivent avoir des droits en "écriture".

4/ Procéder à la création des tables SQL
	-> exécuter le fichier d'instructions "modules/mg3/installation/mg3_sql(x).sql" - (x) dépendant de la version de SQL autorisée par votre hébergeur - en utilisant PhpMyAdmin OU le module "SQL" de votre interface d'administration KwsPHP

5/ Le module est alors disponible sur votre site.
	Il ne vous reste plus qu'à créer le lien ad-hoc dans votre menu, et à ajouter si vous le souhaitez le bloc de "mg3" dans votre portail ( cf. doc de KwsPHP )

	
-----[ PRISE EN MAIN "BASIQUE" ( solution FTP )
1/ Préparation du travail, sur votre ordinateur:
	créer un dossier "test", et son sous-dossier "thumbnail"
	déposer une ou plusieurs images ( jpg,jpeg, gif ou png ) dedans
	vous pouvez utiliser le freeware "phpmyvignettes" ( Google est votre ami... ) pour facilement générer ces vignettes.

2/ Transfert sur votre site
	avec un logiciel de FTP ( Google est toujours votre ami... ), transférer le dossier "test" et son contenu dans le dossier "modules/mg3/albums"

3/ Synchronisation
	Aller dans la partie "Gestion des modules" de KwsPHP.
	Sélectionner le bouton "mg3"
	Utiliser l'option "Gestion des sites"
	-> dans la partie "Site local", cliquer sur le lien [XML] pour générer le fichier xml
	-> une fois que le fichier XML est généré, retourner sur la page de gestion des sites et cliquer sur le lien [Synchroniser]
	Vos photos devraient alors être disponibles...


-----[ PRECISIONS PRATIQUES
- la première étape du process génère un fichier .xml contenant les informations nécessaires à la synchronisation. Chaque sous-dossier devient un "album" de la galerie, contenant les images qui sont présentes dans le répertoire concerné. Lors de la création de ce fichier, le script tentera également de créer les répertoires et/ou les vignettes manquantes.

- évitez d'utiliser des caractères spéciaux ( espaces, caractères accentués etc.. ) dans le nom des dossiers et des images. Remplacez les espaces par le signe "_", il sera automatique converti en espace lors de la synchronisation.


-----[ CAS PARTICULIER 01 : AUTOMATISER LE COMMENTAIRE D'UN ALBUM
Principe:
	Le script de synchronisation va détecter la présence d'un fichier texte dans le répertoire et injecter son contenu en tant que commentaire de l'album correspondant.
	
Procédure:
	Déposer dans le répertoire concerné un fichier "commentaire.txt". Synchroniser.

Utilité:
	Ne pas avoir à re-saisir ces informations en cas de ré-installation

	
-----[ CAS PARTICULIER 02 : AUTOMATISER LES PARAMETRES D'UN ALBUM
Principe:
	Le script de synchronisation va détecter la présence d'un fichier texte dans le répertoire et injecter son contenu en tant que paramètres de l'album correspondant.
	
Procédure:
	Déposer dans le répertoire concerné un fichier "alb_params.txt". Synchroniser.

Utilité:
	Ne pas avoir à re-saisir ces informations en cas de ré-installation
	
Notes:	
	Mettre une seule instruction par ligne dans ce fichier.

NOBLOC	
	=> 	les images de cet album ne seront pas affichées dans le bloc de mg3

RANDOM
	=> 	une image serait tirée au hasard pour représenter l'album lors de la navigation dans mg3

TITRE=le_titre_choisi
	=> 	"le_titre_choisi" devient le titre de l'album, qui peut être différent du nom de répertoire.

THUMB=chemin_vers_la_miniature
	=> 	"chemin_vers_la_miniature" définit le chemin vers la miniature qui représente l'album.
		Attention: l'indicateur "RANDOM" est prioritaire sur cette instruction.

PRIVATE
	=>	l'album est défini comme "privé"

GROUPE=groupe1,groupe2
	=>	liste des intitulés de groupes autorisés à accéder à l'album, séparés par une virgule

USER=user1,user2
	=>	liste des pseudos autorisés à accéder à l'album, séparés par une virgule	

OWNG=groupe1,groupe2
	=>	liste des intitulés de groupes autorisés à gérer l'album, séparés par une virgule


-----[ CAS PARTICULIER 03 : AUTOMATISER LA DESCRIPTION DES IMAGES
Principe:
	Le script de synchronisation va lire les informations IPTC présentes dans l'image et les injecter en tant que description de l'image correspondante.
	
Procédure:
	Au préalable, utiliser un logiciel ad-hoc pour garnir les informations IPTC de l'image. Synchroniser.

Utilité:
	Ne pas avoir à re-saisir ces informations en cas de ré-installation

Détail technique:
	Les données sont récupérées dans le script "mg3/xml_generate.php"
		Titre 		<- $iptc['2#005']
		Mots-clés 	<- $iptc['2#025']
		Date 		<- $iptc['2#055']
		Ville 		<- $iptc['2#090']
		Région 		<- $iptc['2#095']
		Pays 		<- $iptc['2#101']
		Commentaire <- $iptc['2#120']
		Auteur		<- $iptc['2#122']


-----[ CAS PARTICULIER 04 : TYPES DE SYNCHRONISATION
La synchronisation se passe toujours en 2 temps :

- création d'un fichier xml contenant l'ensemble des informations "automatisées du site" :
	informations IPTC pour les images, paramètres des albums

- synchronisation de la base SQL avec le fichier xml

4 modes de synchronisation sont possibles, paramétrables dans l'écran de gestion des sites:
	1 maj des nouveaux albums et images uniquement ( conserve l'existant )

	2 maj des nouveaux albums et images, 
		+ remplacement des descriptions des albums ( sf le tri ) existants

	3 maj des nouveaux albums et images, 
		+ remplacement des descriptions des images existantes

	4 synchro complète ( par défaut ) = 2+3
		le fichier xml écrase les informations de la base...


-----[ CAS PARTICULIER 05 : UPLOAD
Il est possible d'autoriser les utilisateurs à déposer des images sur le serveur.
Il est possible de paramétrer que l'upload se fasse dans le répertoire "réel" de l'album concerné, pour peu que celui-ci existe sur le site local.
Dans ce cas, veiller à avoir des droits en "écriture" sur ce répertoire.
Après l'upload, mg3 crée une miniature de l'image.
Remarque:
	- le poids maximum autorisé par transfert est fixée par votre hébergeur ( en général, 8Mo ).
	- la mémoire utilisable est par le processus de création de la miniature est également fixé par votre hébergeur ( idem, 8Mo )
	Attention: le format jpg est un format compressé. La mémoire utilisée par le processus de création de la vignette est égale à la taille "décompressée" du fichier ( exemple: fichier.jpg = 200Ko => 6Mo en mémoire! ), que vous pouvez contrôler dans la plupart des visionneuses d'images ( dont "Irfanview" )


-----[ CAS PARTICULIER 06 : COMMENTAIRES
les utilisateurs ont la possibilité de déposer un commentaire sur les albums et photos.
Un fois que le commentaire est déposé, le propriétaire de l'album recoit un message d'information.
Ce procédé permet au propriétaire de l'album ou de l'image de réagir "dans la foulée"...


-----[ CAS PARTICULIER 10 : IMAGES GRAND FORMAT
Objectif:
	permettre de gérer un 3e format d'affichage pour une ou plusieurs photos ( miniature, standard, grand format )

Principe:
	"mg3" va détecter la présence d'une image du même nom dans le sous-répertoire "maxidir". Un lien apparait alors au dessus de l'image.

Utilité:
	Pour afficher une image de votre site, le visiteur la transfère implicitement sur son disque dur. Plus la taille de l'image est grande, plus votre visiteur mettra de temps à l'afficher. C'est pourquoi il est souhaitable de mettre à disposition des images de taille moyenne ( moins de 150ko ) afin de rendre la navigation plus fluide ( ce sont les images "standard" de mg3 ). MG3 offre ici la possibilité de faire apparaitre un lien vers l'image en grand format...

Procédure:
	1/ créer un sous-répertoire "maxidir"
	2/ y déposer la ou les images en grand format, portant le même nom que l'image standard


-----[ CAS PARTICULIER 11 : IMAGES DETAILLEES
Objectif:
	Prenons l'exemple d'une photo de classe. L'idée est que l'on puisse afficher le nom des personnes en survolant leur visage, et que l'on puisse déclencher dans la foulée une recherche dans la base photo pour la personne concernée.

Principe:
	"mg3" va détecter la présence dans le répertoire d'un fichier .xml du même nom que l'image. Un lien apparait alors au dessus de l'image.

Procédure:
	pour une image "toto.jpg", générer un fichier standardisé "toto.xml" que vous déposerez dans le répertoire de l'image. Un outil de saisie vous est proposé dans le dossier "mg3/utile".


-----[ CAS PARTICULIER 12 : SITES DISTANTS
Objectif:
	Permettre de dépasser l'espace alloué par votre hébergeur, en combinant plusieurs espaces d'hébergement.

Principe:
	On génère sur le serveur distant un fichier ".xml" qui permettra de faire une synchronisation sur le site principal.

Procédure:
	1/ 	saisir les données concernant le site distant dans la partie administration de mg3 "Gestion des sites"
	2/ 	adapter le fichier "mg3/installation/xml_generate_dst.php", en fonction de vos besoins
	3/ 	déposer le fichier "mg3/installation/xml_generate_dst.php" à la racine de la galerie du site distant
	4/ 	ensuite, procéder à génération du fichier xml, puis à la synchronisation, par la procédure habituelle de mg3

Remarque:
	Je n'ai pas trop creusé cette piste, car l'affichage des images distantes peut être ralenti par les temps d'accès aux serveurs distants concernés... On pourra revoir si ca intéresse des utilisateurs.


-----[ CAS PARTICULIER 13 : GESTION DES PERMISSIONS
Principe:
	MG3 est prévu pour gérer tout un lot de permissions

Cas 1 : Accès à la galerie
	L'accès à la galerie ( et au bloc ) est défini par un grade minimum dans la partie "paramètres" de mg3.

Cas 2 : Administration de galerie
	L'accès à la partie administration de la galerie est défini par un grade minimum dans la partie "paramètres" de mg3.. L'administration se fait via le menu habituel de Kws.

Cas 3 : Gestion des albums
	La gestion des albums peut - en plus de l'admin de la galerie et du propriétaire de l'album - être déléguée aux membres des groupes autorisés. Modifier la zone de saisie "Groupes de gestion" dans le formulaire de gestion de l'album considéré.

Cas 4 : Accès et permissions sur albums
	On peut donner l'accès à un album 
		- à un ou plusieurs groupes donnés, 
		- à un ou plusieurs users donnés
	Une personne non autorisée ne voit pas l'album apparaître

Cas 5 : Affichage ou non dans le bloc de mg3
	Il est possible de définir que le contenu d'un album ne doit pas apparaitre dans le bloc de photos aléatoires. Le module est construit de facon à ce que ce contenu n'apparaisse pas non plus dans les approches par date et dans le résultat des recherches.