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

➠ file_download : Gestionnaire simple de téléchargements avec stats et protection par mot de passe

Cliquer pour lire la documentation

syntaxe 1 {up file-download=dossier ou fichier}
syntaxe 2 {up file-download=dossier ou fichier}##icon## ##filename-link##{/up file-download}
présentation des liens :
##link## ##/link## ##filename-link## ##filename## ##icon## ##icon-link##
##hit## ##lastdownload##
##info## ##size## ##date##
author LOMART version 1.0 license GNU/GPLv3
  • file_download: fichier ou dossier
  • extensions = zip, pdf,txt,md,png,jpg,gif,svg,doc,docx,xls,xlsx,odt,ods: extensions autorisées
  • sort-by = name: TODO ou date-desc
  • template = ##icon## ##filename-link## (##size## - ##date##) [small]##hit## ##lastdownload##[/small] [br]##info##: modèle de mise en page. keywords + bbcode
  • main-tag = ul: balise pour la liste des fichiers
  • main-style: style pour la liste des fichiers
  • main-class = list-none: classes pour la liste des fichiers
  • item-tag = li: balise pour un bloc fichier
  • item-style: style pour un bloc fichier
  • item-class: classes pour un bloc fichier
  • link-style: style pour le lien (classes admises)
  • icon = 32: chemin et nom de l'icone devant le lien ou taille de l'icone selon extension du fichier (16 ou 32)
  • password: mot de passe pour télécharger le fichier
  • format-date = lang[en=m/d/Y H:i;fr=d/m/Y H:i]: 'd/m/Y H:i'
  • model-hit = téléchargé %s fois:
  • model-lastdownload = dernier téléchargement le %s:
  • model-info = %s:
  • class: classe(s) pour bloc
  • style: style inline pour bloc
  • filter:
  • css-head (base-css): règles CSS définies par le webmaster (ajout dans le head)

    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.

    La méthode simple

    Un fichier unique

    • plg_content_up-v1.0.zip (154.85 ko - 31/05/2020 15:12) téléchargé 15 fois dernier téléchargement le 15/05/2020 18:51

    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-unicode-top100.pdf (233.49 ko - 31/05/2020 15:13) téléchargé 10 fois dernier téléchargement le 10/05/2020 18:28
    • demo.md (62 o - 31/05/2020 15:13) téléchargé 6 fois dernier téléchargement le 19/04/2020 23:15
    • demo.txt (27 o - 31/05/2020 15:13) téléchargé 3 fois dernier téléchargement le 01/05/2020 15:25
    • lion.png (216.64 ko - 31/05/2020 15:13) téléchargé 5 fois dernier téléchargement le 21/04/2020 21:12
    • up-dossier-technique.zip (2.96 ko - 31/05/2020 15:13) téléchargé 3 fois dernier téléchargement le 19/04/2020 23:30
      Ceci est un texte explicatif trouvé dans le fichier up-dossier-technique.zip.info situé dans le même dossier.

    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.
      zip,pdf,txt,md,png,jpg,gif,svg,doc,docx,xls,xlsx,odt,ods
    • Il est possible d'avoir un texte explicatif en créeant un fichier HTML de même nom en ajoutant l'extension ".info"
      Exemple : pour le fichier up-dossier-technique.zip, les informations sont trouvées dans le fichier  up-dossier-technique.zip.info

    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 - 31/05/2020 15:12) téléchargé 15 fois dernier téléchargement le 15/05/2020 18:51

    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.

    On ne peut guère faire plus simple. L'ajout et la suppression des fichiers et dossiers sont réalisés en FTP.

    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.file-download : Fichier non trouvé : doc/UP-Memo-CSS.pdf 
    {up file-download=doc/UP-Memo-CSS.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 un jeu d'options

    [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=doc/UP-Memo-CSS.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.

    Le résultat

    ➜ UP.file-download : Fichier non trouvé : doc/UP-Memo-CSS.pdf 

    copie d'écran de la saisie sous TinyMCE

    idem en vue code

    <p>{up file-download=doc/UP-Memo-CSS.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

    icones-halloween.zip 31/05/2020 15:13
    icones-noel.zip 31/05/2020 15:13
    up-dossier-technique.zip 31/05/2020 15:13

    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

    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
    li', // balise pour un bloc fichier

    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 dans les options courantes

    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 bbcode . 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. PLUS D'INFO

    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.
    • 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

    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 :

    • files : le dossier racine
      • plg_content_up_update.xml : le(s) manifest(s) pour l'update Joomla!
      • update.php : le script appelé par le manifest. j'aurais pu le nommer 'upupdate.php' 😀
      • plg_content_up-v1.7.zip : le fichier à télécharger pour la mise à jour.
        Egalement accessible par {up file-download} 1
      • docs : un dossier pour contenir la documentation
      • up-old : les anciennes versions du plugin.
        Il suffira d'un shortcode {up file-download=up-old} pour donner l'accès aux anciennes versions

    1 il est inutile de préciser son nom puisqu'il est l'unique fichier zip du dossier. Cela veut dire qu'il n'est pas nécessaire de mettre à jour les articles qui donnent accès à la dernière version. La mise à disposition d'une nouvelle version se limite à mettre la nouvelle version en racine et à déplacer l'ancienne (et ses logs) dans le sous-dossier "up-old". Il faut bien sûr, mettre à jour le fichier "votre_extension_update.xml"

    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 - 31/05/2020 15:13) téléchargé 7 fois dernier téléchargement le 16/04/2020 18:09
      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