file-explorer

Explorer un dossier et ses sous-dossiers avec prévisualisation et téléchargement.

Un exemple simple

{up file-explorer=images/actions-demo/file-explorer/test}

Les fichiers affichés

Les extensions reconnues

Sans ajouter d'options, seuls les fichiers dont l'extension est autorisée par l'action figurent dans la liste.

Il est possible de définir la liste des extensions reconnues avec les options :

• ext-image : tous les formats d'images
• ext-pdf : fichier traité par l'action pdf du UP
• ext-office : fichier traité par l'outil view.officeapps.live.com. Le serveur doit être accessible d'Internet
• ext-audio : lecteur audio HTML5
• ext-video : lecteur vidéo
• ext-ajax : tous les fichiers lisibles par le navigateur
• ext-download-only : pour les fichiers non visualisables proposés en téléchargement
• ext-none : pour les fichiers non visualisables et non disponibles au téléchargement

L'argument est la liste des extensions séparée par des virgules. Si la liste commence par le signe +, les extensions seront ajoutées à celles par défaut.
La reconnaissance des extensions n'est pas sensible aux minuscules/majuscules

Le but de cette action étant de proposer des fichiers au téléchargement, il est impossible de l'interdire pour un fichier visualisable. 

L'option view-unknow-ext permet d'afficher tous les fichiers du dossier. Les fichiers avec une extension inconnue sont affichés sans visualisation, ni téléchargement. 

Filtrer les fichiers

Tous les fichiers du dossier indiqué dans l'option principale file-explorer seront listés sous réserve que leur extension soit connue ou que l'option view-unknow-ext soit spécifiée.

Il est possible d'indiquer le niveau d'exploration des sous-dossiers avec l'option folder-recursive. L'argument est un entier. 
Par défaut, la présentation est sous la forme d'une liste UL/LI. L'option view-root  permet de montrer le dossier origine (l'argument de file-explorer).

L'option mask permet de restreindre la liste des fichiers. Elle reprend la syntaxe de la fonction glob de PHP.

Pour permettre sa saisie dans le shortcode, les accolades doivent être remplacées par des crochets. 
Exemple uniquement les fichiers avec l'extension jpg et jpeg : mask=*.[jpg,jpeg]

Pour saisir un crochet, il faut l'échapper avec un antislash. 
Exemple les fichiers pdf dont le nom commence par un a : mask=\[aA\]*.pdf

L'option file-exclude est la liste séparée par des virgules des fichiers à ne jamais afficher.

La mise en forme

Les options main-tag et item-tag  sont les balises pour le bloc principal et les différentes lignes.
Par défaut, la présentation est faite sous la forme d'une liste ul/li.

Le template

Comme à son habitude, UP utilise un système de template et mots-clés pour mettre en forme le résultat. 

l'option template pour les fichiers et template-folder pour les dossiers.

L'argument est une chaine HTML en BBCode qui utilise les mots-clés suivants :

Pour les fichiers 

• ##file## : chemin/nom.extension - pour copier/coller comme argument shortcode
  
• ##dirname## : chemin (sans slash final)
  
• ##basename## : nom et extension
  
• ##filename## : nom sans extension (sans le point)
  
• ##extension## : extension (sans le point)
  
• ##relpath## : chemin relatif au chemin passé comme principal argument
  
• ##size## : taille du fichier. Voir l'option size-decimal
  
• ##date## : date dernière modification. Voir l'option date-format
  
• ##icon## : icône ou vignette du fichier. Voir les options icon-thumbnail, icon-size et icon-path
  
• ##download## : bouton pour télécharger
  
• ##view-btn## : bouton pour voir le fichier dans une fenêtre modale
  
• ##view## & ##/view## : balise a (ouvrante et fermante) avec attributs pour voir le fichier dans une fenêtre modale

Par défaut : ##icon## ##basename## ##view-btn## ##download##

Pour visualiser le contenu en cliquant sur l'icône et le nom : ##view## ##icon## ##basename## ##/view## ##view-btn## ##download##

Pour les sous-dossiers

• ##foldername## : nom du dossier (sans l'arborescence)
  
• ##folderpath## : chemin et nom du dossier (avec l'arborescence)

Par défaut : [b]##foldername##[/b]

Le mot-clé ##icon##

3 options définissent le contenu pour le mot-clé ##icon## :

• icon-thumbnail : pour les fichiers de type 'image', une valeur de 1 (par défaut) affiche l'image sous forme de vignette. 0 affiche une icône selon l'extension du fichier
  
• icon-size : 3 tailles pour les icônes ou vignette sont disponibles 16, 32 et 48 px
• icon-path : le chemin vers vos fichiers icônes. ce dossier doit contenir 3 sous-dossiers 16,32 et 48

Les icônes représentatives des extensions de fichiers sont dans les 3 sous-dossier (16,32,48) du dossier /plugins/content/up/assets/img/file

Vous pouvez ajouter des icônes pour les extensions absentes. Elles seront conservées lors des mises à jour, tant qu'une version de Up ne les propose. 
La méthode la plus sûre est d'utiliser vos propres icônes dans un dossier dont vous informez UP à l'aide de l'option icon-path

Dans le cas où aucune icône n'est disponible, UP utilise une icône représentative du type (ajax, audio, download-only, iframe, image, none, office, pdf, video) dans un des dossiers de /plugins/content/up/actions/file_explorer/img 

Les mots-clés ##view-btn## et ##view## ... ##/view##

2 méthodes permettent de visualiser le contenu d'un fichier :

##view-btn##

Affiche le contenu de l'option view-label. Celui-ci peut être un texte ou du bbcode. Quelques exemples :

view-label=Voir
view-label=&#x1F441
view-label=[img src='path/to/image.png']

L'option view-style vous permet d'ajouter des classes et des styles pour habiller le bouton.
Exemple : view-style=btn;color:red

##view## et ##/view##

Ces 2 mots-clés (balise ouvrante et fermante) permettent de mettre un lien pour la prévisualisation sur un ou plusieurs autres mots-clés.

Exemple : ##view## ##icon## ##basename## ##/view## ##view-btn## ##download##

Autres options

id, class, style : pour le bloc principal (main-tag)

css-head : style ajouté dans le HEAD de la page

js-params : règles JS définies par le webmaster. Voir la documentation du script rbox
Exemple : supprimer le bouton fermer de la fenêtre modale et modifier la couleur de l'overlay
js-params='closebtn':false,'bgcustom':'rgba(20, 0, 0, 0.9)'
Ces règles s'appliquent à toutes les instances de l'action sur la page.

Exemple de présentation

Une méthode efficace pour montrer l'arborescence des dossiers est d'utiliser l'action treeview comme ceci :

{up treeview
  | icon-folder=folder-red
}
{up file-explorer=images/actions-demo/file-explorer
 | icon-size=16
 | main-tag=ul
 | folder-recursive=9
 | template=##view## ##icon## ##basename## (##date## - ##size##) ##/view## ##view-btn## ##download## 
}
{/up treeview}

Un autre exemple que j'utilise dans la démo de media-audio

audio-default.webp 👁 📥

credits.md 👁 📥

funky.info 👁 📥

funky.mp3 👁 📥

funky.ogg 👁 📥

funky.webp 👁 📥

funny-kids.jpg 👁 📥

funny-kids.mp3 👁 📥

happy-santa.jpg 👁 📥

happy-santa.mp3 👁 📥

happy-santa.ogg 👁 📥

joyful-snowman.mp3 👁 📥

joyful-snowman.webp 👁 📥

merry-christmas.mp3 👁 📥

minimal-tech-ambient.mp3 👁 📥

minimal-tech-ambient.ogg 👁 📥

science-of-trip-hop.jpg 👁 📥

science-of-trip-hop.mp3 👁 📥

{up file-explorer=images/audio
 | ext-ajax=+md,info
 | main-tag=div
 | icon-size=16}

1/le chemin vers les fichiers

2/ par défaut, les fichiers .md et .info ne sont par pris en charge par l'action. Le signe + au début ajoute leurs extensions aux existantes. Comme il s'agit de fichier au format texte, ils seront ouverts en ajax.

3/ comme ce dossier ne possède pas de sous-dossier, je remplace la vue liste par des blocs simples

4/ toutes les icônes et photos seront affichées en 16x16 pixels

Astuce

Si vous voulez que vos utilisateurs disposent d'un dossier sur votre site, il suffit d'utiliser une combinaison de shortcodes comme ceci :

{up file-explorer=files/users/{up php=$user=JFactory::getUser();echo ($user->guest!=1) ? $user->id.'_'.$user->username : 'guest';}}

Le nom du dossier est composé de l'ID et de l'username pour éviter de l'imaginer trop facilement.

L'accès à l'article avec les shortcodes peut-être limité aux utilisateurs enregistrés. Sauf si vous proposez un dossier pour les visiteurs qui aurait comme nom "guest" ou celui indiqué dans le shortcode php.

Si un dossier n'existe pas, on affiche rien. 

Je vous laisse imaginer l'usage que vous pouvez en faire. 

Il me reste à créer une action pour uploader des fichiers 😉