file-download ~ gestion téléchargements

Cette action affiche un lien vers un fichier ou tous les fichiers correspondant à un masque d'un dossier

Elle gère des compteurs et journaux des téléchargements

Il est possible d'autoriser le téléchargement aux possesseurs d'un mot de passe

Au départ, j'étais à la recherche d'un moyen pour connaitre le nombre de mises à jour de UP demandées par la méthode native de Joomla! (menu Extensions > mise à jour).
Ayant trouvé une solution, il me fallait afficher les stats et une gestion de fichiers avec un suivi des téléchargements

Version 1.9 Un énorme merci à Pascal (pmleconte) qui a repris le code pour permettre le téléchargement de tous les types de fichiers.

Version 2.3 Ajout option file-mask

La méthode simple

Un fichier unique

• plg_content_up-v1.0.zip (154.85 ko - 26/09/2023 12:21) téléchargé 51 fois dernier téléchargement le 13/03/2024 21:13
  

Ce petit shortcode fait beaucoup de choses :

{up file-download=up-old/plg_content_up-v1.0.zip}

• affichage d'une icône selon le type du fichier
• affichage du nom du fichier avec un lien pour le télécharger
• affichage date et taille du fichier
• affichage du nombre et date du dernier téléchargement
• mise à jour des statistiques et du journal des téléchargements (date/heure et IP)

Le fichier peut-être dans le dossier racine indiqué dans updownload.cfg (files par défaut) ou un de ses sous-dossiers.
Seuls les types de fichiers autorisés par le webmaster sont permis.

Bien entendu, tout cela est paramétrable !

Tous les fichiers d'un dossier

Il suffit d'indiquer le nom d'un sous-dossier du dossier racine indiqué dans updownload.cfg (files par défaut)

{up file-download=demo}

• up-dossier-technique.zip (2.96 ko - 26/09/2023 12:21) téléchargé 11 fois dernier téléchargement le 01/02/2024 09:00
  Ceci est un texte explicatif trouvé dans le fichier up-dossier-technique.zip.info situé dans le même dossier.
• lion.png (216.64 ko - 26/09/2023 12:21) téléchargé 11 fois dernier téléchargement le 01/02/2024 09:00
  
• demo.txt (27 o - 26/09/2023 12:21) téléchargé 6 fois dernier téléchargement le 15/04/2024 11:33
  
• demo.md (62 o - 26/09/2023 12:21) téléchargé 9 fois dernier téléchargement le 15/04/2024 11:33
  
• UP-unicode-top100.pdf (233.49 ko - 26/09/2023 12:21) téléchargé 48 fois dernier téléchargement le 26/01/2024 11:10
  

Informations :

• Par défaut, tous les fichiers du dossier ayant une des extensions ci-dessous sont listés.
  Votre webmaster a la possibilité de resteindre ou d'étendre les extensions permises dans le fichier updownload.cfg avec les fichiers custom/updownload.cfg et/ou custom/prefs.ini.
  zip,pdf,txt,md,png,jpg,gif,svg,doc,docx,xls,xlsx,odt,ods
• Il est possible d'avoir un texte explicatif en créant, dans le même dossier, un fichier texte ou au format HTML.  Il doit impérativement avoir le même nom+extension en ajoutant une autre extension ".info"
  Exemple : pour le fichier up-dossier-technique.zip, les informations sont trouvées dans le fichier  up-dossier-technique.zip.info

{up file-download=foo | file-mask=fic-*}

{up file-download=doc/UP-memo-redacteur-*.pdf}

 Avec un mot de passe

Pour limiter le téléchargement à des personnes non identifiées sur le site, mais à qui vous avez fourni un sésame, il suffit d'ajouter une option password avec le fameux sésame.

{up file-download=up-old/plg_content_up-v1.0.zip | password=joomla}

• plg_content_up-v1.0.zip (154.85 ko - 26/09/2023 12:21) téléchargé 51 fois dernier téléchargement le 13/03/2024 21:13
  

Le fichier pourra être téléchargé uniquement si le visiteur fournit le mot de passe qui lui a été communiqué. Bien entendu, le mot de passe ne sera pas visible ni récupérable sur le site.

Si vous utilisez cette option, je vous conseille de modifier le chemin racine des fichiers pour un nom moins "évident" que files. Voir "fichier de configuration" ci-après. En effet, cette partie du chemin d'accès au fichier ne sera jamais visible dans le source de la page. Donc impossible de récupérer le fichier directement par son URL.

Gestion des icônes

Sans indication spécifique, une icône de 32 pixels caractéristique du type de fichier sera affichée. Si l'option icon=16, l'icône fait 16 pixels.
Vous pouvez ajouter d'autres types d'icônes dans les sous-dossiers de plugins/content/up/assets/img/files

L'argument de l'option icon peut être le chemin vers une image comme dans l'exemple ci-dessous. Elle sera affichée en remplacement du mot clé ##icon## ou ##icon-link## de l'option template.

UP-unicode-top100.pdf
(233.49 ko)
téléchargé 48 fois
dernier téléchargement le 26/01/2024 11:10

{up file-download=demo/UP-unicode-top100.pdf
| icon=images/doc/UP-Memo-CSS.jpg
| class = tc bd-grisClair p1
| main-tag = div
| item-tag = 0
| template = ##icon-link##[br]##filename-link##[br](##size##)[br][small]##hit##[br]##lastdownload##[/small][br]##info##
}

L'argument principal est le nom du fichier à télécharger. L'option icon est le chemin vers une image

Les autres arguments concernent la mise en page :

• des classes pour centrer le contenu, ajouter un filet gris et un padding
• main-tag et item-tag remplace la liste par défaut par un bloc div
• template est la mise en page. Notez l'utilisation de bbcode

Si vous utilisez fréquement cette disposition, il est pratique de créer 🆙 créer un jeu d'options (prefset)

[pdf-image]
class = "tc grisClair p1"
main-tag="div"
item-tag=0
template="##icon-link##[br]##filename-link##[br](##size##)[br][small]##hit##[br]##lastdownload##[/small][br]##info##"

qui sera utilisé avec ce shortcode

{up file-download=demo/UP-unicode-top100.pdf
| icon=images/doc/UP-Memo-CSS.jpg
| prefset=pdf-image}

Saisie wysiwyg

Il est aussi possible de gérer le contenu entre le shortcode ouvrant et fermant. Cela peut-être plus facile dans certains cas.

J'ai surligné les shortcodes pour les mettre en évidence.

<p>{up file-download=demo/UP-unicode-top100.pdf 
<br>| class=tc bd-bleu | main-tag=div | item-tag=0}</p>
<p>##link##<img src="/images/actions-demo/image-logo/up-lego-300px.jpg" alt="" />##/link##</p>
<p>##filename-link##<br />(##size##)</p>
<p><small>##hit## <br />##lastdownload##</small></p>
<p>##info##</p>
<p>{/up file-download}</p>

Dans le fichier .info

S'il existe, dans le même sous-dossier, un fichier de même nom que celui en téléchargement avec une extension .info, ce fichier sera lu pour rechercher le texte explicatif pour le mot clé ##info## et l'image à utiliser dans icon. Si aucun chemin n'est précisé pour l'image, UP considère qu'elle se trouve dans le même dossier que le fichier téléchargé.

info="texte explicatif", balises HTML autorisées"
icon="images/mon_image.jpg"

Cette méthode est pratique pour afficher le contenu d'un dossier.

J'utilise ce procédé sur la page des téléchargements pour les fichiers 'documentation' en PDF. Cela évite de modifier l'article, tout est géré en FTP dans le sous-dossier. Pour information, voici les shortcodes

{up flexauto=4 | tablet=2 | class=fg-gap }
  {up file-download=doc
   | extensions=pdf
   | main-tag=0 | item-tag=div
   | item-class=bd-gris ombre tc p1
   | template=##icon-link##[br]##filename-link##[br](##size##)[br][small]##hit##[/small][br][i]##info##[/i]
  }
{/up flexauto}

• J'utilise l'action flexauto pour avoir une grille fluide sur 4 colonnes sur grand écran et 2 sur tablette
• Pour l'action file-download, je précise uniquement le sous-dossier de la documentation.
• Comme je ne veux pas récupérer les images du dossier, je limite les extensions au pdf
• A la place de la liste par défaut, je choisis un bloc div pour chaque fichier (item-tag)
• Les 2 dernières options servent à définir et styler la mise en page

Dorénavant, je n'ai plus besoin de revenir sur l'article pour ajouter ou supprimer des documentations. C'est automatique 😀

Attention si vous utilisez l'option password de cette action, je vous conseille de mettre les images dans un autre dossier que celui du fichier à télécharger et d'indiquer le chemin complet vers l'image dans le fichier info.

Avec des options

Comme à son habitude, UP propose des options pour personnaliser le rendu et les fonctionnalités

	up-dossier-technique.zip	26/09/2023 12:21
	listup-synthese-scss.pdf	26/09/2023 12:21
	icones-noel.zip	26/09/2023 12:21
	icones-halloween.zip	26/09/2023 12:21

La table ci-dessous est obtenue à l'aide de 2 actions UP.

• file-download : la mise en forme est spécifiée comme contenu. Chaque champ est séparé par un point-virgule comme attendu par l'action parente. On indique que l'on ne veut pas de balise.
• csv2table : récupère la sortie de file-download pour l'afficher avec le model blue. La justification et la largeur des colonnes sont indiquées dans l'option col

{up csv2table | model=blue | col=c5-80-15}
   {up file-download=doc | main-tag=0 | item-tag=0}##icon##;##filename-link##;##date##{/up file-download}
{/up csv2table}

Les options

file-download

le chemin et nom du fichier ou dossier à partir du dossier principal. Voir "Fichiers de configurations"

extensions

zip,pdf,txt,md,png,jpg,gif,svg,doc,docx,xls,xlsx,odt,ods; liste des extensions autorisées

Votre webmaster a la possibilité de resteindre ou d'étendre les extensions permises dans le fichier updownload.cfg

sort-order

desc ou asc : sens du tri alphanumérique.

password

mot de passe pour télécharger le fichier ou les fichiers d'un dossier

main-tag

Balise pour la liste des fichiers. UL par défaut. Indiquer 0 pour ne pas mettre le résultat dans un bloc

main-style

style

main-class

class

Classes et style pour la liste des fichiers. list-none par défaut.

item-tag

balise pour un bloc fichier. LI par défaut. Indiquer 0 pour ne pas mettre le résultat dans un bloc

item-style

item-class

style et classes pour un bloc fichier

link-style

style pour le lien (classes admises)

icon

chemin et nom de l'icone devant le lien ou taille de l'icone selon extension du fichier (16 ou 32). 32 par défaut

format-date

format des dates. Par défaut: d/m/Y H:i Il est possible de l'indiquer par l'action lang ou la méthode lang[en=m/d/Y H:i;fr=d/m/Y H:i]

model-hit

La mise en forme du nombre de téléchargements. Défaut : téléchargé %s fois

model-lastdownload

La mise en forme pour la date du dernier téléchargement. Défaut : dernier téléchargement le %s

model-info

La mise en forme pour les infos. Défaut : %s

id

L'identifiant unique pour l'action attribuée à la balise principale (main-tag). Inutilisé si main-tag=0

filter

Les conditions pour exécuter l'action. Exemple filter=!guest pour réserver le téléchargement aux enregistrés. Voir  🆙 Filter : liste des conditions

css-head

règles CSS définies par le webmaster (ajout dans le head)

template

Modèle de présentation composé de mots-clés et de 🆙 BB-Code by UP. Cette option est prévue pour être utilisée par le webmaster dans le fichier custom/prefs.ini pour fournir des jeux d'options :

• ##filename## : nom du fichier sans mention du chemin
• ##filename-link## : idem à filename avec un lien pour le télécharger
• ##link## : uniquement les attributs pour faire un lien de téléchargement. A utiliser sous la forme <a ##link##>##icon## ##filename##</a>
• ##info## : si un fichier "nom_fichier_a_telecharger.info" existe, le texte correspond à la clé "info"
• ##icon## : peut contenir (dans l'ordre de priorité)
  - une image (png, jpg ou gif) indiquée dans le fichier .info
  - une image png, jpg ou gif indiquée dans le shortcode
  - un sous-dossier de "up/assets/img/file" qui contient des images png du nom des extensions courantes. Les sous-dossiers de base de UP sont 16 et 32, ce qui correspond à la taille de l'icône. Vous pouvez ajouter vos sous-dossiers qui seront préservés lors des mises à jour.
• ##size## : taille du fichier
• ##date## : date du fichier
• ##lastdownload## : date du dernier téléchargement
• ##hit## : nombre de téléchargement

Template par défaut : {icon} {filename-link} ({size}) {date} [small]{hit} {lastdownload}[/small]{info}

Les fichiers de configuration

Certaines informations qui sont globales au site ne peuvent pas être définies par des options classiques.

Ce rôle est dévolu au fichier updownload.cfg que vous pouvez surcharger dans le sous-dossier custom de l'action. 🆙 Comment surcharger les fichiers de UP

root="files/"
logfile="1"
extensions="zip,pdf,txt,md,png,jpg,gif,svg,doc,docx,xls,xlsx,odt,ods"

• root définit le chemin relatif à la racine du site. Il est unique et non modifiable par d'autres options.
• logfile : 1 pour tenir un journal de tous les téléchargements, 0 pour avoir uniquement le nombre et la date de dernier téléchargement.
• extensions : liste des extensions autorisées.
  Il n'est pas possible d'autoriser des extensions dans le fichier prefs.ini ou dans le shortcode, si elles ne sont pas autorisées à ce niveau

Structure du dossier des téléchargements

Tous les fichiers proposés au téléchargement doivent être dans un dossier ou sous-dossier en racine du site. Par défaut, il s'agit du dossier 'files'. Vous pouvez en changer à l'aide du fichier updownload.cfg. Cela peut être judicieux pour masquer l'emplacement exact de vos fichiers. Ce répertoire ne sera pas visible dans le code source de la page web.

Vous pouvez créer des sous-dossiers pour classer vos fichiers par catégories. Dans chacun des dossiers contenant des fichiers proposés au téléchargement, un sous-dossier .log sera créé pour contenir les fichiers de suivi.

• nom_du_fichier.ext.stat : un petit fichier contenant le nombre et la date du dernier téléchargement
• nom_du_fichier.ext.log : les dates/heures et l'IP visiteur de tous les téléchargements. Cette option est désactivable dans le fichier updownload.cfg

N'oubliez pas de mettre un fichier index.html vide dans chaque dossier !

Suivi Update Joomla

Connaitre le nombre de demandes de mise à jour d'une extension est un indicateur précieux pour le développeur.
Plus que le nombre de primo-téléchargements, il indique le nombre de sites utilisant réellement l'extension.

Sa mise en oeuvre est indépendante de cette action.
Il est toutefois judicieux d'organiser la structure des répertoires pour une gestion commune. Je vais prendre la structure de UP comme exemple :

Les fichiers impliqués

Le manifest de votre extension

Aucune modification. Pour mémoire le code concerné est :

<version>1.7</version>
<update>24-12-2019</update>

<updateservers>
   <server type="extension" priority="1" name="UP - Universal Plugin">https://up.lomart.fr/files/plg_content_up_update.xml</server>
</updateservers>

le fichier files/plg_content_up_update.xml

Il contient l'appel au script pour le téléchargement du fichier zip. Surligné en jaune, les informations à modifier pour une nouvelle version

<updates>
   <update>
      <name>UP</name>
      <description>UP (Universal Plugin)</description>
      <element>up</element>
      <type>plugin</type>
      <folder>content</folder>
      <client>0</client>
      <version>1.7</version>
      <downloads>
            <downloadurl type="full" format="zip">https://up.lomart.fr/files/update.php?file=UP/plugin/plg_content_up-v1.7.zip</downloadurl>
      </downloads>
      <maintainer>LOMART</maintainer>
      <maintainerurl>http://up.lomart.fr</maintainerurl>
      <targetplatform name="joomla" version=".*"/>
   </update>
</updates>

update.php

A mettre dans le ou les dossiers contenant des manifests

• update.zip (1.04 ko - 26/09/2023 12:21) téléchargé 8 fois dernier téléchargement le 06/12/2023 06:01
  Ce script permet de comptabiliser les mises à jour d'une extension. Il faut le placer dans le dossier appelé par le manifest de votre extension