CommissionInternet:PuzzleFramework

Fichier Description Alignement

======Documentation du Framework Puzzle======

=====TÃ©lÃ©chargement=====

Pour tÃ©lÃ©charger Puzzle, [[http://ppa.ecole-et-nature.org/wiki-internet/puzzle.zip cliquez ici]].

=====Principes de Base=====

Puzzle utilise le Design Pattern MVC (Model-View-Controller).
Ce design pattern consiste Ã  faire passer les requÃªtes vers le Controlleur AssociÃ©, qui se chargera Ã  son tour de mettre en forme la Vue pour la rÃ©ponse.
Si le Controlleur doit accÃ©der Ã  une base de donnÃ©e, il se sert alors du ModÃ¨le.

Cette structure permet d'Ã©tablir une architecture organisÃ©e et simple Ã  modifier.
En effet, si jamais des changements devraient avoir lieu sur la base de donnÃ©e, il suffirait alors d'adapter uniquement le ModÃ¨le. Le Controlleur se servant de ce dernier, et celui-ci Ã©tant Ã  jour, il serait donc capable de restituer la Vue en bonne et dÃ»e forme.

Par ailleurs, Puzzle tiens son nom car il Ã  Ã©tÃ© dÃ©veloppÃ© pour que le dÃ©veloppeur puisse uniquement charger ce dont il Ã  besoin.
(ceci sera dÃ©veloppÃ© par la suite de cette documentation - cf. Classes).

=====RequÃªtes=====

Les requÃªtes sont toujours interprÃ©tÃ©es de la maniÃ¨re suivante:

>  http://www.monsite.com/[controlleur]/[variable]/[action]/

Par exemple:

> http://www.monsite.com/blog/mon-titre-darticle/

=====Organisation=====

L'organisation est la suivante:

- / (dossier racine)
        - /cache/ (dossier des fichiers temporaires)
        - /config/ (dossier des fichiers de configuration) 
        - /controllers/ (dossier ou se trouvent les Controlleurs)
        - /i18n/ (dossier des fichiers de traduction)
        - /log/ (dossier des fichiers log - pas encore dÃ©veloppÃ©)
        - /models/ (dossier des modÃ¨les)
        - /puzzle/ (dossier des fichiers "core" du Framework)
        - /site/ (dossier ou rÃ©sident les fichiers joints au site (images, javascripts, css ...)
        - /views/ (dossier des Vues)
        - .htaccess (fichier se chargeant de la redirection des requÃªtes vers index.php)
        - index.php (fichier "Bootstrap" - permettant le dispatch vers les Controlleurs)

En cas de non-support du mod_rewrite, les requÃªtes peuvent passer par le fichier index.php, par exemple: http://www.monsite.com/index.php/controlleur/variable/action/

Si vous souhaitez placer des Controlleurs "invisibles" (c'est Ã  dire pas accessible par une requÃªte web) vous pouvez les nommer _moncontrolleur.php.
Ceci est identique pour les fonctions (dites 'actions') des Controlleurs.

L'action par dÃ©faut d'un Controlleur est 'index'.
Ceci est configurable dans le fichier puzzle/defines.inc

A chaque Controlleur, une Vue. Le modÃ¨le n'est pas nÃ©cessaire mais sera chargÃ© automatiquement si prÃ©sent.
Tous doivent porter le mÃªme nom.
- Un controlleur est une Classe qui hÃ©rite de pzController (Class MonControlleur extends pzController)
- Un modÃ¨le est une Classe qui n'a pas de parent.

=====Les Classes=====

Note: Certaines classes peuvent nÃ©cessiter des paramÃ¨tres de configuration, ceux-ci Ã©tant dÃ©taillÃ©s dans le fichier //config.inc.php//

Lorsque vous souhaitez utiliser une classe du Framework dans vos Controlleurs, vous pouvez l'appeler de cette maniÃ¨re.
> //pzEngine::getClass('nom_de_classe');//

par exemple, pour utiliser la classe qui se charge d'accÃ©der Ã  la base de donnÃ©e:
> //$db = pzEngine::getClass('database');//
> //$db->query("SELECT * FROM exemple");//

Note: le nom de la classe ne prend pas le prefixe "pz".

====Les Classes "Core"====

GÃ©nÃ©ralement, ces classes sont utilisÃ©s par Puzzle lui-mÃªme. Vous n'aurez sans doute pas besoin de les charger manuellement.
Afin d'obtenir de plus amples informations sur les Classes et pour maitriser leurs fonctionnements, rÃ©fÃ©rez-vous au code de celles-ci.
Celles-ci sont:

//      - pzEngine
       - pzView
       - pzGeoip
       - pzi18n
       - pzController
       - pzLog//

Vous pouvez cependant appeler un Controlleur secondaire depuis une vue (par exemple pour charger le menu) en utilisant:
//pzEngine::getController('nom_controller', 'nom_action', 'variable', PZ_CONTROLLER_LOAD_VIEW); //

Si vous remplacez PZ_CONTROLLER_LOAD_VIEW par PZ_CONTROLLER_LOAD_SILENT, le controlleur se chargera sans retourner d'output. 
Ceci est utile si vous souhaitez utiliser des fonctionnalitÃ©s spÃ©cifiques Ã  un controlleur, sans pour autant vouloir le charger visuellement.

==pzi18n==

La classe pzi18n vous permet d'ajouter des balises {i18n:MA_VARIABLE} dans vos Vues, chose qui aura pour effet de remplacer la balise par MA_VARIABLE Ã©quivalente dans la langue de l'utilisateur (pas d'auto-dÃ©tection pour le moment).

==pzGeoip==

Cette classe permet de GÃ©o-localiser vos visiteurs selon leur adresses ip.
Elle nÃ©cessite une table MySQL mise Ã  jour par un script placÃ© dans puzzle/cron/. 
Il est conseillÃ© de mettre Ã  jour la table deux fois par mois pour des rÃ©sultats corrects.

====Les Classes "Framework"====

Celles-ci sont utilisable et chargables par //getClass()//.

//      - pzSession
       - pzDatabase
       - pzUser*
       - pzUsergroup*
       - pzBrowserinfo//

==pzDatabase==

Cette classe fournit une API simple et efficace pour MySQL.
Elle gÃ¨re les connexions, les requÃªtes et quelques erreurs.

==pzBrowserinfo==

Cette classe retourne des informations dÃ©taillÃ©es sur le navigateur de vos visiteurs. 
Utile pour faire des statistiques.

==pzSession==

Cette classe est la plus aboutie du Framework. 
Elle s'occupe des sessions utilisateurs, sans utiliser session_start(). 
Vous pouvez la configurer en auto-load (voir fichier de configuration) pour gÃ©rer automatiquement les sessions.

=====Sites utilisant Puzzle=====

Des Nichoirs Dans La Plaine : http://www.desnichoirsdanslaplaine.fr/

=====Auteur=====

Puzzle Ã  Ã©tÃ© dÃ©veloppÃ© par Julien Ballestracci au cours de sa mission au RÃ©seau Ecole & Nature.
Vous pouvez me contacter par mail: julien [at] nitronet [point] org