Comment ajouter un téléchargement de fichier

Téléchargements de fichiers

Vous pouvez ajouter une fonctionnalité de téléchargement de fichiers dans les plans Pages, Config, Plugins et Thèmes. Les téléchargements de fichiers sont toujours basés sur Ajax et permettent le glisser-déposer depuis le bureau ou de les sélectionner en tant que champs de fichiers normaux. Chaque fois qu'un fichier est ajouté au champ, il est automatiquement téléchargé dans un dossier temporaire et ne sera stocké que lorsque l'action Enregistrer (ou Soumettre) aura lieu.

Exemple d'utilisation :

1 | custom_file:
2 |      name: myfile
3 |      type: file
4 |      label: A Label
5 |      destination: 'plugins://my-plugin/assets'
6 |      multiple: true
7 |      autofocus: false
8 |      accept:
9 |            - image/*
Afin d'ajouter un téléchargement de fichier, vous devez avoir une commande de rendu javascript en bas dans votre modèle Twig de base. {{ assets.js('bottom') }}

Options

Un champ de fichier a plusieurs options disponibles, du type ou de l'extension MIME accepté à la taille de fichier autorisée :

Valeurs par défaut 

1  | custom_file:
2  |     type: file
3  |     label: A Label
4  |     multiple: false
5  |     destination: 'self@'
6  |     random_name: false
7  |     avoid_overwriting: false
8  |     limit: 10
9  |     accept:
10 |           - image/*

multiple 

multiple: false # [false | true]

Comme un champ de fichier HTML5 normal, lorsque l'option multiple est activée, elle permet de télécharger plus d'un seul fichier. Ce paramètre est également lié à l'option limit, qui détermine le nombre de fichiers multiples autorisés pour le champ.

destination 

destination: 'self@' # [<path> | <stream> | self@ | page@:<path>]

La destination est l'emplacement où les fichiers téléchargés doivent être stockés. Cela peut être soit un path normal (relatif à la racine de Grav), un stream (tel que theme://images), self@ ou le préfixe spécial page@: .

self@ n'est pas autorisé en dehors de la portée Pages ou Flex Objects, une erreur sera renvoyée. Si vous utilisez un champ de fichier en dehors d'une page ou d'un objet Flex, vous devez toujours modifier le paramètre de destination.

Exemples

  1. Si vous souhaitez télécharger des fichiers dans un dossier testing de plug-in (user/plugins/testing), la destination serait :
destination : 'plugins://testing'
  1. En supposant que nous ayons un article de blog sur la route /blog/ajax-upload (l'emplacement physique étant user/pages/02.blog/ajax-upload), avec le préfixe page@ : la destination serait :
destination : 'page@:/blog/ajax-upload'
  1. En supposant que le thème actuel est antimatter et que nous voulons télécharger dans le dossier assets (l'emplacement physique étant user/themes/antimatter/assets), avec le flux de thème, la destination serait :
destination : 'theme://assets'


random_name 

random_name: false # [false | true]

Lorsque le random_name est activé, le fichier téléchargé sera renommé avec une chaîne aléatoire de 15 caractères. Ceci est utile si vous souhaitez hacher vos fichiers téléchargés ou si vous cherchez un moyen de réduire les collisions de noms.

Exemple 

'my_file.jpg' => 'y5bqsGmE1plNTF2.jpg'


avoid_overwritting 

avoid_overwriting: false # [false | true]

Lorsque avoid_overwritting est activé et qu'un fichier portant le même nom que celui téléchargé existe déjà dans la destination, il sera renommé. Le fichier nouvellement téléchargé sera précédé de la date et de l'heure actuelles, concaténées par un tiret.

Exemple 

'my_file.jpg' => '20160901130509-my_file.jpg'


limit 

limit: 10 # [1...X | 0 (unlimited)]

Lorsque le paramètre multiple est activé, limit permet de restreindre le nombre de fichiers autorisés pour un champ individuel. Si multiple n'est pas activé (non activé par défaut), limit retombe automatiquement à 1.

Lorsque la limite est définie sur 0, cela signifie qu'il n'y a aucune restriction sur le nombre de fichiers autorisés pouvant être téléchargés.

Il est recommandé de toujours s'assurer que vous disposez d'une limite définie de fichiers autorisés pouvant être téléchargés. De cette façon, vous avez plus de contrôle sur l'utilisation des ressources de votre serveur.

accept 

1 | accept:
2 |      - 'image/*' # Array of MIME types and/or extensions. ['*'] for allowing any file. .

Le paramètre accept autorise un tableau de type MIME ainsi que des définitions d'extensions. Toutes les extensions doivent commencer par . (point) plus l'extension elle-même.

De plus, vous pouvez également autoriser n'importe quel fichier en utilisant simplement la notation * (étoile) accep : ['*'].

Exemple

1.Pour autoriser uniquement les fichiers yaml et json:

1 | accept:
2 |      - .yaml
3 |      - .json

2.Pour autoriser uniquement les images et les vidéos :

1 | accept:
2 |      - 'image/*'
3 |      - 'video/*'

3.Pour autoriser n'importe quelle image, n'importe quelle vidéo et uniquement les fichiers mp3 :

1 | accept:
2 |      - 'image/*'
3 |      - 'video/*'
4 |      - .mp3

4.Pour autoriser n'importe quel fichier :

1 | accept:
2 |      - '*'


filesize

La taille maximale du fichier est limitée par :

  1. filesize au niveau du champ :, puis ...

  2. Fichiers de configuration au niveau du plug-in de formulaire user/plugins/form.yaml : files: filesize: , alors si aucun de ceux-ci n'est limitatif...

  3. Configuration du niveau PHP pour upload_max_filesize pour les fichiers individuels qui sont téléchargés, et post_max_size pour la taille maximale de la publication du formulaire.

Exemple

1.Pour limiter un champ spécifique à 5M

1 | custom_file:
2 |      name: myfile
3 |      type: file
4 |      label: A Label
5 |      destination: 'plugins://my-plugin/assets'
6 |      filesize: 5
7 |      accept:
8 |            - image/*

2.Pour limiter tous les champs de fichier à 5 Mo, modifiez votre fichier user/config/form.yaml :

1 | files:
2 |      multiple: false
3 |      limit: 10
4 |      destination: 'self@'
5 |      avoid_overwriting: false
6 |      random_name: false
7 |      filesize: 5
8 |      accept:
9 |            - 'image/*