Accueil

Introduction

Le plugin Safer permet de fournir un ensemble de blocs à utiliser dans l'éditeur ainsi que diverses fonctionnalités utilisées par ceux-ci.

Le plugin se compose de deux parties interdépendantes :

  • Les blocs dans l'éditeur Gutenberg utilisant React pour leur interface.
  • Les blocs dans la page rendue et les fonctionnalités PHP associées.

Ces deux parties interagissent au moyen de WordPress :

  • Les blocs sont configurés dans l'éditeur au moyen de React et leurs attributs sont enregistrés sous forme textuelle dans la base de données.
  • Les blocs sont rendus dans la page au moyen de PHP et les attributs sont récupérés depuis la base de données.

Cela signifie qu'un bloc dynamique doit avoir à la fois une partie en React et une autre en PHP.

Par la suite :

  • {{nom}} : correspondra à une valeur dynamique.
    Exemple : Quelque chose de {{nom}} peut devenir Quelque chose de dynamique ou encore Quelque chose de variable.

Arborescence des fichiers

  • .vscode : contient les fichiers de configuration de l'éditeur de code Visual Studio Code.
  • bin : contient une archive PHP : WP-CLI).
  • build : contient les fichiers générés par Webpack.
    • blocks : équivalent de /src/blocks mais avec uniquement les fichiers block.json.
    • index.asset.php : fichier généré par Webpack pour enregistrer les dépendances des scripts.
    • index.css : fichier généré par Webpack, combinaison de tous les fichiers CSS des blocs.
    • index.css.map : fichier généré par Webpack dans un environnement de développement. Il contient la liste des fichiers CSS utilisés pour générer index.css ainsi que leur contenu.
    • index.js : fichier généré par Webpack, combinaison de tous les fichiers JS des blocs.
    • index.js.map : fichier généré par Webpack dans un environnement de développement. Il contient la liste des fichiers JS utilisés pour générer index.js ainsi que leur contenu.
    • map.json : fichier généré par un plugin Webpack pour permettre la création du fichier de traduction à destination des navigateurs.
  • languages : contient les fichiers de traduction du thème.
    • safer.pot : fichier de traduction du thème. Ce fichier contient l'emplacement de chaque chaine de caractère à traduire.
    • safer-fr_FR.po : fichier de traduction en français.
    • safer-fr_FR.mo : fichier de traduction en français.
    • make-pot.ps1 : script pour générer le fichier safer.pot.
    • make-json.ps1 : script pour générer le fichier de traduction à destination des navigateurs.
    • safer-fr_FR-{{id}}.json : fichier de traduction généré par le début du script make-json.ps1. Ce fichier n'est pas censé rester après la fin du script.
    • safer-fr_FR-safer_editor_script_{{id}}.json : fichier de traduction généré par le script make-json.ps1. Ce fichier est utilisé pour la traduction des blocs dans l'éditeur.
  • node_modules : contient les dépendances Node.js du projet.
  • src : contient les fichiers sources du thème.
    • admin : contient les fichiers pour l'interface administrateur du plugin.
      Pour plus d'informations : Pages d'administration - Documentation administrateur (saferducentre.com).
    • assets : contient les fichiers statiques du thème (images, css, js, ...).
      • css : contient les fichiers CSS.
        • handsontble.css : fichier CSS pour corriger un problème de superposition de popup dans l'éditeur.
        • wordpress.scss : contient des styles pour ajuster l'éditeur Gutenberg.
      • js : contient les fichiers JavaScript.
        • main.js : fichier JavaScript principal du plugin. Ce fichier est lié à toutes les pages (non admin) du site.
        • safer-echart.js : Contient la classe EChart. Cette classe permet de générer des graphiques avec la librairie ECharts.
      • json : contient les fichiers JSON.
        • datatables-i18n-french.json : fichier de traduction pour le plugin DataTables.
    • blocks : contient les blocs du plugin.
      • {{nom-du-group}} : contient les blocs du groupe {{nom-du-group}}.
        • {{nom-du-bloc}} : contient les fichiers du bloc {{nom-du-bloc}}.
          • block.json : fichier de configuration du bloc.
          • editor.scss : fichier de style du bloc dans l'éditeur.
          • index.js : fichier JavaScript du bloc.
          • edit.js : fichier JavaScript pour l'édition du bloc.
          • template.php : fichier de template pour le rendu du bloc.
          • block.php : point d'entrée PHP pour le bloc.
          • attributes.php : liste des attributs du bloc.
      • class-block.php : SaferBlock.
      • class-blocks.php : SaferBlocks.
    • components : contient les composants du plugin.
      • modals : contient les composants générant des fenêtres modales.
    • database : Contient tous les fichiers en rapport avec la base de données.
      • models : Contient des fichiers fournissant un ensemble de requêtes préparées.
      • queries : Fichiers de classes en rapport avec les différentes méthodes de requêtes.
      • class-dataset-manager.php : SaferDatasetManager. Cette classe permet de gérer les données des blocs.
      • class-dataset.php : SaferDataset. Cette classe permet de gérer les données d'un bloc.
      • connector.php : Database. Cette classe permet de se connecter à la base de données.
      • model.php : Model.
      • query.php : Query.
    • filters
    • formats
    • functions
    • helpers
    • middlewares
    • `routes
    • class-admin-menu.php
    • class-admin-submenu.php
    • class-context.php
    • class-functions.php
    • class-options.php
    • class-rest-route.php
    • class-rest.php
    • class-setting-field.php
    • class-setting-group.php
    • class-setting-section.php
    • class-settings.php
    • index.js
    • interface-singleton.php
  • .gitignore
  • package-lock.json
  • package.json
  • requirements.php
  • safer.php
  • webpack.config.js

Blocs

Création d'un bloc

Comme décrit dans l'arborescence des fichiers, un bloc est composé de plusieurs fichiers disposés dans un dossier portant le nom du bloc lui-même situé dans un dossier représentant le groupe de blocs.

Le fichier d'entrée du bloc est block.php. Il doit contenir une classe héritant de SaferBlock et dont le nom est formaté de la manière suivante : SaferBlock{{nom-du-groupe-avec-une-maj}}{{nom-du-bloc-avec-une-maj}}. Par exemple : SaferBlockSaferChart.

Exemple : 

<?php
require_once SAFER_PLUGIN_PATH . '/src/blocks/class-block.php';

class SaferBlockSaferChart extends SaferBlock {
}

La classe SaferBlock fournit différentes fonctionnalités pour personnaliser le bloc.

Les métadonnées

Les métadonnées d'un bloc sont définies dans un fichier block.json situé dans le dossier du dossier du bloc. 

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "{{groupe-du-bloc}}/{{nom-du-bloc}}",
	"version": "{{version-du-bloc}}",
	"title": "{{titre-du-bloc}}",
	"category": "{{groupe-du-bloc}}",
	"icon": "{{icône}}",
	"description": "{{description-du-bloc}}",
	"example": {},
	"supports": {
		"html": false
	},
	"textdomain": "safer"
}

Les attributs

Les attributs d'un bloc sont les paramètres que celui-ci recevra au moment de son rendu. Généralement, on construit une interface de configuration avec React dans Gutenberg pour permettre à l'utilisateur de définir ces attributs.

Les attributs des blocs dans le plugin sont définis dans un fichier attributes.php situé dans le dossier du bloc. Ce fichier retourne un tableau associatif dont les clés sont les noms des attributs et les valeurs sont :

  • type : le type de l'attribut.
  • default : la valeur par défaut de l'attribut.
  • required : si l'attribut est requis ou non.

Exemple : 

<?php
return [
    'title' => [
        'type' => 'string',
        'default' => 'Titre',
        'required' => true
    ],
    'content' => [
        'type' => 'string',
        'default' => 'Contenu',
        'required' => false
    ]
];

Dans le cas d'attributs communs à plusieurs blocs, il est possible de les définir dans le fichier /src/helpers/php/attributes.php et de les inclure dans les blocs concernés grâce à la méthode saferPluginAttributesHelpers::extends.

Édition du bloc

La déclaration du bloc dans l'éditeur Gutenberg se fait dans le fichier index.js situé dans le dossier du bloc.

Généralement, le fichier contient :

import { registerBlockType } from '@wordpress/blocks';

import Edit from './edit';
import metadata from './block.json';

registerBlockType(metadata.name, {
	icon: metadata.icon,
	category: metadata.category,
	keywords: metadata.keywords ?? [],
	supports: metadata.supports ?? {},

	edit: Edit
});

Ce fichier fait appel au fichier edit.js qui contient la logique de l'édition du bloc. Ce fichier doit retourner un composant React qui sera affiché dans l'éditeur Gutenberg.

Le fichier index.js est à importer dans le fichier /src/index.js.

Rendu du bloc

Le rendu du bloc se fait dans le fichier template.php situé dans le dossier du bloc. Ce fichier doit contenir une fonction nommée renderSaferBlock{{nom-du-groupe-avec-une-maj}}{{nom-du-bloc-avec-une-maj}} qui prend en paramètre un Dict des attributs du bloc ainsi que le contenu du bloc. Cette fonction doit retourner le contenu du bloc sous forme de chaine de caractères.

Exemple : 

<?php
function renderSaferBlockSaferCard($attributes, $content) {
    return "
    <div class=\"card\">
	    <h2>$attributes->title</h2>
        <div>$content</div>
	</div>
	";
}

Les blocs existants

Pour le détail des blocs existants, voir Accueil (saferducentre.com)

Contexte

Le contexte est un moyen de sauvegarder des données entre plusieurs pages. Le défaut de PHP, c'est que chaque requête est indépendante des autres. Le contexte permet contexte permet de stocker des données entre les requêtes. Pour ce faire, on utilise un paramètre dans l'url (context) qui permet de faire passer le contexte d'une page à l'autre.

Cela est possible grâce à la classe SaferContext.

Les données sont en réalité stockées dans la session PHP. Cela signifie que si l'utilisateur ferme son navigateur, les données sont perdues.

Le contexte met notamment à disposition un moyen de récupérer une instance de SaferDatasetManager, ce qui permet de conserver le résultat d'une requête entre plusieurs pages.

Routes API

Les routes API permettent de créer des points d'accès pour récupérer des données en utilisant la méthode REST de WordPress.

Les routes sont stockées dans le dossier routes et sont définies dans des fichiers PHP.

Ces fichiers doivent retourner une instance de la classe SaferRestRoute.

Composants

components
│ │ CodeEditor.js
│ │ DataSourceControl.js
│ │ FilterControl.js
│ │ FilterSummary.js
│ │ FormatControl.js
│ │ FunctionSelector.js
│ │ ServerSideRender.js
│ │ TablerIconsList.json
│ │ TablerIconsSelector.js
│ │ TabPanel.js
│ │ types.d.ts
│ │
│ └───modals
│ ConfirmModal.js
│ DataPreviewModal.js
│ FilterModal.js
│ MiddlewaresModal.js
│ OptionModal.js
│ PreviewModal.js
│ SQLModal.js
│ StaticDataModal.js

Interactive Graph
Table Of Contents
Accueil
Introduction
Arborescence des fichiers
Blocs
Création d'un bloc
Les métadonnées
Les attributs
Édition du bloc
Rendu du bloc
Les blocs existants
Contexte
Routes API
Composants