Développement d'un add-on

La toute première chose à faire pour se lancer dans le développement avec XenForo est d'activer le mode développement.

Une simple ligne de code dans le fichier config.php suffit.
Sur votre serveur il se trouve :
chemin Et voici la ligne de code a rajouter:
php

Voici les principales lignes de commandes qui nous serviront dans l'interface de Terminal :

• Créer les fichiers de base
• Exporter les fichiers
• Définir une nouvelle version
• Générer le module complémentaire

$ php cmd.php xf-addon:create

$ php cmd.php xf-addon:export [addon_id]

$ php cmd.php xf-addon:bump-version [addon_id] --version-id 1020370 --version-string 1.2.3

$ php cmd.php xf-addon:build-release [addon_id]

Ouvrez Terminal (Cmder avec Laragon) et lancez la première commande:
commande  Enter an ID for this add-on: Demo/OpenGraph

---

on choisit l'ID pour l'add-on a créer: ici nous indiquons d'abord un espace de travail, Demo, puis l'ID de l'add-on, OpenGraph. De cette façon si vous créez plusieurs add-ons vous pouvez les créer dans le même espace de travail. En général on nomme l'espace de travail du nom du développeur ou de l'équipe de développement.

 Enter a title: Image OpenGraph pour les discussions

---

le titre de votre add-on, c'est ce titre qui apparaitra dans la liste des add-ons installés dans le panneau d'administration des utilisateurs

 Enter a version ID: 1000070

---

ici on défini la version de l'add-on. Parcourez cette page pour comprendre le fonctionnement de l'ID de version dans l'environnment XenForo:
Recommanded version ID format

 Does this add-on supersed a XenForo 1 add-on? (y/n) n

---

notre add-on n'est pas une version destiné à remplacer un add-on conçu pour XenForo 1, donc on répond non ici. À cet instant un fichier addon.json est créé.

 Does your add-on need a Setup file? (y/n) n

---

notre simple add-on ne nécessite pas un fichier Setup, donc réponse non.
les fichiers (un seul dans notre cas exemple) de base de notre add-on sont créés et ils se trouvent ici:
chemin

On retrouve dans le fichier le titre de l'add-on ainsi que sa version (ID et string) mais il nécessite quelques modifications:

• 'description': on précise ici la fonction, l'utilité du module complémentaire (add-on).
• 'dev': le nom du développeur ou de l'équipe de développement.
• 'dev_url': l'URL du site du développeur le cas échéant.
• 'faq_url': l'URL d'une FAQ sur le site du développeur le cas échéant.
• 'support_url': l'URL vers un site de support pour cet add-on.
• 'etc...'

tous ce champs ne sont pas obligatoires mais permettent de personnaliser votre création, plusieurs de ces éléments apparaitront dans la liste des add-ons installés dans le panneau d'administration des utilisateurs.

Pour le champ 'icon': vous avez la possibilité de définir une icône FontAwesome (v5), ici nous avons choisi des rouages:

• Le code fa-cogs donne mais vous pouvez définir une image qu'il conviendra de joindre au dossier de l'add-on.

Rentrons maintenant dans le vif du sujet: on se connecte à notre panneau administrateur de notre XenForo "local" et on se rend sur la page des add-ons pour constater que notre nouvelle création OpenGraph y figure bien.

On constate que notre module complémentaire est affublé du label Pending changes, nous avons manuellement édité le fichier addon.json il faut nous faut donc sychroniser ou reconstruire l'add-on pour être certain que les méta datas soient bien à jour:

• Pour synchroniser on utilise la ligne de commande suivante:
  commande
  $ php cmd.php xf-addon:sync-json Demo/OpenGraph
• Pour reconstruire on utilise le menu déroulant de l'add-on dans le panneau administrateur (ACP) et on clique sur Rebuild (ou reconstruire si votre ACP est traduit en français).

Tout est en ordre on peut maintenant se concentrer sur la fonctionnalité de notre add-on: intégrer l'image du premier message d'une discussion lors du partage sur les réseaux sociaux.

Pour cela nous allons effectuer un modification de template à l'aide des outils de développement intégrés à XenForo. Le template concerné est :

• thread_view

Dans l'ACP on ouvre le menu Apparence et on ouvre la page des modifications de template:
Menu Puis on crée une nouvelle modification en cliquant sur le bouton

Add template modification

On renseigne les champs du formulaire

 Template: thread_view

---

choix du template, le champ est en auto-complétion et une liste déroulante affine le choix de template au fur et à mesure que vous écrivez.

 Modification key: addOGcode

---

on choisit une clé de modification unique pour cette action, nommez cette clé en fonction de ce que vous allez modifier dans le template, ici nous rajoutons un bout de code pour ajouter l'image OpenGraph: addOGcode.

 Description: Adding OpenGraph code to the template

---

permet en un ligne de décrire votre modification du template. Utile pour le développeur pour comprendre en un coup d'oeil de quoi il s'agit mais aussi utile pour l'utilisateur final pour les mêmes raisons, a des fins de débogage par exemple.

 Template contents:

---

affiche automatiquement le contenu du template sélectionné dans le premier champ.

 Search type:

---

permet de sélectionner la méthode de recherche du code à remplacer dans le template sélectionné. Ici nous utiliserons un remplacement simple, on colle la partie du code que l'on veut remplacer. La deuxième option permet d'effectuer une recherche à partir d'une expression regex. PHP callback est une méthode de rappel d'un fichie PHP que l'on fournit dans les dossiers de l'add-on.

• Simple remplacement
• Regular expression
• PHP callback

La partie du template que l'on souhaite remplacer voir code.1 ci-contre et le code qui remplace voir code.2.

On ajoute simplement l'argument arg-imageUrl="" dans une instruction conditionnelle : si le message de création de la discussion comporte une image alors...

 Execution order: 10

---

si vous prévoyez plusieurs modifications de template et qu'un ordre doit être respecté alors utilisez cette fonction. Laissez à 10 le cas contraire.

laissez Automatically apply template modification coché par défaut, la modification du template s'effectuera automatiquement à l'installation de l'add-on.

 Add-on: Image OpnGraph pour les discussions

---

choisissez l'add-on pour lequel cette modification de template correspond, ici notre add-on Image OpenGraph pour les discussions.

Vous pouvez tester en direct votre modification avant de la sauvegarder en cliquant sur le bouton Test.

Test

• En rouge le code remplacé
• En vert le code ajouté

Si tout est ok on clique sur le bouton Save !

Save

<xf:if is="$thread.cover_image">
    <xf:macro template="metadata_macros" name="metadata"
        arg-description="{$fpSnippet}"
        arg-shareUrl="{{ link('canonical:threads', $thread) }}"
        arg-canonicalUrl="{{ link('canonical:threads', $thread, {'page': $page}) }}"
        arg-imageUrl="{$thread.cover_image}" />

<xf:if is="$thread.cover_image">
    <xf:macro template="metadata_macros" name="metadata"
        arg-description="{$fpSnippet}"
        arg-shareUrl="{{ link('canonical:threads', $thread) }}"
        arg-canonicalUrl="{{ link('canonical:threads', $thread, {'page': $page}) }}"
        arg-imageUrl="{$thread.cover_image}" />
    <xf:else/>
    <xf:macro template="metadata_macros" name="metadata"
        arg-description="{$fpSnippet}"
        arg-shareUrl="{{ link('canonical:threads', $thread) }}"
        arg-canonicalUrl="{{ link('canonical:threads', $thread, {'page': $page}) }}" />
</xf:if>

La construction de notre add-on avec les outils de développement XenForo est maintenant terminée, on peut générer la première version du module complémenataire afin de le proposer aux futurs utilisateurs !

Terminal : build-release

commande
Votre add-on est généré, vous pouvez retrouvez le dossier final ici : chemin
Le dossier Demo-OpenGraph-1.0.0.zip est celui que vous pourrez proposer sur votre canal de distribution habituel et/ou dans le gestionnaire de ressources de xenforo.com

  https://xenforo.com/community/resources/

Si après avoir proposé votre add-on au public vous apportez des modifications à celui-ci il conviendra de générer une nouvelle version puis une nouvelle "release".

Terminal : bump-version et build-release

commande commande
Une nouvelle version de votre module complémentaire est générée.