[Doc] Template & Tuto officiel FR des MODs v2.0.1

Découvrez ici une liste de documents concernant phpBB: son installation, sa mise à jour et enfin son utilisation.
En bref, apprenez ici à vous servir de phpBB2!

Modérateur: Equipe

Règles du forum
A lire impérativement sur notre page : Règlement

[Doc] Template & Tuto officiel FR des MODs v2.0.1

Messagepar Tchock » 25 Aoû 2003 à 14:24

Traduit et adapté de la structure des MODs du groupe phpBB - à jour au 17 Avril 2007

» Template & Tuto officiel FR des MODs v2.0.1
Le groupe phpBB a conçu une structure type de MOD qu'il est obligatoire d'utiliser pour toute demande de soumission d'un MOD en vue d'une intégration du MOD, dans leur base de données.
Dans le même esprit, l'équipe de phpBB-fr.com a traduit ce document officiel et il est demandé donc de l'utiliser pour toute demande de validation de MOD pour phpBB, afin qu'il soit intégré à la nouvelle base de données de MODs.




    » Voici la structure type officielle dans son ensemble:
    Code: Tout sélectionner
    ##############################################################
    ## MOD Title: Titre_du_mod_en_anglais
    ## MOD Author: Nom_d'utilisateur_de_l'auteur_du_mod < son_e-mail > (son_nom_réel) adresse_de_son_site_web
    ## MOD Description: Description_concise_de_ce_que_permet_le_mod
    ## MOD Version : x.x.x
    ##
    ## Installation Level: (Facile/Intermédiaire/Difficile)
    ## Installation Time: x minute(s)
    ## Files To Edit: (x pour le nombre de fichier ou N/A si aucun fichier)
    ##		fichier_1
    ##		fichier_2
    ##		etc
    ## Included Files: (x pour le nombre de fichier ou N/A si aucun fichier)
    ##      fichier_1
    ##      fichier_2
    ##      etc
    ## License: http://opensource.org/licenses/gpl-license.php GNU General Public License v2
    ##############################################################
    ## Pour des raisons de sécurité, vous êtes priés de consulter régulièrement :
    ## http://forums.phpbb-fr.com afin d'obtenir la dernière version de ce MOD.
    ## Bien que les MODs sont vérifiés avant d'être autorisés à figurer dans
    ## la base de données de MODs, il n'y a aucune garantie qu'aucun problème
    ## de sécurité ne soit pas présent dans le MOD. Par conséquent, phpBB-fr.com
    ## n'assurera aucun support pour les MODs absents de leur base de données,
    ## consultable sur : http://forums.phpbb-fr.com
    ############################################################## 
    ## Author Notes:
    ##
    ############################################################## 
    ## MOD History:
    ##
    ##   YYYY-MM-DD - Version x.x.x
    ##      - Notes_sur_la_version.
    ##
    ############################################################## 
    ## Avant d'ajouter ce MOD à votre forum, il vous est fortement conseillé
    ## d'effectuer une sauvegarde des éléments que vous allez modifier.
    ##############################################################
    
    #
    #-----[ ACTION ]------------------------------------------
    #
    
    #
    #-----[ ACTION ]------------------------------------------
    #
    
    #
    #-----[ ACTION ]------------------------------------------
    #
    
    #
    #-----[ SAVE/CLOSE ALL FILES ]------------------------------------------
    #
    # EoM

    » Ce qui suit est donc le tutorial détaillé sur comment utiliser cette structure type de MOD.

    » Tous les MOD qui nous sont soumis devront :
    - respecter ce tutorial,
    - utiliser le thème /subSilver/,
    - ne plus comporter de bug (défaut dans le code),
    - utiliser les systèmes de gestion des accès à la base de données, des thèmes et des langues, propres à phpBB2.



      La première partie de notre structure type est celle-ci :

      Code: Tout sélectionner
      ##############################################################
      ## MOD Title: Titre_du_mod_en_anglais
      ## MOD Author: Nom_d'utilisateur_de_l'auteur_du_mod < son_e-mail > (son_nom_réel) adresse_de_son_site_web
      ## MOD Description: Description_concise_de_ce_que_permet_le_mod
      ## MOD Version : x.x.x
      ##
      ## Installation Level: (Facile/Intermédiaire/Difficile)
      ## Installation Time: x minute(s)
      ## Files To Edit: (x pour le nombre de fichier ou N/A si aucun fichier)
      ##		fichier_1
      ##		fichier_2
      ##		etc
      ## Included Files: (x pour le nombre de fichier ou N/A si aucun fichier)
      ##      fichier_1
      ##      fichier_2
      ##      etc
      ## License: http://opensource.org/licenses/gpl-license.php GNU General Public License v2
      ##############################################################


        » Voilà une rapide explication de chaque rubrique :

        » MOD Title: Il faut renseigner ici simplement le nom du MOD.
        Il faut indiquer ici le titre du MOD en anglais. Si l'auteur du MOD souhaite indiquer un titre en français, il faut ajouter sur le même ligne, après le titre anglais, le titre du MOD en français comme ceci :

        Code: Tout sélectionner
        ## MOD Title: Titre_du_mod_en_anglais // Titre_du_mod_en_français


        » MOD Author: Cette rubrique comporte 4 parties :
          » Nom_d'utilisateur_de_l'auteur_du_mod: Il faut renseigner ici le nom d'utilisateur de l'auteur du MOD (obligatoire),
          » Son_e-mail: Il faut renseigner ici l'e-mail de l'auteur du MOD < > (obligatoire),
          » Son_nom_réel: Il faut renseigner ici le nom de l'auteur du MOD ou "N/C" si il ne peut être communiqué,
          » Adresse_de_son_site_web: Il faut renseigner ici l'adresse URL du site/forum de l'auteur du MOD ou "N/C" si elle ne peut être communiquée.

            Image Il faut laisser des espaces entre les guillemets et l'e-mail de l'auteur du MOD, comme ceci < francois@pignon.com >. Par ailleurs, il est interdit de mettre des espaces autour du "@" ou de le remplacer par tous autres caractères comme "AT".

            Image Seul le nom et l'adresse URL de l'auteur du MOD sont optionnels (mais doivent être remplacés par "N/C" si ils ne peuvent être communiqués). Le nom d'utilisateur et l'adresse e-mail de l'auteur du MOD sont obligatoires pour pouvoir le contacter à tout moment!

          » Procéder de même manière pour les raisons suivantes:
            » Si il y a plusieurs auteurs, alors il faut ajouter une seconde ligne de type MOD Author:
            » Ou encore, si il y a lieu d'indiquer un traducteur, il faut alors ajouter la ligne ci-dessous, qui se présente de la même manière que la ligne de type MOD Author::

            Code: Tout sélectionner
            ## MOD Traductor: Nom_d'utilisateur_du_traducteur_du_mod < son_e-mail > (son_nom_réel) adresse_de_son_site_web

        » MOD Description: Il faut placer ici une description concise de ce que permet le MOD (3/4 lignes maximum). Mettre des explications plus longues dans le champs Author Notes:.

        » MOD Version: Comme le MOD doit être totalement exempt de bug (défaut dans le code), la première version doit avoir le numéro 1.0.0. Par la suite, il faut respecter le système de numérotation des MODs pour les nouvelles versions.
        - changer le 1er chiffre pour une révision ou une réécriture complète du MOD,
        - changer le 2nd chiffre pour l'ajout d'une nouvelle fonctionnalité ou une correction de sécurité majeure,
        - changer le 3ème chiffre pour de simples corrections de bugs (défauts dans le code).

        » Installation Level: Il faut renseigner ici le niveau de difficulté d'installation du MOD, selon son auteur (Facile/Intermédiaire/Difficile).

        » Installation Time: Il faut renseigner ici un temps moyen d'installation du MOD, selon son auteur (en minutes).

        » Files To Edit: Il faut renseigner ici le nombre de fichiers à modifier pour installer le MOD puis en dessous, il faut énumérer les fichiers.

        » Included Files: Il faut renseigner ici le nombre de fichiers inclus et nécessaires (donc obligatoires et seulement ceux obligatoires) à l'installation du MOD puis en dessous, il faut énumérer les fichiers.
        Ces fichiers peuvent être des fichiers à copier dans un ou des répertoires de phpBB, mais aussi des fichiers d'instructions à exécuter pour réaliser l'installation (fichiers de type *.php, *.tpl, *.gif, etc...).

        » License: C'est la licence sous laquelle le MOD est défini. Dans 99% des cas, il sera réalisé sous la licence GNU General Public License v2. Consulter cet article pour d'avantage d'informations.


        » Et voilà.
          La première partie de la structure type des MODs est terminée.

      Avertissement de sécurité

        » Nous demandons que tous les MODs qui nous sont soumis sur phpBB-fr.com, et afin qu'ils soient intégrés à notre base de données, comportent cet avertissement de sécurité.
        Code: Tout sélectionner
        ##############################################################
        ## Pour des raisons de sécurité, vous êtes priés de consulter régulièrement :
        ## http://forums.phpbb-fr.com afin d'obtenir la dernière version de ce MOD.
        ## Bien que les MODs sont vérifiés avant d'être autorisés à figurer dans
        ## la base de données de MODs, il n'y a aucune garantie qu'aucun problème
        ## de sécurité ne soit pas présent dans le MOD. Par conséquent, phpBB-fr.com
        ## n'assurera aucun support pour les MODs absents de leur base de données,
        ## consultable sur : http://forums.phpbb-fr.com
        ##############################################################

      Author Notes:

        » La section Author Notes: donne la possibilité à l'auteur du MOD de placer ici les informations que celui qui va installer le MOD aura besoin de connaître.
        Code: Tout sélectionner
        ############################################################## 
        ## Author Notes:
        ##
        ############################################################## 

        » Il peut y avoir:

          » Des informations complémentaires à la description sur le fonctionnement du MOD,
          » Des informations complémentaires à la description sur l'installation/désinstallation du MOD,
          » Des informations complémentaires à la description sur l'utilisation du MOD,
          » Des informations complémentaires à la description sur le contenu obligatoire, disponible dans l'archive du MOD,
          » Des informations complémentaires à la description sur le contenu alternatif, disponible dans l'archive du MOD,
          » Des informations complémentaires à la description sur les droits d'auteurs pour le MOD,
          » Des informations complémentaires à la description sur les remerciements pour la réalisation le MOD,
          » Des informations complémentaires à la description sur des ressources complémentaies pour le MOD.

        » Cette section n'est pas là pour mettre une adresse URL de démonstration du MOD, ou tout autre coordonnée de contact.
        » Toutes les explications doivent être inclus ici, mais pas les actions.
        » Ne pas mettre les notes sur la même ligne que "Author Notes:". Il faut utiliser les lignes en dessous et/ou en ajouter.

      MOD History:

        » La section MOD History: est faite pour les notes propres à chaque version du MOD. En sommes indiquer les changements apportés, comme un journal sur le suivi de l'évolution d'un projet.

        » A chaque nouvelle version du MOD, cette section doit être complétée.
        Code: Tout sélectionner
        ############################################################## 
        ## MOD History:
        ##
        ##   YYYY-MM-DD - Version x.x.x
        ##      - Notes_sur_la_version.
        ##
        ##############################################################

          » Voilà un exemple pour cette section :
          Code: Tout sélectionner
          ##############################################################
          ## MOD History:
          ## 
          ##   2005-06-13 - Version 1.0.1
          ##      - Modifie les libellés de langue.
          ##      - Corrige le bug trucmuche.
          ##      - Ajoute la fonction duchemole.
          ##
          ##   2005-05-30 - Version 1.0.0
          ##      - Première version.
          ## 
          ##############################################################
        » Il est demandé à tous de suivre cette manière de présenter le champs MOD History:.

      Rappel de la nécessiter d'effectuer une sauvegarde

        Code: Tout sélectionner
        ############################################################## 
        ## Avant d'ajouter ce MOD à votre forum, il vous est fortement conseillé
        ## d'effectuer une sauvegarde des éléments que vous allez modifier.
        ##############################################################

        » Ce simple rappel ne doit pas être enlevé pour des raisons évidentes.

      Les actions

        » Il y a 14 actions possibles:
        » SQL - Exécuter une ou des requêtes SQL
        » COPY - Copier un ou des fichiers vers un emplacement sur le serveur
        » DIY INSTRUCTIONS - Effectuer diverses actions
        » OPEN - Ouvrir un fichier spécifique
        » FIND - Trouver un morceau de code dans le fichier ouvert
        » REPLACE WITH - Remplacer le code trouvé par ce code
        » AFTER, ADD - Ajouter après le code trouvé (sur la ligne en dessous), ce code
        » BEFORE, ADD - Ajouter avant le code trouvé (sur la ligne au dessus), ce code
        » INCREMENT - Augmenter ou diminuer la valeur d'un nombre
        » IN-LINE FIND - Dans la ligne précédemment trouvée, trouver ce code
        » IN-LINE AFTER, ADD - Après le code trouvé dans la ligne, ajouter ce code
        » IN-LINE BEFORE, ADD - Avant le code trouvé dans la ligne, ajouter ce code
        » IN-LINE REPLACE WITH - Remplacer le code trouvé dans la ligne par ce code
        » SAVE/CLOSE ALL FILES - Sauvegarder et fermer tous les fichiers ouverts


        » Si ces 14 actions ci-dessus ne sont pas suffisantes, il faut contacter le responsable de l'équipe des MODs par message privé.

        » Les "Actions" constituent, étape par étape, la procédure spécifique nécessaire à l'installation du MOD.

        » Les voilà présentées tel qu'elle doivent l'être dans le MOD :
        Code: Tout sélectionner
        # 
        #-----[ SQL ]-------------------------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ COPY ]------------------------------------------------
        #

        Code: Tout sélectionner
        #
        #-----[ DIY INSTRUCTIONS ]------------------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ OPEN ]------------------------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ FIND ]------------------------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ REPLACE WITH ]----------------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ AFTER, ADD ]------------------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ BEFORE, ADD ]-----------------------------------------
        #

        Code: Tout sélectionner
        #
        #-----[ INCREMENT ]-------------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ IN-LINE FIND ]---------------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ IN-LINE AFTER, ADD ]----------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ IN-LINE BEFORE, ADD ]---------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ IN-LINE REPLACE WITH ]--------------------------------
        #

        Code: Tout sélectionner
        # 
        #-----[ SAVE/CLOSE ALL FILES ]--------------------------------
        #
        #EoM


        » Et voilà quelques exemples d'actions accompagnés d'explications:
        Code: Tout sélectionner
        # 
        #-----[ SQL ]---------------------------------------------------------
        # 
        CREATE TABLE `phpbb_config` ( 
          `config_name` varchar(255) NOT NULL default '', 
          `config_value` varchar(255) NOT NULL default '', 
          PRIMARY KEY  (`config_name`) 
        ) TYPE=MyISAM;

        » Par ces instructions, la personne qui installera le MOD devra exécuter cette requête ci-dessus pour créer une table dans sa base SQL.

        » Si une action SQL doit être présente dans le MOD, elle doit être placée en première position.

        Code: Tout sélectionner
        # 
        #-----[ COPY ]-------------------------------------------------------- 
        # 
        copy foo_body.tpl to templates/subSilver/foo_body.tpl 
        copy foo_body.tpl to templates/subSilver/ 
        copy *.* to templates/subSilver/

        » Par ces instructions il est possible de télécharger, copier les fichiers sur le serveur.

        » Si une action COPIER doit être présente dans le MOD, elle doit être placée après SQL et avant le reste des actions.
        Il est posssible de regrouper toutes les instructions de copie au sein de la même action COPY.

        Code: Tout sélectionner
        #
        #-----[ DIY INSTRUCTIONS ]------------------------------------------
        #
        Réaliser un CHMOD de type 777 sur les fichiers suivants :
         - foo.php
         - bar.php
        Exécuter le fichier db_install.php via son navigateur et suivre les instructions

        » Les instruction DIY ("do it yourself" = "Le faire soit même") sont des instructions, dont la personne installant le MOD, doit exécuter avant que le MOD ne soit entièrement installé.
        Elles peuvent comprendre l'exécution de scripts exécutant des requêtes SQL, comme des instructions de CHMOD, etc.

        Code: Tout sélectionner
        # 
        #-----[ OPEN ]---------------------------------------------------------
        # 
        includes/constants.php

        » Dans l'exemple ci-dessus, on ouvre le fichier "constants.php" qui est situé dans le répertoire "includes", dans la racine de phpBB.

          Image Ne pas commencer d'action OPEN par un "/" et ne pas utiliser /phpBB2/ ou quoi que ce soit de ce genre non plus.

        » L'action OPEN sera toujours la première du MOD après SQL , COPIER et DIY.

        Code: Tout sélectionner
        # 
        #-----[ FIND ]---------------------------------------------------------
        # 
        {L_NEW_POSTS}

        » Ici, on va chercher {L_NEW_POSTS} dans le code du fichier que l'on vient d'ouvrir.

        » FIND est une manière simple pour la personne qui va installer le MOD de savoir exactement sur quelles lignes quelque chose qui va suivre va avoir lieu.

        Code: Tout sélectionner
        # 
        #-----[ REPLACE WITH ]-------------------------------------------------
        # 
        
        {L_YOUR_VARIABLE}

        » Ici on va REMPLACER la ligne de {L_NEW_POSTS} PAR {L_YOUR_VARIABLE}.

        » REPLACE WITH replace la ou les lignes trouvées par le nouveau code indiqué.

        Code: Tout sélectionner
        # 
        #-----[ AFTER, ADD ]---------------------------------------------------
        # 
        
        &lt;img src="templates/subSilver/images/some_new_image.gif" alt="{L_YOUR_VARIABLE}"/&gt;

        » Ici on va après la ligne {L_NEW_POSTS} (en dessous), ajouter le nouveau code indiqué.

        » AFTER, ADD permet de demander à la personne qui installe le MOD d'ajouter du code APRES celui qu'il vient de TROUVER (sur la ligne en dessous).

        Code: Tout sélectionner
        # 
        #-----[ BEFORE, ADD ]--------------------------------------------------
        # 
        
        &lt;img src="templates/subSilver/images/some_new_image.gif" alt="{L_YOUR_VARIABLE}"/&gt; 


        » Ici on va AVANT la ligne {L_NEW_POSTS} (au dessus), AJOUTER le nouveau code indiqué.

        » BEFORE, ADD permet de demander à la personne qui installe le MOD d'ajouter du code AVANT celui qu'il vient de TROUVER (sur la ligne au dessus).


        Code: Tout sélectionner
        #
        #-----[ INCREMENT ]-------------------------------------
        #
        %:1

        » L'action INCREMENT est utilisée pour ajouter ou soustraire un montant à un nombre. Il est surtout utilisé pour colspan et rowspan du template.
        Cette action nécessite d'être précédée par une instruction FIND ou IN-LINE-FIND où il aura été remplacé le nombre que souhaitant être remplacé par {%:1}.
        Par exemple :
        Code: Tout sélectionner
        #
        #-----[ FIND ]------------------------------------------
        # 
        <td class="row1" align="center" valign="middle" rowspan="{%:1}">
        
        #-----[ IN-LINE-FIND ]------------------------------------------
        #
        {%:1}
        
        #
        #-----[ INCREMENT ]-------------------------------------
        #
        %:1 +1

        » Si il y a plusieurs nombres à changer dans la ligne, alors il faut utiliser {%:2}, {%:3} etc.

        » Dans l'instruction INCREMENT il faut indiquer le nombre à modifier suivi du montant que souhaitant être ajouté ou soustrait.
        Ne pas indiquer de montant le nombre sera inchangé, comme par exemple :
        Code: Tout sélectionner
        #
        #-----[ INCREMENT ]-------------------------------------
        #
        %:1 +10
        
        #
        #-----[ INCREMENT ]-------------------------------------
        #
        %:2 -3
        
        #
        #-----[ INCREMENT ]-------------------------------------
        #
        %:3 +5

        » Il faut savoir qu'il est possible aussi d'utiliser le code :
        Code: Tout sélectionner
        # 
        #-----[ IN-LINE INCREMENT ]-------------------------------------------------
        #



        Code: Tout sélectionner
        # 
        #-----[ IN-LINE FIND ]-------------------------------------------------
        # 
        user_from = '" . str_replace("\'", "''", $location) . "',

        » Par cette action (IN-LINE FIND) il est possible de trouver une portion de code dans une ligne de code.

        Code: Tout sélectionner
        # 
        # 
        #-----[ IN-LINE AFTER, ADD ]-------------------------------------------
        # 
        user_from_flag = '$user_flag',

        » IN-LINE AFTER, ADD (-DANS LA LIGNE APRES, AJOUTER-) permet d'ajouter du code directement après celui trouvé dans la ligne.

        Code: Tout sélectionner
        # 
        # 
        #-----[ IN-LINE BEFORE, ADD ]------------------------------------------ 
        # 
        user_from_flag = '$user_flag', 

        » IN-LINE BEFORE, ADD (-DANS LA LIGNE AVANT, AJOUTER-) permet d'ajouter du code directement avant celui trouvé dans la ligne.

        Code: Tout sélectionner
        # 
        # 
        #-----[ IN-LINE REPLACE WITH ]------------------------------------------ 
        # 
        user_from_flag = '$user_flag',

        Cet exemple permet de remplacer dans la ligne ce code trouvé :
        Code: Tout sélectionner
        user_from = '" . str_replace("\'", "''", $location) . "', 

        » Par celui ci:
        Code: Tout sélectionner
        user_from_flag = '$user_flag', 



        » Enfin, à la toute fin du MOD, ajouter :
        Code: Tout sélectionner
        # 
        #-----[ SAVE/CLOSE ALL FILES ]------------------------------------------ 
        # 
        # EoM 
        

        » Il s'agit simplement d'un rappel de "SAUVEGARDER/FERMER TOUS LES FICHIERS" qui a été modifié.
        EoM signifie End of MOD : fin du MOD.

      Apostrophes / Guillemets

        » Comment utiliser les apostrophes/guillemets dans les libellés?

          » Si il est défini une chaîne comme ceci "Bonjour !", PHP va l'analyser et essayer de remplacer les variables qu'il pourra trouver dedans. La plupart du temps cette étape est inutile et va à l'encontre des standards de programmation de phpBB. Alors qu'une chaîne définie comme ceci 'Bonjour !' n'entraîne pas d'analyse et d'essai de substitution de variable de la part de PHP.

      Annexes


Tutorial (en sa version 2.0.1) réalisé par l'équipe des MODs de phpBB-fr.
Il est possible de diffuser ce tutorial sur son site web.
Si c'est le cas, mettre un lien vers ce message pour une meilleure prévention des mises à jour.


@+.

-Edité par ErnadoO-
Motif: Correction multiple le 17/04/07
Modifié en dernier par Tchock le 04 Mar 2004 à 23:07, modifié 2 fois.
Tchock
Dieu des floodeurs
Dieu des floodeurs
 
Messages: 5938
Enregistré le: 30 Avr 2002 à 11:40

Retourner vers [phpBB 2.0.x] Forum de documentation

 


  • Articles en relation
    Réponses
    Vues
    Dernier message

Qui est en ligne

Utilisateurs parcourant ce forum : Aucun utilisateur enregistré et 1 invité