Le framework Gantry est livré avec un système AJAX intégré qui agit comme une passerelle entre le client et le framework Gantry.
Chaque appel Ajax est dirigé vers un "modèle Ajax" qui reçoit des paramètres Ajax et après ses opérations est capable de retourner une réponse avec ce que la demande d'appel d'origine Ajax attend. Ci-dessous vous pouvez voir un résumé schématique du processus.
La puissance réelle du système ajax intégré dans le framework gantry réside dans les modèles. Chaque développeur peut créer ses propres modèles personnalisés Ajax et utiliser les appels Ajax côté client afin de récupérer des types de données spécifiques.
There are 2 Ajax systems in the Gantry framework that actually work exactly the same with one exception: restrictions. In fact the first can be used for everything regarding the template while the second can only be used admin side. The restriction makes it so that even by error you cannot use the admin Ajax System on the frontend.
Il y a 2 systèmes Ajax dans le framework Gantry qui fonctionnent exactement pareil à une exception près : les restrictions. En fait le premier peut être utilisé pour tout ce qui concerne le template tandis que le second ne peut être utilisé que côté admin. La restriction fait en sorte que même par erreur, vous ne pouvez pas utiliser l'admin système Ajax sur le frontend.
l'URL Ajax
Pour commencer avec un appel Ajax côté client, vous devez appeler l'URL correcte afin de déclencher le mécanisme du modèle Ajax de gantry.
L'URL est le même pour le Frontend et Backend avec, bien sûr, l'ajout du chemin /administrator/ lorsque nous traitons dans le Backend et il ressemble à /index.php?option=com_gantry&task=ajax&format=raw&template=[nom_de_votre_template]
Si nous décomposons la requète, vous remarquerez que cela ressemble à un appel de composant Joomla!, et c'est effectivement ce que c'est :
- option → com_gantry
- task → ajax
- format → raw
- template → [
nom_de_votre_template
]
Tous ces morceaux sont fondamentaux pour que le mécanisme Ajax de Gantry puisse travailler.
nom_de_votre_template fait réference au nom du template frontend que vous utilisez actuellement. Par exemple si nous étions en train d'utiliser le template par défaut Gantry, ce serait template=gantry
Gantry est livré avec une méthode qui rend plus facile la construction et le rendu de l'URL Ajax. En PHP, vous pouvez exécuter $gantry->getAjaxUrl()
et la même chaîne d'URL que ci-dessus sera retournée.
Ceci est particulièrement utile si vous souhaitez copier l'URL dans une variable globale de JavaScript que vous pourrez ensuite référencer dans votre propre script.
Par exemple, dans le index.php de votre template, vous pourriez produire une déclaration de script inline similaire à :
<?php // location: /templates/gantry/index.php ... $gantry->addInlineScript("var GantryAjaxURL = '".$gantry->getAjaxUrl()."';"); // GantryAjaxURL => '/index.php?option=com_gantry&task=ajax&format=raw&template=gantry'
De cette façon, vous pouvez accéder à la variable GantryAjaxURL à partir de vos propres scripts.
Les modèles Ajax
Les modèles sont des fonctions Ajax PHP efficace où participe toute la logique d'un modèle spécifique.
Un modèle peut avoir n'importe quel genre de but. Par exemple, dans l'Admin du portique, nous utilisons des modèles Ajax pour
- Vider le cache
- Supprimmer des fichiers compilés LESS
- Sauvegarde Ajax
- Créer des presets
- ...
Comme vous pouvez le voir, un modèle peut être quelque chose que vous pouvez penser et dont le mécanisme fonctionne dans les coulisses, en fait un moyen très puissant pour contrôler quoi que ce soit via Ajax si vous le souhaitez.
Les modèles Ajax sont situés dans le dossier Library de Gantry sous [votre_site]/library/gantry/. Les modèles frontend sont à la racine ajax-models/
tandis que les modèles de backend sont dans le dossier admin admin/ajax-models/
En raison de la capacité du Framework gantry d'overrider, vous n'aurez jamais besoin de jamais aller éditer les modèles contenus dans les endroits mentionnés ci-dessus. En fait, il vous suffit de travailler au niveau du dossier template, en gardant la même structure.
Ainsi, vos modèles personnalisés de tempalte Ajax doivent être stockés dans le dossier [votre_site]/templates/[votre_template]/ajax-models/ tandis que vos modèles personnalisés administrateur Ajax doivent être stockés dans le dossier [votre_site]/templates/[votre_template]/admin/ajax-models/.
Ci-dessous un exemple de modèle qui retournera toutes les requêtes POST en retour à l'Ajax :
<?php // location: /templates/gantry/ajax-models/example.php defined('JPATH_BASE') or die(); global $gantry; print_r(JRequest::get('post')); ?>
Il est important de noter que le nom de fichier du modèle Ajax est ce qui identifie le modèle lui-même.Le nom, dans ce cas, example est ce que nous allons utiliser dans l'appel Ajax côté client, pour récupérer les données dont nous avons besoin pour ce modèle particulier.
La syntaxe d'appel Ajax
Maintenant que nous avons un modèle, nous sommes prêts à créer l'appel JavaScript Ajax. Gantry est basé sur MooTools 1.4, donc les exemples suivants sont écrits dans la syntaxe de MooTools. Cela ne signifie pas que vous ne pouvez pas utiliser JavaScript natif ou tout autre framework pour effectuer la même opération.
Supposons que notre index.php du template charge un fichier js nommé ajax-call.js, fournissant ainsi une variable GantryAjaxURL comme décrit dans la section L'URL Ajax.
<?php // location: /templates/gantry/index.php ... $gantry->addInlineScript("var GantryAjaxURL = '".$gantry->getAjaxUrl()."';"); $gantry->addScript('ajax-call.js'); // /templates/gantry/js/ajax-call.js ...
Le template est maintenant configuré pour charger votre script personnalisé d'appel ajax, nous pouurons également nous appuyer sur lavariable JavaScript GantryAjaxURL qui contient l'url ajax en tant que chaîne.
Maintenant la partie amusante, le JavaScript :
((function(){ window.addEvent('domready', function(){ // Request Object var request = new Request({ url: GantryAjaxURL, // <r;- remember, this is the ajax url, explained in The Ajax URL section. onSuccess: function(response){ console.log(response); } }); // Request post request.post({ model: 'example', // <r;- the model must always be passed in animal: 'Cat', name: 'Pixel' }); }); })());
C'est très simple. Comme vous pouvez le voir, nous créons un objet de requête que nous utilisons ensuite pour demander un POST. Il est obligatoire que le modèle (model: 'example'
) soit toujours présent lors d'une requète, c'est ce qui identifie quel modèle le système Ajax Gantry doit charger et exécuter.
Voila ce qui est produit par l'exemple ci-dessus
Array ( [model] => example [animal] => Cat [name] => Pixel )
Le modèle que nous avons utilisée est un exemple très basique et simple, mais c'est un bon point de départ. Vous pouvez voir des modèles beaucoup plus sophistiqués si vous explorez le référentiel de bibliothèque de Gantry.