Blueprint

La structure de base de Flex Blueprint contient le title, la description et le type, qui décrivent le type et trois sections : config, blueprints et form, qui décrivent différents aspects du type de répertoire.

Structure principale de contacts.yaml :

title: Contacts
description: Simple contact directory with tags.
type: flex-objects  # do not change

# Flex Configuration
config: {}

# Flex Directory Forms
blueprints: {}

# Flex Object Form
form: {}

Pour créer votre propre répertoire personnalisé, vous devez commencer par nommer votre type (nom de fichier) et remplir le title et la description``.

Après avoir créé le fichier et rempli les informations de base, l'étape suivante consiste à copier votre formulaire existant ou à ajouter des champs dans le fichier.

Form.

Dans notre exemple de contacts, la section de formulaire ressemble à ceci :

# Flex Object Form
form:
   validation: loose

   fields:
      published:
         type: toggle
         label: Published
         highlight: 1
         default: 1
         options:
            1: PLUGIN_ADMIN.YES
            0: PLUGIN_ADMIN.NO
         validate:
            type: bool
            required: true

      last_name:
         type: text
         label: Last Name
         validate:
            required: true

      first_name:
         type: text
         label: First Name
         validate:
            required: true

      email:
         type: email
         label: Email Address
         validate:
            required: true

      website:
         type: url
         label: Website URL

      tags:
         type: selectize
         size: large
         label: Tags
         classes: fancy
         validate:
            type: commalist       

Le formulaire a le même aspect, qu'il provienne d'une page ou d'un fichier de configuration, de plug-in ou de thème. Il s'agit du plan directeur principal de chaque objet de votre répertoire et il doit contenir tous les champs définis dans l'objet. Considérez-le comme un formulaire qui s'affiche pour l'administrateur.

Nous n'avons pas encore tout à fait terminé. Il reste encore deux choses à faire pour que l'annuaire fonctionne : nous devons configurer la couche de stockage des données et définir les champs à afficher dans la vue Liste d'administration. Nous pouvons faire les deux dans la section config.

Config.

La section Config est la partie la plus compliquée de Flex Blueprint, bien qu'une grande partie ne soit destinée qu'à permettre la personnalisation. Il contient des sections data, admin et site.

# Flex Configuration
config:

   # Data Settings
   data: {}

   # Admin Settings
   admin: {}

   # Site Settings
   site: {}

La configuration minimale ressemble à ceci :

# Flex Configuration
config:

   # Data Settings
   data:
      storage: user-data://flex-objects/contacts.json

   # Admin Settings
   admin:
      # List view
      list:
         # List of fields to display
         fields:
            last_name:
               link: edit # Edit link
            first_name:
               link: edit # Edit link
            email:
            website:

Il existe deux sections obligatoires dans la configuration : config.data.storage et config.admin.list.fields. Ce dernier définit les champs affichés dans la vue de la liste d'administration. Le stockage des données, quant à lui, définit la manière dont les données seront stockées.

Config > Data.

Flex Directory est hautement personnalisable. Vous pouvez utiliser vos propres classes PHP object, collection et index pour ajouter votre propre comportement. De plus, vous pouvez configurer la couche storage pour répondre au mieux à vos besoins. Directory a également sa fonctionnalité ordering et search par défaut.

config:
   data:
      # Flex Object Class
      object: CLASSNAME
      # Flex Collection Class
      collection: CLASSNAME
      # Flex Index Class
      index: CLASSNAME
      # Storage Options
      storage: {}
      # Ordering Options
      ordering: {}
      # Search Options
      search: {}

L'objet, la collection et l'index prennent des noms de classe. S'ils ne sont pas fournis, Grav utilisera la configuration par défaut suivante :

config:
   data:
      object: 'Grav\Common\Flex\Types\Generic\GenericObject'
      collection: 'Grav\Common\Flex\Types\Generic\GenericCollection'
      index: 'Grav\Common\Flex\Types\Generic\GenericIndex'   

Ces classes définiront ensemble le comportement de votre type. Si vous souhaitez personnaliser votre propre type, c'est possible en étendant ces classes et en passant vos propres classes ici.

L'une des parties les plus importantes consiste à définir où et comment les données sont stockées :

config:
   data:
      storage:
         class: 'Grav\Framework\Flex\Storage\SimpleStorage'
         options:
            formatter:
               class: 'Grav\Framework\File\Formatter\JsonFormatter'
            folder: user-data://flex-objects/contacts.json   

Ci-dessus, un cas particulier qui peut aussi s'écrire sous une forme courte :

config:
   data:
      storage: user-data://flex-objects/contacts.json

Grav 1.7 propose 3 stratégies de stockage différentes, bien que vous puissiez facilement créer la vôtre :

De plus, vous pouvez fournir un format de fichier avec options.formatter.class :

Les options de configuration (avec les valeurs par défaut) pour les formateurs par défaut se trouvent ci-dessous dans les onglets :

- JSON

# JSON
  formatter:
    class: 'Grav\Framework\File\Formatter\JsonFormatter'
    options:
      file_extension: '.json'
      encode_options: '' # See https://www.php.net/manual/en/function.json-encode.php (separate options with space)
      decode_assoc: true # Decode objects as arrays
      decode_depth: 512  # Decode up to 512 levels
      decode_options: '' # See https://www.php.net/manual/en/function.json-decode.php (separate options with space)

- YAML

# YAML
formatter:
  class: 'Grav\Framework\File\Formatter\YamlFormatter'
  options:
    file_extension: '.yaml'
    inline: 5           # Save with up to 4 expanded levels
    indent: 2           # Indent with 2 spaces
    native: true        # Use native YAML decoder if available
    compat: true        # If YAML cannot be decoded, use compatibility mode (SLOW)

- Markdown

# Markdown
formatter:
  class: 'Grav\Framework\File\Formatter\MarkdownFormatter'
  options:
    file_extension: '.md'
    header: 'header'    # Header variable eg. header.title
    body: 'markdown'    # Body variable
    raw: 'frontmatter'  # RAW YAML variable
    yaml:
      inline: 20        # YAML options, see YAML formatter from above

- Serailize

# PHP Serialize
formatter:
   class: 'Grav\Framework\File\Formatter\SerializeFormatter'
   options:
      file_extension: '.ser'
      decode_options:
         allowed_classes: ['stdClass'] # List of allowed / safe classes during unserialize

- INI

# INI
formatter:
   class: 'Grav\Framework\File\Formatter\IniFormatter'
   options:
     file_extension: '.ini'

- CSV

# CSV
formatter:
   class: 'Grav\Framework\File\Formatter\CsvFormatter'
   options:
     file_extension: ['.csv', '.tsv']
     delimiter: ','      # Delimiter to separate the values
     mime: 'text/x-csv'  # MIME type for downloading file

Vous pouvez également définir l'ordre par défaut, qui est défini par la paire key: ASC|DESC :

config:
   data:
     # Ordering Options
     ordering:
        key: ASC
        timestamp: ASC

Enfin, vous pouvez ajouter des champs de recherche, qui sont consultés lorsque vous appelez collection.search() :

config:
   data:
      search:
         # Fields to be searched
         fields:
            - last_name
            - first_name
            - email
         # Search Options
         options:
            - contains: 1   # If field contains the search string, assign weight 1 to the object

Les Champs contiennent une liste de champs à rechercher.

Les options de recherche peuvent être :

La fonction de recherche renvoie 0 si le champ ne correspond pas et pondère entre 0 et 1 s'il y a une correspondance. Le poids est utilisé pour classer les résultats de la recherche. L'objet qui obtient le noyau le plus élevé a une meilleure correspondance que celui avec un score inférieur.

Config > Admin.

La section Admin contient diverses options de configuration pour personnaliser l'administration de l'annuaire. Il contient quelques sections principales : router, actions, permissions, menu, template et views.

config:
   # Admin Settings
   admin:
      # Admin router
      router: {}
      # Allowed admin actions
      actions: {}
      # Permissions
      permissions: {}
      # Admin menu
      menu: {}
      # Admin template type
      template: pages
      # Admin views
      views: {}

La section facultative router peut être utilisée pour personnaliser les routes d'administration de Flex Directory. Le routage prend en charge un chemin de base, des itinéraires personnalisables pour chaque action ainsi que des redirections pour gérer, par exemple, la rétrocompatibilité. Tous les chemins sont relatifs à l'URL de base de l'administrateur.

config:
   admin:
      # Admin router
      router:
         path: '/contacts' # Custom path to the directory
         actions:
            configure: # Action name
               path: '/contacts/configure' # New path to the action.
         redirects: # List of redirects (from: to)
            '/flex-objects/contacts': '/contacts'

Parfois, vous souhaitez restreindre l'administration pour n'afficher que les entrées ou, par exemple, pour autoriser uniquement la modification de celles existantes. Pour ces actions, vous pouvez modifier les opérations CRUD autorisées pour mieux répondre à vos besoins.

config:
   admin:
      # Allowed admin actions (for all users, including super user)
      actions:
         list: true   # Needs to be true (may change in the future)
         create: true # Set to false to disable creating new objects
         read: true   # Set to false to disable link to edit / details of the objects
         update: false # Set to false to disable saving existing objects
         delete: false # Set to false to disable deleting objects

L'exemple ci-dessus empêchera la sauvegarde des objets existants et leur suppression pour chaque utilisateur, y compris le super administrateur.

La section Autorisations vous permet d'ajouter de nouvelles règles d'autorisation pour Grav. Ces règles apparaîtront dans l'administration des utilisateurs/groupes. Vous pouvez créer autant de règles d'autorisation que vous le souhaitez, mais vous devez ajouter votre propre logique ou authorize les règles dans ce fichier pour les utiliser.

config:
   admin:
      # Permissions
      permissions:
         # Primary permissions (used for the objects)
         admin.contacts:
            type: crudl # Create, Read, Update, Delete, List
            label: Contacts Directory
         # Secondary permissions (you need to assign these to a view, otherwise these will not be used)
         admin.configuration.contacts:
            type: default # Simple permission
            label: Contacts Configuration

Si vous ne souhaitez pas afficher votre répertoire dans l'administration des Flex Objects, une option consiste à afficher l'élément de menu dans la navigation principale.

config:
   admin:
      # Admin Menu
      menu:
         list:
            hidden: false # If true, hide the menu item.
            route: '/contacts' # Alias to `config.admin.router.path` if router path is not set.
            title: Contacts
            icon: fa-address-card-o
            authorize: ['admin.contacts.list', 'admin.super'] # Authorization needed to access the menu item.
            priority: 2 # Priority -10 .. 10 (highest goes up)

L'exemple ci-dessus crée un élément de menu Contacts pointant vers /admin/contacts.

Lorsque vous créez vos propres répertoires Flex, vous souhaiterez peut-être parfois partager les mêmes modèles entre tous vos répertoires personnalisés. Vous pouvez le faire avec le template :

config:
   admin:
      # Admin template type (folder)
      template: contacts

Flex Admin dispose de plusieurs vues sur les objets. Par défaut, les vues suivantes sont prises en charge : list, edit, configure et éventuellement preview & export. Il est également possible d'ajouter vos propres vues.

config:
   admin:
      views:
         # List view
         list: {}
         # Edit view
         edit: {}
         # Configure view
         configure: {}
         # Preview
         preview: {}
         # Data Export
         export: {}

List View.

La première vue dont vous aurez besoin est celle qui répertorie tous vos objets. Par défaut, la vue list utilise VueTable et AJAX pour paginer les objets. Il a besoin d'une liste de fields à afficher ainsi que d'options pour définir le nombre d'articles à afficher en même temps ainsi que le champ par défaut utilisé pour la commande.

config:
   admin:
      views:
         # List view
         list:
            icon: fa-address-card-o
            title: Site Contacts
            fields: {}        # See below
            options:
               per_page: 20    # Default number of items per page
               order:
                  by: last_name # Default field used for ordering
                  dir: asc      # Default ordering direction

Icon et title sont utilisés pour personnaliser l'icône et le titre de la page de liste. Title prend également en charge l'utilisation du modèle Twig en utilisant le format suivant :

            title:
               template: "{{ 'PLUGIN_CONTACTS.CONTACTS_TITLE'|tu }}"

Fields contient les champs que vous souhaitez afficher dans la liste du répertoire. Chaque champ possède une clé, qui est le nom du champ. La valeur peut être omise ou contenir les options de configuration suivantes :

Edit View.

La vue Modifier possède les mêmes options de configuration de base que la vue Liste :

config:
   admin:
      views:
         # Edit view
         edit:
            icon: fa-address-card-o
            title:
               template: '{{ object.last_name ?? ''Last'' }}, {{ object.first_name ?? ''First Name'' }}'

Configure view.

La vue Configurer vous permet d'ajouter des options de configuration à l'échelle du répertoire, qui peuvent ensuite être utilisées dans les fichiers modèles.

config:
   admin:
      views:
      # Configure view
      configure:
         hidden: false # Configuration button can be hidden, for example if you have custom tab to replace it, like in Accounts.
         authorize: 'admin.configuration.contacts' # Optional custom authorize rule for this view.
         file: 'config://flex/contacts.yaml' # Optional file where the configuration is saved.

         icon: fa-cog
         title:
            template: "{{ directory.title }} {{ 'PLUGIN_ADMIN.CONFIGURATION'|tu }}"

Preview view.

Flex prend également en charge l'aperçu, bien qu'il fonctionne actuellement en restituant une page à partir du frontend, qui peut être définie dans le fichier de plan.

# Preview View
preview:
   enabled: true
   route:
      template: '/contacts' # Twig template to create URL. In this case we use the list view

      icon: fa-address-card-o
         title:
            template: "{{ object.form.getValue('title') ?? object.title ?? key }}"

Export view.

Tous les objets peuvent être exportés dans un seul fichier, voici un exemple de configuration pour exporter des données dans un fichier YAML :

# Data Export
export:
   enabled: true
   method: 'jsonSerialize'
   formatter:
      class: 'Grav\Framework\File\Formatter\YamlFormatter'
   filename: 'contacts'

Config > Site.

config:
   # Site Settings
   site:
      templates:
         collection:
            # Lookup for the template layout files for collections of objects
            paths:
               - 'flex/{TYPE}/collection/{LAYOUT}{EXT}'
         object:
            # Lookup for the template layout files for objects
            paths:
               - 'flex/{TYPE}/object/{LAYOUT}{EXT}'
         defaults:
            # Default template variable {TYPE}; overridden by filename of this blueprint if template folder exists
         type: contacts
         # Default template variable {LAYOUT}; can be overridden in render calls (usually Twig in templates)
         layout: default

Les paramètres du modèle vous permettent de personnaliser les chemins de recherche du modèle et de définir le type et le nom de mise en page par défaut dans l'interface.

Blueprints.

La section Blueprints définit les options de configuration communes pour l’ensemble du Répertoire. Les options vous permettent de personnaliser un répertoire commun pour mieux répondre aux besoins du site sans nécessiter une édition manuelle des fichiers.

blueprints:
   # Blueprint for configure view.
   configure:
      # We are inside TABS field.
      fields:
         # Add our own tab
         compatibility:
            type: tab
            title: Compatibility
            fields:
               # Fields should be prefixed with object, collection etc..
               object.compat.events:
                  type: toggle
                  toggleable: true
                  label: Admin event compatibility
                  help: Enables onAdminSave and onAdminAfterSave events for plugins
                  highlight: 1
                  default: 1
                  options:
                     1: PLUGIN_ADMIN.ENABLED
                     0: PLUGIN_ADMIN.DISABLED
                  validate:
                     type: bool