Créer des champs extras depuis un plugin perso avec l’aide de Saisies

Note : n’oubliez pas de remplacer prefixe par le préfixe de votre plugin.

Créer la fonction qui va déclarer les nouveaux champs

Dans cette première partie, on ajoute simplement un champ date aux articles du secteur 1 et un champ textarea aux rubriques de la branche 5. Pour voir d’autres types de champs, rendez-vous dans la partie Déclarer d’autres types de champs extras.

Créer un fichier /base/prefixe.php contenant le code suivant :

<?php

// Sécurité
if (!defined("_ECRIRE_INC_VERSION")) return;

function prefixe_declarer_champs_extras($champs = array()) {

    // SAISIE DATE SUR L'OBJET ARTICLE DU SECTEUR 1
    $champs['spip_articles']['date_diffusion'] = array(
        // Le type de saisie
        'saisie' => 'date',
        'options' => array(
            // Le nom du champ dans la base de données
            'nom' => 'date_diffusion', 
            // Le label affiché dans l'espace privé du site
            'label' => _T('prefixe:chaine_de_langue_date_diffusion'),
            // L'explication affichée dans l'espace privé du site
            'explication' => _T('prefixe:chaine_de_langue_date_diffusion_explication'),
            // Le type d'info attendue
            'sql' => "datetime DEFAULT '0000-00-00 00:00:00' NOT NULL",
            // La valeur par défaut
            'defaut' => '',
            // Le champ est obligatoire
            'obligatoire' => 'oui',
            // Afficher ce champ uniquement pour les articles du secteur n°1
            'restrictions'=>array(
                        'secteur' => '1'
            ),
       ),
        // Vérifier et normaliser les infos saisies avant de les insérer dans la base
        'verifier' => array(
            'type' => 'date',
            'options' => array(
                'normaliser' => 'datetime',
            )
        )
    );

    // SAISIE TEXTEAREA SUR L'OBJET RUBRIQUE DE LA BRANCHE N°5
    $champs['spip_rubriques']['infos_complementaires'] = array(
        'saisie' => 'textarea',
        'options' => array(
            'nom' => 'infos_complementaires',
            'label' => _T('prefixe:chaine_de_langue_infos_complementaires'), 
            'defaut' => '',
            // Nombre de ligne du champ dans l'espace privé
            'rows' => 10,
            // Insérer la barre d'outils type forum
            'inserer_barre' => 'forum',
            // Appliquer les traitements typographiques et raccourcis SPIP à l'affichage du champ
            'traitements' => '_TRAITEMENT_RACCOURCIS',
            'sql' => "text DEFAULT '' NOT NULL",
            // Afficher ce champ uniquement pour les articles de la branche n°5
            'restrictions'=>array(
                        'branche' => '5'
            ),
        )
    );
    return $champs;	
}

Indiquer au plugin de mettre à jour la base

Créer un fichier /prefixe_administrations.php contenant le code suivant :

<?php
if (!defined("_ECRIRE_INC_VERSION")) return;

// Inclure l'API Champs Extras
include_spip('inc/cextras');
// Inclure les champs déclarés à l'étape précédente
include_spip('base/prefixe');

function prefixe_upgrade($nom_meta_base_version,$version_cible) {

	$maj = array();

	// Première déclaration à l'installation du plugin
	cextras_api_upgrade(prefixe_declarer_champs_extras(), $maj['create']);

	include_spip('base/upgrade');
	maj_plugin($nom_meta_base_version, $version_cible, $maj);

}

// Désinstaller proprement le plugin en supprimant les champs de la base de données
function prefixe_vider_tables($nom_meta_base_version) {
	cextras_api_vider_tables(prefixe_declarer_champs_extras());
	effacer_meta($nom_meta_base_version);
}

Si vous ajoutez des champs extras une fois votre plugin installé et en fonctionnement, vous devez déclarer ces mises à jour en ajoutant au code ci-dessus (après la première déclaration $maj['create']) :

	// Ajout d'un nouveau ou plusieurs champs
	cextras_api_upgrade(prefixe_declarer_champs_extras(), $maj['0.1.1']);
	
	// Encore un ajout de nouveaux champs
	cextras_api_upgrade(prefixe_declarer_champs_extras(), $maj['0.1.2']);

Si vous supprimez des champs, par exemple la date, indiquer à votre plugin de les supprimer de la base :

Note : la valeur $maj['0.1.1'] doit correspondre avec le schema déclaré plus loin dans paquet.xml.

Dans votre paquet.xml

Dernière étape : pour que tout ça soit pris en compte, vous devez modifier votre fichier paquet.xml.

Indiquer que le plugin doit mettre à jour la base

Ajouter schema="0.1.0" dans la balise <paquet> afin que votre plugin mette à jour la base de données.
Puis, à chaque ajout ou surpression d’un champ, monter d’une version que le changement soit pris en compte.

Déclarer le pipeline champs extras

Enfin, déclarer le pipeline declarer_champs_extras :

	<pipeline nom="declarer_champs_extras" inclure="base/prefixe.php" />

Déclarer les dépendances

Pour que ça fonctionne, votre plugin nécessite désormais 3 autres plugins :

  • Champs Extras 3 pour gérer les champs en base
  • Saisies pour gérer les saisies (interface avec la base)
  • Vérifier pour vérifier les infos saisies avant de les rentrer en base

Ajouter ces nécessites :

Note : l’article ayant été écrit en mai/juin 2020, il sera peut-être nécessaire de mettre à jour les compatibilite.

Récapitulatif paquet.xml

Votre fichier paquet.xml doit désormais ressembler à ça :

Déclarer d’autres types de champs extras

Voici un exemple plus complet :

Pour aller plus loin