Référence : Champs de formulaire Blueprint

Champs de formulaire disponibles pour une utilisation dans l'administration

Les formulaires côté administrateur peuvent être créés avec une variété de champs. Ce document fournit une référence complète des propriétés de chaque champ et fournit des exemples d'utilisation.

En plus des champs listés ci-dessous, réservés à une utilisation dans l'Admin, vous pouvez également utiliser tous les champs disponibles dans les formulaires frontend décrits dans la Référence des champs des formulaires frontend.

Champs de formulaire spéciaux disponibles exclusivement dans l'administration

Attributs des champs communs

Chaque champ accepte une liste d'attributs que vous pouvez utiliser. Chaque champ peut partager ces attributs communs, mais des champs particuliers peuvent les ignorer. La meilleure façon de vérifier quels attributs sont autorisés sur un champ est de vérifier la description du champ dans cette page et de voir quels attributs sont mentionnés.

Cette liste fournit un terrain d'entente, il n'est donc pas nécessaire de répéter la description d'un champ commun.

En savoir plus sur les champs

Vous pouvez lire comment les champs sont construits à partir de la source : champs ajoutés par le plug-in de formulaire et champs uniquement disponibles dans Admin.

Validation

La plupart des champs permettent la validation.

1 | validate:
2 |   required: true

fera que le champ sera marqué comme requis.

1 | validate:
2 |   message: 'Some message'

affichera le message défini lorsque le champ n'est pas correctement rempli.

1 | validate:
2 |   pattern: 'Some pattern'

validera la valeur du champ par rapport au modèle regex passé. Exemples : Pattern : "[1-9][0-9]*", modèle : '[A-Za-z0-9-]+', modèle : '[a-z0-9-]+', modèle : '^[a-z0-9_-]{3,16}$', modèle : '(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8 ,}'

validate.type

validate.type indique le type par rapport auquel il doit être validé.

Quelques exemples:

Un éditeur se traduira par une textarea :

1 | content:
2 |    type: editor
3 |    validate:
4 |       type: textarea

Un selectize sera un commalist :

1  | taxonomies:
2  |    type: selectize
3  |    size: large
4  |    label: PLUGIN_ADMIN.TAXONOMY_TYPES
5  |    classes: fancy
6  |    help: PLUGIN_ADMIN.TAXONOMY_TYPES_HELP
7  |    validate:
8  |       type: commalist
9  |
10 | filters.category:
11 |    type: selectize
12 |    label: Category filter
13 |    help: Comma separated list of category names
14 |    validate:
15 |       type: commalist

Valider une adresse e-mail :

1 | author.email:
2 |    type: text
3 |    size: large
4 |    label: PLUGIN_ADMIN.DEFAULT_EMAIL
5 |    help: PLUGIN_ADMIN.DEFAULT_EMAIL_HELP
6 |    validate:
7 |       type: email

Assurez-vous qu'une valeur est un booléen :

1  | summary.enabled:
2  |    type: toggle
3  |    label: PLUGIN_ADMIN.ENABLED
4  |    highlight: 1
5  |    help: PLUGIN_ADMIN.ENABLED_HELP
6  |    options:
7  |        1: PLUGIN_ADMIN.YES
8  |        0: PLUGIN_ADMIN.NO
9  |     validate:
10 |        type: bool

Assurez-vous qu'une valeur est un entier compris entre 0 et 65536 :

1 | summary.size:
2 |     type: text
3 |     size: x-small
4 |     label: PLUGIN_ADMIN.SUMMARY_SIZE
5 |     help: PLUGIN_ADMIN.SUMMARY_SIZE_HELP
6 |     validate:
7 |        type: int
8 |        min: 0
9 |        max: 65536

Assurez-vous qu'une valeur est un nombre > 1 :

1 | pages.list.count:
2 |    type: text
3 |    size: x-small
4 |    label: PLUGIN_ADMIN.DEFAULT_PAGE_COUNT
5 |    help: PLUGIN_ADMIN.DEFAULT_PAGE_COUNT_HELP
6 |    validate:
7 |       type: number
8 |       min: 1

Validez un type de taxonomie en tant que tableau :

1 | header.taxonomy:
2 |    type: taxonomy
3 |    label: PLUGIN_ADMIN.TAXONOMY
4 |    multiple: true
6 |    validate:
7 |       type: array

Validez un champ de texte en tant que slug :

1 | folder:
2 |    type: text
3 |    label: PLUGIN_ADMIN.FOLDER_NAME
4 |    validate:
5 |       type: slug

Champ de tableau

Le type de champ attay est utilisé pour créer une simple liste d'objets clé-valeurs, ou simplement une liste de valeurs si vous utilisez l'option value_only.

Exemple:

1 | metadata:
2 |   type: array
3 |   label: PLUGIN_ADMIN.METADATA
4 |   help: PLUGIN_ADMIN.METADATA_HELP
5 |   placeholder_key: PLUGIN_ADMIN.METADATA_KEY
6 |   placeholder_value: PLUGIN_ADMIN.METADATA_VALUE
7 |   required: true

Champ de sélecteur de couleurs

Le type de champ colorpicker est utilisé pour afficher un champ color picker

Exemple:

1 | color:
2 |   type: colorpicker
3 |   label: Choose a color
4 |   default: '"FFFFFF'

Colonnes / Champs de colonne

Les columns et les types de champ column sont utilisés pour diviser les champs de formulaire contenus en colonnes

Exemple:

1  | columns:
2  |     type: columns
3  |     fields:
4  |        column1:
5  |           type: column
6  |           fields:
7  | 
8  |           # .... subfields
9  | 
10 |        column2:
11 |           type: column
12 |           fields:
13 |
14 |           # .... other subfields

Champ de format de date

Le type de champ dateformat est utilisé pour

Exemple:

1  | pages.dateformat.short:
2  |     type: dateformat
3  |     size: medium
4  |     classes: fancy
5  |     label: PLUGIN_ADMIN.SHORT_DATE_FORMAT
6  |     help: PLUGIN_ADMIN.SHORT_DATE_FORMAT_HELP
7  |     default: "jS M Y"
8  |     options:
9  |        "F jS \\a\\t g:ia": Date1
10 |        "l jS \\of F g:i A": Date2
11 |        "D, d M Y G:i:s": Date3
12 |        "d-m-y G:i": Date4
13 |        "jS M Y": Date5

Champ de date

The datetime field type is used to store and present a date and time field.

Example:

1 | header.date:
2 |   type: datetime
3 |   label: PLUGIN_ADMIN.DATE
4 |   toggleable: true
5 |   help: PLUGIN_ADMIN.DATE_HELP

Champ de l'éditeur

Le type de champ editor est utilisé pour présenter l'éditeur Codemirror

Exemple:

1  | frontmatter:
2  |     classes: frontmatter
3  |     type: editor
4  |     label: PLUGIN_ADMIN.FRONTMATTER
5  |     autofocus: true
6  |     codemirror:
7  |        mode: 'yaml'
8  |        indentUnit: 4
9  |        autofocus: true
10 |        indentWithTabs: false
11 |        lineNumbers: true
12 |        styleActiveLine: true
13 |        gutters: ['CodeMirror-lint-markers']
14 |        lint: true

Champ d'éléments

Ce champ est uniquement organisationnel et permet de regrouper des éléments au sein d'un groupe nommé qui ne sera affiché que si la valeur de l'élément sélectionné correspond au groupe.

Exemple:

1  | header.elements-demo.type:
2  |     type: elements
3  |     label: 'Elements Demo'
4  |     size: small
5  |     default: gelato
6  |     options:
7  |        gelato: Gelato Flavors
8  |        color: Color
9  |        planets: Planets
10 |     fields:
11 |        gelato:
12 |           type: element
13 |           fields:
14 |              .flavours:
15 |                 type: array
16 |                 default:
17 |                    pistacchio: Pistacchio
18 |                    vanilla: Vanilla
19 |                    chocolate: Chocolate
20 |                    stracciatella: Stracciatella
21 |        color:
22 |           type: element
23 |           fields:
24 |              .description:
25 |                 type: textarea
26 |                 rows: 10
27 |                 default: Color (American English) or colour (Commonwealth English) is the  
   | visual perceptual property corresponding in humans to the categories called blue, green,  
   | red, etc. Color derives from the spectrum of light (distribution of light power versus  
   | wavelength) interacting in the eye with the spectral sensitivities of the light receptors.  
   | Color categories and physical specifications of color are also associated with objects  
   | or materials based on their physical properties such as light absorption, reflection,  
   | or emission spectra. By defining a color space colors can be identified numerically by  
   | their coordinates.
28 |     planets:
29 |        type: element
30 |        fields:
31 |           .favorites:
32 |              type: text
33 |              placeholder: What are your favorite planets?
34 |              markdown: true
35 |              description: 'Find a list of planets from [Wikipedia](https://en.wikipedia  
   | .org/wiki/Planet)'

Champ d'ensemble de champs

The champs fieldset regroupe un ensemble de champs à l'intérieur d'une boîte réductible.

Exemple:

1  | header.fieldset:
2  |     type: fieldset
3  |     title: Your title
4  |     help: Help text
5  |     info: Info text
6  |     text: Text inside fieldset and before other fields
7  |     icon: comments       # Fork Awesome icons system (see : forkaweso.me).
8  |     collapsed: true      # Initial state of fieldset (see collapsible option)
9  |     collapsible: true    # Whether one can expand the fieldset or not
10 |     fields:
11 |        header.fieldset.an_example_text:
12 |           type: text
13 |           label: text
14 |        header.fieldset.an_example_textarea:
15 |           type: textarea
16 |           label: textarea

Les ensembles de champs doivent également être enregistrés dans le frontmatter, avec header, afin que leurs états de sous-champ soient correctement mémorisés !

1  | header.fieldset:
2  |      type: fieldset
3  |     ... etc...
4  |     fields:
5  |        header.content.pagination:
6  |           type: toggle
7  |           toggleable: true
8  |           label: "Activate Pagination ?"
9  |           highlight: 1
10 |           default: 0
11 |           options:
12 |              1: Yes
13 |              0: No
14 |           validate:
15 |              type: bool

Icône du jeu de champs

Vous pouvez utiliser une icône à placer dans l'en-tête de l'ensemble de champs. Le système d'icônes utilisé est Fork Awesome.

Champ de fichier

Exemple:

1 | custom_logo_login_screen:
2 |      type: file
3 |      label: Custom Logo Login Screen
4 |      destination: 'plugins://admin/assets'
5 |      accept:
6 |         - image/*

1 | custom_file:
2 |      type: file
3 |      label: A Label
4 |      destination: 'theme://assets'
5 |      multiple: true
6 |      limit: 5
7 |      filesize: 1
8 |      accept:
9 |      - image/*

Champ de sélecteur de fichiers

Le type de champ filepicker peut être utilisé dans les configurations de pages, de plugins et de thèmes (blueprints). Gère la sélection d'un fichier à partir d'un emplacement et l'enregistre dans les en-têtes de page ou la configuration du thème/plug-in.

Exemple:

1 | picked_image:
2 |      type: filepicker
3 |      folder: 'theme://images/pages'
4 |      label: Select a file
5 |      preview_images: true
6 |      accept:
7 |         - .png
8 |         - .jpg

1 | header.a_file :
2 |      type : sélecteur de fichiers
3 |      dossier : 'self@'
4 |      preview_images : vrai
5 |      label : sélectionnez un fichier

Champ de pot de miel

Le type de champ honeypot crée un champ caché qui, une fois rempli, renverra une erreur. C'est un moyen utile d'empêcher les robots de remplir et de soumettre un formulaire.

Exemple:

1 | fields:
2 |      - name: honeypot
3 |      type: honeypot

Il s'agit d'un simple champ de texte qui n'apparaît pas sur le front-end. Les robots, qui détectent les champs dans le code et les remplissent automatiquement, rempliront probablement le champ. L'erreur empêche ce formulaire d'être correctement soumis. L'erreur revient à côté de l'élément de formulaire, plutôt qu'en haut dans un bloc de message.

Un champ de pot de miel est une alternative populaire aux champs de captcha. Champ de liste

Champ de liste

Le type de champ list est utilisé pour créer des collections de champs. Le champ accepte un attribut de fields qui hébergera des sous-champs, et il y aura un bouton "Ajouter un élément" pour permettre à l'utilisateur d'ajouter plus d'éléments à la collection.

Exemple:

1  | header.buttons:
2  |     name: buttons
3  |     type: list
4  |     style: vertical
5  |     label: Buttons
6  |     fields:
7  |        .text:
8  |           type: text
9  |           label: Text
10 |        .url:
11 |           type: text
12 |           label: URL
13 |        .primary:
14 |           type: toggle
15 |           label: Primary
16 |           highlight: 1
17 |           default: 1
18 |           options:
19 |              1: 'Yes'
20 |              0: 'No'
21 |           validate:
22 |              type: bool

Cet exemple générera cette interface d'administration :

Lors de l'enregistrement de la page, nous verrons le YAML suivant ajouté au frontmatter de la page :

1 | buttons:
2 |      -
3 |         text: 'Some text'
4 |         url: 'https://getgrav.org'
5 |         primary: false
6 |      -
7 |         text: 'Another text'
8 |         url: 'https://another-url.com'
9 |         primary: true

Cela sera utilisé dans le thème Twig pour afficher la liste d'une manière agréable.

Un autre exemple de cette définition de champ est cette liste de fonctionnalités, utilisée par la page enfant modulaire des fonctionnalités d'Antimatière. Chaque fonctionnalité a une icône, un en-tête et du texte :

1  | header.features:
2  |     name: features
3  |     type: list
4  |     label: Features
5  | 
6  |     fields:
7  |        .icon:
8  |           type: text
9  |           label: Icon
10 |        .header:
11 |           type: text
12 |           label: Header
13 |        .text:
14 |           type: text
15 |           label: Text

L'accès et l'affichage des données d'un champ list se fait avec une simple boucle for twig, comme dans l'exemple ci-dessous :

1 | {% for feature in page.header.features %}
2 |      {{ feature.icon }}
3 |      {{ feature.header }}
4 |      {{ feature.text }}
5 | {% endfor %}

Champ PageMediaSelect

Le type de champ pagemediaselect est utilisé pour permettre aux utilisateurs de choisir un média parmi l'un des médias de la page déjà téléchargé via FTP ou à l'aide du gestionnaire de médias de la page.

Exemple

1 | header.img_link:
2 |      label: Choose media
3 |      type: pagemediaselect

Champ Pages

Le type de champ pages affiche une liste des pages du site.

Exemple

1  | home.alias:
2  |     type: pages
3  |     size: medium
4  |     classes: fancy
5  |     label: PLUGIN_ADMIN.HOME_PAGE
6  |     start_route: '/some_page'
7  |      show_all: false
8  |     show_modular: false
9  |     show_root: false
10 |     help: PLUGIN_ADMIN.HOME_PAGE_HELP

Si vous définissez multiple sur true, vous devez ajouter validate.type: array. Sinon, le tableau des pages sélectionnées ne sera pas enregistré correctement.

Champ de section

Le type de champ Section est utilisé pour diviser une page de paramètres en sections.

Exemple:

1 | content:
2 |      type: section
3 |      title: PLUGIN_ADMIN.DEFAULTS
4 |      underline: true
5 | 
6 |      fields:
7 | 
8 |         #..... subfields

Champ de sélection

Le type de champ selectize est utilisé pour afficher un hybride d'une zone de texte et d'une zone de sélection. Principalement utile pour le balisage et d'autres champs de sélection d'éléments.

Exemple:

1  | taxonomies:
2  |     type: selectize
3  |     selectize:
4  |        options:
5  |           - text: "test"
6  |              value: "real value 1"
7  |           - text: "test-2"
8  |              value: "real value 2"
9  |           - text: "test-3"
10 |              value: "real value 3"
11 |     size: large
12 |     label: PLUGIN_ADMIN.TAXONOMY_TYPES
13 |     classes: fancy
14 |     help: PLUGIN_ADMIN.TAXONOMY_TYPES_HELP
15 |     validate:
16 |        type: commalist

Champ de taxonomie

Le type de champ taxonomy est une sélection spéciale préconfigurée pour sélectionner une ou plusieurs valeurs de taxonomie.

Exemple:

1 | header.taxonomy:
2 |   type: taxonomy
3 |   label: PLUGIN_ADMIN.TAXONOMY
4 |   multiple: true
5 |   validate:
6 |      type: array