Ces règles sont des indications afin d'obtenir des modules de qualité.

Elles sont amenées à évoluer pour plus de précision dans le temps.

Règles générales

• Quel est le besoin ? Est-ce que le module y répond ? Est-ce qu'il n'existe pas déjà une solution à ce besoin ?
• Bien réfléchir à la conception du module
• Bien penser la structure des données stockées
• Suivre les règles d'UX de Paheko
• Suivre les bonnes pratiques de ce document

Consistance des données

• À l'enregistrement, utiliser les schémas JSON pour s'assurer de la consistance des données enregistrées.
• Valider les données envoyées par formulaire : le schéma JSON n'est là que pour s'assurer que les données stockées correspondent à ce qui est prévu.
• Transformer les données passées à la fonction save avec les filtres boolval, intval, arrayval, etc. pour s'assurer de leur type

De par le stockage des données sous forme de document JSON, il n'existe pas de versionnement des structures de données, pas de processus de mise à jour (migration) du schéma des données. Si vous désirez versionner le schéma, ça sera au module de le faire et de gérer les migrations.

Code

Indentation

• Toujours utiliser des tabulations, pas des espaces pour indenter.
• Ne pas mixer tabulations et espaces pour indenter.
• La taille d'une tabulation est de 4 espaces.
• Toujours indenter le contenu des sections, et des blocs if, else, elseif.
• Indenter en accord avec le HTML environnant le code Brindille.
• Il est possible et même conseillé de mettre les paramètres d'une fonction ou d'une section sur plusieurs lignes.

Exemple :

{{#load
    type="category"
    order="title COLLATE U_NOCASE"
}}
    {{:link href="/%s"|args:$uri label=$title}}
{{else}}
    <p class="alert block">Aucune catégorie n'existe.</p>
{{/if}}

Voir le fichier .editorconfig de Paheko pour référence.

Références aux tables SQL

Ne pas créer de requête faisant référence explicitement à des tables de modules, celles-ci n'existent pas forcément, ou peuvent avoir un autre nom.

Par exemple :

{{#select
    key
    FROM module_data_equipment as cat
    WHERE json_extract(cat.document, '$.type') = 'category'
}}

Utiliser plutôt :

{{#load type="category"}}

Il est possible de faire référence aux tables de Paheko (voir le fichier schema.sql de Paheko pour leur schéma), mais il est préférable d'utiliser plutôt une section si une section existe pour les données visées.

Exemple :

{{#select * FROM acc_transactions WHERE id=42}}

Préférer :

{{#transactions id=42}}

Sécurité

Normalement les modules ne peuvent pas modifier la base de données SQL en dehors de leur table et de leur configuration. Ils ne peuvent pas non plus faire de requête externe ou autre.

Mais ils peuvent toujours permettre de récupérer des données personnelles, ou envoyer des mails. Il est aussi possible de faire une attaque en remplissant leurs données.

• Attention aux données stockées :
  • vérifiez qu'elles correspondent à ce qui est demandé ;
  • limitez la taille des champs texte ;
  • limitez la taille des nombres.
• Attention à bien limiter certaines actions aux personnes connectées et autorisées avec restrict : par défaut les modules sont publics, sauf si restrict_section et restrict_level sont spécifiés dans module.ini
• Limiter l'utilisation du filtre raw à certains cas précis.
• Limiter l'envoi de mails depuis une page publique à une vérification de captcha.
• Limiter (si possible) toute action de création / modification de donnée aux membres connectés.

Écoconception

• Tester le fonctionnement avec la limitation de vitesse à "Slow 3G" dans les outils de développement du navigateur : l'expérience utilisateur doit être satisfaisante (moins d'une seconde pour chaque action).
• Limiter le nombre de requêtes, de fichiers inclus, de code exécuté, au minimum nécessaire.

Ressources externes

• Aucune ressource externe ne doit être inclue dans le code (font, javascript, image, etc.)
• Ne pas utiliser de tracker, d'outil de statistiques, etc.

Javascript

• Minimiser l'usage du javascript :
  • ne l'utiliser que pour améliorer l'expérience utilisateur (progressive enhancement)
  • l'interface doit être visible et fonctionnelle à 99% sans javascript (graceful degradation)
  • certaines exceptions sont possibles pour des besoins spécifiques
• Ne pas utiliser de librairie lourde (plus de 100 Ko) ou nécessitant l'usage de npm, yarn, webpack ou autre
• Le code javascript ne doit pas être minifié, sauf s'il s'agit d'une librairie externe
• Si une librairie externe est inclue, sa licence doit être mentionnée, et si la librairie est minifiée, l'adresse du code source original doit être mentionnée

UX

• Toujours utiliser les éléments de design de Paheko, ne pas en créer de nouveaux, sauf besoin spécifique.