Ce tutoriel a été écrit pour expliquer la conception du crochet pour IP.Board 3.2 User Online Status in Topics.
Il est conseillé d'utiliser un forum de développement relativement propre, voir dédié pour la création de votre crochet.
Ce forum dispose du IN_DEV activé, mais uniquement côté administration. Faire cela en éditant le fichier /admin/index.php et en ajoutant la ligne suivante vers le haut :
define('IN_DEV', 1);
L'avantage ici est d'avoir tous les atouts de développement du mode IN_DEV dans le PC Admin, mais sans avoir à se soucier du thème maître. Vous verrez plus tard comment traiter les thèmes sans tripatouiller les fichiers du thème maître.
La première chose à faire est d'identifier où accrocher votre crochet. Dans IP.Board 3.0 et 3.1, l'affichage d'un sujet se trouvait entièrement dans le modèle topicViewTemplate, avec ce qui entourait l'avatar dans son propre modèle userInfoPane. Le nom d'utilisateur à côté duquel l'indicateur du statut connecté se situe n'est pas dans la zone userInfoPane. Il faut donc chercher où le nom se trouve dans topicViewTemplate. On peut être un peu confus de ne pas trouver où le nom se trouve. Après avoir quelque peu farfouiller dans le modèle afin de le localiser, on finit par trouver qu'il est maintenant dans les messages individuels qui disposent de leur propre modèle : post.
En regardant dans le modèle post, vous trouvez la zone suivante où le nom d'utilisateur est affiché :
<if test="postMember:|:$post['author']['member_id']">
<span class="author vcard">{parse template="userHoverCard" group="global" params="$post['author']"}</span>
<else />
{$post['author']['members_display_name']}
</if>
C'est parfait, car il y a un élément if qui est un des éléments dont vous avez besoin pour réaliser un crochet dans modèle (ceci ou un élément foreach). Ce sera donc l'endroit où l'indicateur connecté ira. Dans un soucis de cohérence, je consulte un forum de test en 3.1 pour voir exactement où l'indicateur connecté était situé. Il était juste après la balise d'ouverture <if> dans ce code :
<if test="postMember:|:$post['author']['member_id']">
<if test="postOnline:|:$post['author']['_online']">
{parse replacement="user_online"}
<else />
{parse replacement="user_offline"}
</if>
<span class="author vcard"><a class="url fn" href='{parse url="showuser={$post['author']['member_id']}" base="public" template="showuser" seotitle="{$post['author']['members_seo_name']}"}'>{$post['author']['members_display_name']}</a>{parse template="user_popup" group="global" params="$post['author']['member_id'], $post['author']['members_seo_name']"}</span>
<else />
{$post['author']['members_display_name']}
</if>
Nous avons donc identifié où accrocher le crochet et quel sera le code de base du crochet, afin de dupliquer cette fonctionnalité de la version 3.1.
La prochaine étape est le début de la création du crochet sur la page Gérer les crochets. Une fois sur ladite page, cliquez sur le bouton Créer un crochet et commencez à travailler sur les différentes pages à partir d'ici. Voici la première page, dont la plupart des éléments sont bien expliqués :
Quelques éléments à garder à l'esprit. Donner à ses applications/crochets une clé unique à utiliser durant tout le processus. La seule chose qui pourrait perturber certaines personnes est l'URL de mise à jour, que peu d'auteurs utilisent alors qu'elle permet de garder les utilisateurs du crochet au courant de la disponibilité d'une mise à jour.
L'onglet suivant permet de fixer les pré-requis du crochet. Comme il s'agit d'un crochet réservé à la version 3.2 d'IP.Board, les pré-requis sont sont assez basiques :
Cela indique simplement que le crochet nécessite IP.Board 3.2. Nous n'utilisons pas l'onglet Caches globaux (je ne vois même pas certain pourquoi quelqu'un devrait l'utiliser), passons donc directement à l'onglet Fichiers. C'est ici que les gens éprouvent en général des difficultés. Voici donc une capture d'écran, avec ensuite des explications détaillées.
Les deux premiers champs sont assez faciles, vous devez juste donner le nom du fichier et le nom de sa classe. En général on utilise la clé du crochet comme base pour les deux, en ajoutant l'extension .php au nom du fichier. Une fois ces champs remplis, il faut créer le fichier PHP. Mais nous allons avant ça en terminer avec cet onglet.
Il y a plusieurs types de crochet disponibles, mais celui utilisé ici est probablement le plus simple. Ce crochet cherche un élément dans le thème pour y ajouter quelque chose. Il s'agit donc d'un crochet de modèle. Lorsque vous sélectionnez ce choix, des listes déroulantes apparaissent (une par une) en dessous, vous permettant de choisir l'endroit précis où le crochet se fixera. Comme nous l'avons déterminé précédemment, le crochet sera dans le thème du sujet (skin_topic), dans le modèle "post", et dans la condition if "postMember". Comme nous voulons que le code que nous allons ajouter s'exécute juste après le début de l'instruction if, choississez (post.startif) Après le début de la condition if dans la dernière liste déroulante.
Revenons maintenant au fichier physique. Dans le dossier /hooks du forum, créez un fichier avec le nom indiqué dans le formulaire ci-dessus et y mettre ce code très basique pour un crochet de modèle :
<?php
class onlineStatusInTopics
{
protected $registry;
public function __construct()
{
/* Make registry objects */
$this->registry = ipsRegistry::instance();
}
public function getOutput()
{
/* Return */
return;
}
}
Nous connaissions déjà le nom de notre classe (indiqué dans le formulaire précédent) et la fonction __construct() est une fonction standard de PHP qui est appelée automatiquement lorsque la classe est appelée. Cette fonction doit toujours être utilisée pour configurer les objets communs de registre dont vous aurez besoin. La fonction getOutput() est appelée par IP.Board afin de déterminer ce qui doit être ajouté sur la page à l'endroit du point d'ancrage sélectionné. C'est la fonction la plus couramment utilisée, mais elle présente des inconvénients. Elle est adaptée lorsque vous avez un élément unique à ajouter une seule fois, mais nous avons ici à parcourir plusieurs messages sur la page et pour y ajouter des éléments distincts.
Heureusement, il existe une autre possibilité. Au sein d'une classe de crochet de modèle, vous pouvez aussi avoir une fonction appelée replaceOutput(). Elle nécessite deux arguments, $output et $key. $output est le code actuel utilisé pour l'affichage de la page, $key est l'identifiant unique du point d'ancrage. Comme son nom l'indique, replaceOutput est utilisée pour trouver du contenu dans la page pour le remplacer par autre chose. Voici le contenu complet de la fonction pour le crochet de démonstration. Cela peut sembler déroutant au premier abord, mais vous aurez à réutiliser quasiment l'ensemble de ce code pour des crochets de ce type :
public function replaceOutput( $output, $key )
{
/* Got some data? */
if ( is_array( $this->registry->output->getTemplate('topic')->functionData['post'] ) && count( $this->registry->output->getTemplate('topic')->functionData['post'] ) )
{
/* Init some vars */
$tag = '<!--hook.' . $key . '-->';
$last = 0;
/* Loop through each template call */
foreach ( $this->registry->output->getTemplate('topic')->functionData['post'] as $k => $v )
{
/* See if we can find this hook point */
$pos = strpos( $output, $tag, $last );
/* Found? */
if ( $pos !== FALSE )
{
/* Start swapping it out */
$string = $this->registry->output->getTemplate('topic')->hookUserOnline( $v['post']['author'] );
$output = substr_replace( $output, $string . $tag, $pos, strlen( $tag ) );
$last = $pos + strlen( $tag . $string );
}
}
}
/* Return */
return $output;
}
Regardons pas à pas ce que fait ce code et comment il fonctionne. Tout d'abord, dans un crochet de modèle, vous avez automatiquement accès au tableau functionData. Vous noterez qu'il définit à la fois le groupe de thème (topic) et le modèle (post) où nous nous ancrons. Chaque modèle de thème où vous pouvez vous ancrer met à votre disposition cet objet, vous avez juste besoin de vous assurer que vous y faites référence. Nous commençons simplement par nous assurer d'avoir cet objet et de dérouler notre code uniquement s'il existe. Ensuite nous mettons en place les variables $tag et $last pour nous aider à nous déplacer dans le code $output pour trouver ce que nous devons remplacer. Nous continuons avec une boucle sur tous nos éléments functionData (ceux contenant les éléments 'variables de données' pour chaque message. En passant, c'est pourquoi ils sont si pratiques ici), cherchant l'endroit dans $outpout où nous remplacerons des choses et effectuerons un substr_replace pour ajouter notre texte.
Je parie que beaucoup d'entre vous se gratteront la tête à ce stade, mais ne vous inquiétez pas. Comme mentionné plus haut, une grande partie de ce code est standard et il est juste nécessaire pour trouver le point d'ancrage et le texte que vous devez remplacer. La seule ligne de ce code dont vous avez besoin de vous préoccuper est la suivante :
$string = $this->registry->output->getTemplate('topic')->hookUserOnline( $v['post']['author'] );
C'est la partie magique. Nous appelons ici un modèle de thème et assignons le résultat HTML à une variable nommée $string. Nous avons besoin de créer ce modèle, ce qui sera la prochaine partie que nous allons voir. Mais revenons au point actuel. Comme vous pouvez le voir, il s'agit d'un modèle dans l'affichage d'un sujet dont le nom est hookUserOnline(). Une variable lui est passée en argument : $v['post']['author']. Il s'agit d'un tableau contenant toutes les données sur l'auteur du message. Vous pouvez vous demander, à juste titre, comment j'ai trouvé ce qu'était le contenu de cette variable. Quand je veux connaître la valeur des variables, j'utilise toujours une construction similaire en écrivant un code dans le style de celui qui suit :
print "<textarea cols='50' rows='20'>"; print_r( $variable ); print "<textarea>";
Cela affiche sur la page une zone de texte avec la valeur de la variable que je vérifie. Puisque nous sommes dans une boucle foreach de functionData, où $k est la case du tableau et $v sa valeur, j'ai vérifié quels $v étaient à ma disposition. Voici à quoi ressemble le résultat :
image 4
C'est donc juste un moyen pour trouver comment récupérer les informations sur l'auteur. $v est un tableau à plusieurs dimensions contenant beaucoup d'informations. Le premier niveau contient les informations d'un message (post), sous la forme d'un autre tableau multi-dimensionnel. Dans un message, il y a un autre tableau appelé author qui contient les données sur l'auteur du message. Encore une fois, vous pouvez utiliser la méthode print_r pour étudier ces éléments et vous aider à trouver avec précision l'endroit où se trouve les données dont vous avez besoin. Nous trouvons ainsi que $v['post']['author'] contient toutes les données sur l'auteur et que c'est l'argument que nous devons envoyer à notre modèle pour vérifier si les utilisateurs est en ligne ou non.
Nous arrivons quasiment à la fin de ce fichier PHP. Notez que même en utilisant la fonction replaceOutput(), vous devez également inclure la fonction getOutput(). IP.Board aura toujours besoin de cette dernière dans un crochet de modèle. Maintenant que le fichier PHP est construit, vous pouvez revenir dans le PCA pour enregistrer le crochet. La prochaine étape qui doit être effectuée dans ce cas est de créer le modèle de thème. Sachez qu'il est tout à fait possible de réaliser cette étape avant la création du crochet.
Allez dans l'onglet Apparence > Look & Feel > Gérer les thèmes & modèles pour y éditer le thème par défaut et y ajouter le nouveau modèle dont vous avez besoin. Vous pouvez le nommé selon votre envie. Nous avons défini plus tôt que nous appellerions celui-ci hookUserOnline et qu'il aurait comme données variables les données sur l'auteur. Nous appellerons notre donnée variable ainsi :
$author=array()
Alors dans notre modèle, nous avons un tableau nommé $author que nous passons depuis le code PHP, et qui contient toutes les données sur l'auteur. Voici le code du modèle d'une installation en 3.1 qui correspond à notre crochet :
<if test="postOnline:|:$author['_online']">
{parse replacement="user_online"}
<else />
{parse replacement="user_offline"}
</if>
Vous pouvez l'essayer en espérant que cela fonctionnera de manière magique, mais ce n'est pas le cas. IPS a cessé d'utiliser ces remplacements pour utiliser un look différent pour cet indicateur, vous avez donc besoin de modifier le code. Voici à quoi le résultat doit finalement ressembler :
<if test="postOnline:|:$author['_online']">
<span class='ipsBadge ipsBadge_green'>{$this->lang->words['online_online']}</span>
<else />
<span class='ipsBadge ipsBadge_grey'>{$this->lang->words['online_offline']}</span>
</if>
Vous pouvez alors enregistrer le modèle. Les deux chaînes de langage ne sont pas disponible dans la vue d'un sujet, il vous faut donc les ajouter. Vous pouvez faire cela via la page Gérer les langages et en les plaçant dans le pack de langue Forum > public_topic (bouton ajouter une chaîne).
Maintenant, comme vous avez suivi la recommandation de ne pas utiliser le thème maître, vous devez déplacer le modèle dans le thème maître. Ceci afin qu'il soit ajouté dans l'étape d'export du crochet. Une manière de faire est de se rendre dans phpMyAdmin, de naviguer dans la table des modèles de thème en les triant par template_id décroissant. Vous verrez qu'il y a deux entrées pour le modèle de thème que vous venez d'ajouter : un qui a le template_set_id à 0 et rien dans le champ template_content, et le second avec le template_set_id à 1 etdu contenu dans template_content. Le premier (template_set_id 0) est la copie maître du modèle. Supprimez la en cliquant sur la croix rouge. Editez alors l'autre modèle, puis mettez à 0 les champs template_set_id, template_removable, template_added_to, template_user_added et template_user_edited, et mettez root dans le champ template_master_key. Enregistrez ces modifications, vous avez maintenant le nouveau modèle que vous venez de créer dans le thème maître.
Tout ce que vous avez besoin faire maintenant c'est exporter le crochet. Retournez sur la page de gestion des crochets, cliquez sur le menu déroulant correspondant à votre crochet et choisissez Exporter le crochet. Vous devez utiliser cette interface pour choisir tout ce que vous ajoutez dans le cadre de ce crochet. Pour cet exemple, vous avez ajouté deux chaînes de langage et un modèle de thème. Cherchez les et sélectionnez les, puis cliquez sur le bouton Exporter qui se trouve en bas. Cela vous permettra de sauvegarder la totalité du crochet dans un fichier. Il est alors intéressant de l'importer sur un forum vierge afin de vérifier que vous n'avez rien oublié.
Croyez-le ou non, il aura fallu 20 minutes à Michael pour réaliser le crochet avec la méthode décrite. Il lui a par contre fallu beaucoup plus de temps pour rédiger son article et il est possible que certaines choses qu'il considère comme acquises aient été passées sous silence. Donc si tout n'est pas clair pour vous, n'hésitez pas à poser des questions, de préférence sur le forum. Nous mettrons à jour cet article pour y apporter des précisions si nécessaire. Une fois que vous aurez compris le principe, vous réaliserez des crochets facilement. Et il est possible de faire beaucoup de choses cool par ce moyen.
Article inspiré de Hook creation walkthrough par Michael.
Accueil
Documentation
Aide & Support
Nous contacter
Soutenez Invision Board France
Sortie de la Community Suite 4.1 !
Commentaires recommandés
Rejoindre la conversation
Vous pouvez publier maintenant et vous inscrire plus tard. Si vous avez un compte, connectez-vous maintenant pour publier avec votre compte.