Tous les sites ont besoin de transmettre les informations et bonnes pratiques aux intervenants. Même et surtout si l'on est seul 😀
Chacun y va de sa méthode : la page web, le document papier, etc. Document qui faute de mise à jour, finit souvent aux oubliettes.
J'ai donc recherché une méthode qui réponde aux critères suivants :
- être rapide à mettre en oeuvre. Un simple copier-coller de la doc d'un autre site doit faire une grande partie du travail.
- la mise à jour doit être automatique par récupération des données saisies dans Joomla, ajout d'extensions, prefs de UP
- la présentation doit être synthétique. Elle peut servir de navigation vers d'autres articles plus détaillés
- il doit être possible d'adapter le contenu en fonction du rôle du lecteur (rédacteurs, webmaster et développeur)
- accessoirement, elle doit faire ressortir les oublis, les mauvais classements, les extensions inutiles, ... avant de livrer le site.
Ma solution avec UP :
Elle consiste en un article Joomla! avec un niveau d'accès permettant aux rédacteurs de le consulter à partir du frontend.
Plusieurs actions UP sont utilisées pour récupérer les informations sur la structure et le paramétrage du site.
L'action filter permet d'adapter les informations au niveau de l'intervenant.
La documentation peut être répartie en grandes sections :
- informations générales : adresses utiles, procédures générales, ...
- la navigation : la structure des menus sous une forme condensée avec la possibilité d'ajouter des informations
- l'organisation du contenu : une vue synthétique des catégories
- les modules et positions : la liste des modules avec un petit dessin pour montrer les positions disponibles
- le style : le template utilisé, les couleurs et polices utilisées, les dimensions des images
- Aide à la rédaction : exemple de blocs de contenu, prefset de UP, aide-mémoire divers, ...
- Données techniques du site : liste des extensions, modules et plugin en frontend et backend
Cet exposé se limite à un site utilisant les fonctionnalités de base de Joomla! Il sera sans doute nécessaire d'ajouter d'autres sections pour les grosses extensions que vous utilisez.
Pour récupérer des informations de ces dernières, utilisez l'action SQL
Organisation de cet article :
Pour une fois, je ne vais pas mettre de démonstration, mais uniquement les explications pour que vous expérimentiez par vous-même.
Vous pouvez recopier les exemples de code au fur et à mesure des explications, ou simplement télécharger l'ensemble du code à partir de ce fichier :
up-dossier-technique.zip (6.17 ko - 25/01/2025 19:37) téléchargé 153 fois dernier téléchargement le 04/02/2025 10:18
Exemple de code pour le dossier technique d'un site
Dans les exemples de code ci-dessous ou dans le fichier à télécharger, les éléments que vous devez remplacer pour l'adapter à votre site sont clairement identifiés de cette façon : XXXX ou XX_id_categorie_XX
Pour faire le plus simple possible, je considère que vous connaissez UP et de ses actions. Si besoin, des liens vous proposeront d'aller vers des informations détaillées.
Par souci de simplicité et de clarté, je n'utilise pas les jeux d'options, mais je vous invite fortement à y recourir.
Prérequis
Vous avez créé un article pour contenir le dossier technique ainsi qu'un lien de menu pour y accéder. Il est important de définir un niveau d'accès correspondant à celui des personnes devant le consulter.
Pour nous déplacer rapidement et avoir une vue d'ensemble de ce long article, nous utilisons les actions UP Tabslide et UP Toc
{up tabslide=sommaire | tabLocation=right | clickScreenToClose | panel-style=min-width:170px;max-height:60vh}
{up toc | class=chevron | style=max-height:58vh;overflow-y:auto}
{/up tabslide}Pour limiter l'information à certains intervenants, utilisez l'action UP Filter.
exemple : {up filter | admin}passage réservé aux superadmins{/up filter}
informations générales
Il est judicieux d'indiquer au début ou à la fin du document, des informations de contact et un rappel des bonnes pratiques
Les menus
Un bon moyen pour découvrir l'organisation d'un site est de consulter les menus.
L'action jmenus_list permet d'en avoir une vue condensée.
Les menus affichés dépendent du niveau d'accès du lecteur.
Un exemple de code pour cette section pourrait être :
<h2>La navigation sur le site</h2>
{up tab=accordion | title-tag=h3}
<h3>Le menu principal en haut</h3>
<p>C'est le menu principal du site. En vue smartphone, un bouton 'hamburger' l'ouvre sur le côté droit.</p>
<p>{up jmenus_list=XX_mainmenu_XX
| template-menutype=[h4 class="notoc"]##title## (id:##id##)[/h4] ##description## / ##menutype##
| template-menu = ##title-link##[small] (id:##id##) ##access## - ##component## ##language##[/small] ##note##}</p>
<h3>Le menu secondaire en pied</h3>
<p>Ce menu est utilisé pour proposer des liens secondaires.</p>
<p>{up jmenus_list=XX_footermenu_XX
| template-menutype=[h4 class="notoc"]##title## (id:##id##)[/h4] ##description## / ##menutype##
| template-menu = ##title-link##[small] (id:##id##) ##access## - ##component## ##language##[/small] ##note##}</p>
<h3>Le menu technique invisible</h3>
<p>Ce menu fournit les styles d'affichage pour le contenu appelé en dehors des menus. Il n'a pas besoin d'être visible, mais il est indispensable.</p>
<p>{up jmenus_list=XX_invisible_menu_XX
| template-menutype=[h4 class="notoc"]##title## (id:##id##)[/h4] ##description## / ##menutype##
| template-menu = ##title-link##[small] (id:##id##) ##access## - ##component## ##language##[/small] ##note##}</p>
{/up tab}
Chaque menu est mis dans un panneau déroulant avec l'action tab
Notez l'utilisation de la classe notoc pour les titres h4 des menus. Cela permet de ne pas les prendre en compte dans le sommaire de votre dossier technique.
L'organisation du contenu
L'action jcategories-list affiche l'arborescence d'une ou plusieurs catégories du site.
Un exemple de code pour toutes les catégories pourrait être :
<h2>L'organisation du contenu</h2>
<p>Les catégories facilitent le classement des articles et autres contenus.</p>
<p>{up jcategories-list}</p>
Vous pouvez aussi afficher tout ou partie des articles d'une catégorie. Profitez-en pour passer des informations importantes pour ce type de contenu.
<p>{up faq}</p>
<h4>Général <small>(id XX) liste des articles utilisés pour les options principales des menus</small></h4>
<p>XX_Présentation_et_informations_importantes_XX</p>
<p>{up csv2table
| model=blue
| header=ID;Titre;Contenu;Tags
| col="c5-40-50-c10"
}</p>
<p>{up jcontent_by_categories=XX_id_categorie_XX
| main-tag=0
| item-tag=0
| sort-by=ordering
| sort-order=asc
| tags-list-style
| tags-list-separator=,
| template=##id##;##title-link## [small]##subtitle##[/small];##intro-text,250####note##;##tags-list##
}</p>
<p>{/up csv2table}</p>
</p><!-- les autres catégories --></p>
<p>{/up faq}</p>
J'utilise l'action FAQ pour faciliter la navigation.
Le code ci-dessus ne liste qu'une catégorie. A vous de le dupliquer pour qu'il corresponde à votre structure.
Si vous renommez les fichiers custom/prefs.ini.dist en custom/prefs.ini, vous trouverez les jeux d'options correspondants sous le nom de sitemap-admin . Ce qui donne le code suivant :
<p>{up faq}</p>
<h4>Général <small>(id XX) liste des articles utilisés pour les options principales des menus</small></h4>
<p>XX_Présentation_et_informations_importantes_XX</p>
<p>{up csv2table=sitemap-admin}</p>
<p>{up jcontent_by_categories=XX_id_categorie_XX | prefset=sitemap-admin}</p>
<p>{/up csv2table}</p>
</p><!-- les autres catégories --></p>
<p>{/up faq}</p>
Cela ne vous semble pas plus simple !
Notez que j'utilise le prefset comme argument principal pour csv2table, et comme argument d'une option prefset pour jcontent_by_categories puisque l'argument principal est l'id de la catégorie.
Pour afficher les 10 derniers articles d'une catégorie, tout en conservant les autres options, utilisez ce shortcode :
{up jcontent_by_categories=XX_id_categorie_XX
| prefset=sitemap-admin
| sort-by=created
| sort-order=desc
| maxi=10}Les modules
La liste des modules peut-être récupérée à l'aide de l'action jmodules-list
En ce qui concerne les positions, j'ai pour habitude de faire un petit croquis que j'affiche à l'aide de l'action modal
<h2>Les modules</h2>
<p>Il s'agit des blocs situés en périphérie du contenu principal dans des conteneurs ou positions.</p>
<p>{up jmodules_list}</p>
<p>{up modal=images/admin/XXXX.jpg | label=voir les positions disponibles pour le template XXXX | class=btn btn-primary}</p>- dans les paramètres des templates, activer la prévisualisation des positions
- afficher votre site en ajoutant
/index.php?tp=1à son URL - une fois les positions notées, n'oubliez pas de désactiver la prévisualisation des positions
Le style
Outre un rappel sur la charte graphique du site, il est bon de connaitre les templates installés grâce à l'action jextensions-list. Ce qui peut donner ce genre de code :
<h2>Le style</h2>
<p>Le site utilise le template <strong>XXXXX</strong> qui définit :</p>
<ul>
<li>XXX</li>
<li>XXX</li>
</ul>
<p>Pour info, ces templates sont installés :</p>
<p>{up jextensions-list=jextensions_list=template
| client=0
| template="##name## [small]##version## (id:##id##) ##author## [/small] ##note##"
| minimal-id=0}</p>
<h3>Les couleurs</h3>
<p>La couleur principale est le bleu #069 {up icon=Ux25AC,#069,2rem} utilisé pour les liens ({up icon=Ux25AC,#28f,2rem} #28f en survol). <br />Les couleurs secondaires sont le gris #555 {up icon=Ux25AC,#555,2rem} et le jaune #FFC000 {up icon=Ux25AC,#FFC000,2rem }</p>
<h3>Les images</h3>
<p>Sauf exception, les images font 1200px de large avec une version "-mini" (vignette) à 450px</p>
<p>Elles sont rangées dans des sous-dossiers de "images" selon la catégorie de l'article où elles sont utilisées</p>
J'utilise l'action icon pour montrer les couleurs utilisées. Les 3 arguments principaux étant un caractère Unicode représentant un rectangle dont je précise la taille et la couleur.
Aide à la rédaction
Cette section regroupe des aide-mémoire pour la création du contenu. Personnellement, je la scinde en 3 parties :
- exemples de mise en page
- exemple de shortcode UP
- liste des prefsets UP
Pour afficher du code, j'utilise mon plugin LM-Prism qui convertit automatiquement tous les caractères "dangereux" en entités HTML. C'est cela qui rend "bizarre" le code des exemples ci-dessous.
Exemples de mise en page
Pour assurer une homogénéité du site, il peut être nécessaire de fournir des blocs de code "prêt à l'emploi". Il suffira de le copier et de le coller en mode code dans l'article.
Comme exemple, voici celui que j'utilise pour les pages "démo" de ce site.
<h2Aide à la rédaction</h2>
<h3>Exemples de mise en page</h3>
<h4>La page démo d'une action</h4>
<p>Utilisée pour la <strong>démonstration d'une action</strong>, l'introduction de l'article sert pour le <strong>bloc de cgisotope</strong> et les <strong>news en page d'accueil</strong></p>
<p><b>Image</b> : on utilise une image de 150x150px</p>
<pre><code class="language-markup"><p class="bloc"><img class="left w2" src="/images/actions/xxx.png" />description rapide</p>
<mark><hr id="system-readmore" /></mark>
<div class="fg-row fg-gap fg-vcenter">
<div class="fg-c1 fg-cm2 fg-cs12 tc">
<img src="/images/actions/xxx.png" />
</div>
<div class="fg-c11 fg-cm10 fg-cs12">
<p>description longue</p>
<p class="box-note">Sur un script de <a href="/url" target="_blank">xxxx</a> (licence GPL v3.0)</p>
</div>
</div>
<p><b>{</b>up upactionslist=nom-action | demo=0 | class=mb2<b>}</b></p>
</code></pre>
<p>Si la démo possède des pages annexes, pensez à faire une liste en bas de l'article</p>
Vous pouvez aussi utiliser les templates de votre éditeur wysiwyg
Exemples de shortcode UP
Si vous utilisez ma méthode pour la documentation de votre site, il est fort probable que les rédacteurs utilisent UP au quotidien.
Avoir des exemples et paramétrages de shortcodes simplifie leur utilisation et assure une homogénéité du site
Un exemple pour insérer un sommaire (toujours en utilisant LM-Prism):
<h3>Exemples de shortcode UP</h3>
<h4>TOC : sommaire d'un article</h4>
<pre><code class="language-markup"><b>{</b>up tabslide=sommaire | tabLocation=right | clickScreenToClose | panel-style=min-width:170px;max-height:60vh<b>}</b>
<b>{</b>up toc | class=chevron | style=max-height:58vh;overflow-y:auto<b>}</b>
<b>{</b>/up tabslide<b>}</b></code></pre>Liste des jeux d'options UP
Les jeux d'options de UP facilitent son utilisation. Encore faut-il les connaitre !
Pour cela, nous utilisons l'action upprefset. Les actions Icon et hr son traitées séparément pour permettre un affichage graphique.
<h3>Liste des jeux d'options UP</h3>
<h4>ICON</h4>
<p>{up icon | info=2}</p>
<h4>HR ligne horizontale</h4>
<div class="fg-row fg-auto-6 fg-auto-m3 fg-auto-s2 fg-gap tc fg-vspace-center-1">
<div>{up hr=param} <code class="language-markup"><b>{</b>up hr=param<b>}</b></code></div>
<div>{up hr=typo-feuille} <code class="language-markup"><b>{</b>up hr=typo-feuille<b>}</b></code></div>
<div>{up hr=typo-text} <code class="language-markup"><b>{</b>up hr=typo-text<b>}</b></code></div>
<div>{up hr=up-demo} <code class="language-markup"><b>{</b>up hr=up-demo<b>}</b></code></div>
<div>{up hr=i-love-up} <code class="language-markup"><b>{</b>up hr=i-love-up<b>}</b></code></div>
</div>
<p>{up upprefset | css-head=#id h4[margin-top:10px]}</p>Note :
- pour icon, l'option info=2 permet d'afficher le résultat à la place du shortcode. Pour mémoire info=1, affiche les exemples comme un message Joomla.
- pour hr, j'utilise directement les classes CSS de UP afin d'afficher le rendu et son shortcode. J'utilise mon plugin LM-Prism pour désactiver les shortcodes en ajoutant des balises b autour des accolades.
- pour toutes les autres, l'action upprefset va afficher les jeux d'options prévus par le webmaster
Données techniques
Outre les infos sur l'hébergement, il est pratique de faire un inventaire des principales extensions installées. Nous utilisons à nouveau l'action jextensions-list
<p>Pour adapter un site Joomla aux besoins, on utilise des extensions. Un composant est une grosse fonctionnalité avec un menu dans l'administration, un module est un bloc ajouté en périphérie du contenu sur le site et un plugin réalise diverses actions (UP est un plugin!)</p>
<p>{up tab=accordion | title-tag=h3}</p>
<h3>Les composants</h3>
<p>{up jextensions-list=component | client=2 | sort=name<br /> | template=##name## [small]##version## (id:##id##) ##author## [/small] ##note##}</p>
<h3>Les modules côté site</h3>
<p>{up jextensions-list=module | client=0 | sort=name<br />| template=##name## [small]##version## (id:##id##) ##author## [/small] ##note##}</p>
<h3>Les plugins</h3>
<p>{up jextensions-list=plugin | client=2 | sort=folder,name<br />| template=[small]##folder##[/small] [span class="##state##"]##name##[/span] [small]##version## (id:##id##) ##author## [/small] ##note## <br />| model-folder=%s}</p>
<h3>Les modules côté administration</h3>
<p>{up jextensions-list=module | client=1 | sort=name<br />| template=##name## [small]##version## (id:##id##) ##author## [/small] ##note##}</p>
<p>{/up tab}</p>
<p><span class="t-red">En rouge</span>, les extensions inactives</p>Conclusion
J'espère que vous êtes arrivé au bout de cet article. J'ai essayé de faire simple, mais le sujet était vaste !
Si vous avez des commentaires ou des suggestions, n'hésitez pas à me les transmettre. Merci d'avance