API de déclaration d’objets éditoriaux

La création de nouveaux objets éditoriaux est simplifiée par une interface de programmation (ou API) déclarative [1] qui permet à SPIP de construire de façon automatisée une grande partie de l’interface d’édition de ces objets.

  • Apparu en : SPIP 3.0

La déclaration d’un nouvel objet éditorial se fait via le pipeline declarer_tables_objets_sql qui permet de peupler un tableau associatif :

  • Les clés du tableau sont les noms des tables SQL (exemple spip_articles)
  • à chaque clé sont associées un certain nombre de valeurs dans un tableau, selon la nomenclature ci-dessous, présentée par type d’information

Remarque : Le pipeline declarer_tables_objets_sql est un pipeline supplémentaire qui sert la déclaration des tables des objets editoriaux seulement. Il ne remplace pas vraiment le pipeline declarer_tables_principales : si une table ne concerne pas un objet éditorial, sa déclaration ne doit pas se faire via declarer_tables_objets_sql mais doit se faire avec declarer_tables_principales.

Base de données

Explication nom raccourci de la table
Exemple articles pour spip_articles
Valeur par défaut nom de la table sans spip_
non déclaré
table_objet_surnom
Explication synonymes de table_objet pour les cas particuliers
Exemple pas de surnom pour articles (mais exemple : groupe_mots pour spip_groupes_mots)
Valeur par défaut pas de surnom
via declarer_tables_objets_surnoms
type
Explication nom court de l’objet
Exemple article pour la table spip_articles
Valeur par défaut clé primaire sans id_ au début ni s a la fin, ou à défaut nom de la table sans spip_ au début ni s a la fin
type_surnoms
Explication synonyme du type pour les cas particuliers
Exemple
Valeur par défaut pas de surnom
field
Explication Déclaration SQL des champs de la table
Exemple
array(
  "id_article"	=> "bigint(21) NOT NULL",
  "surtitre"	=> "text DEFAULT '' NOT NULL",
  "titre"	=> "text DEFAULT '' NOT NULL",
  "soustitre"	=> "text DEFAULT '' NOT NULL",...)
Valeur par défaut héritée de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité)
Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe
key
Explication Déclaration SQL des clés de la table
Exemple
array(
  "PRIMARY KEY"		=>"id_article",
  "KEY id_rubrique"	=> "id_rubrique",...)
Valeur par défaut hérité de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité)
Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe
join
Explication les champs déclarés explicitement pour les jointures. sinon les jointures se feront exclusivement sur la clef primaire. attention : les champs ’idx’, ’maj’, ’date’ et ’statut’ ne peuvent PAS être déclarés comme champs de jointure possible.
Exemple
array( 
"id_article"=>"id_article",
"id_rubrique"=>"id_rubrique") 
Valeur par défaut hérité de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité)
Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe
tables_jointures
Explication déclaration de la table de liens et de son champ de jointure. on joindra ainsi (par exemple) id_article, articles à id_auteur, auteurs en passant par la table auteurs_liens et ses lignes id_auteur, id_objet, objet (donc, ici : id_auteur, id_article, articles)
Exemple array(’id_auteur’ => ’auteurs_liens’)
Valeur par défaut hérité de la déclaration $tables_jointures si existante (compatibilité)
$declarer_tables_objets_sql[’spip_articles’][’tables_jointures’] reprend l’ancien contenu de
$tables_jointures[’spip_articles’]
principale
Explication Indique si la table est table principale ou auxiliaire ; prend les valeurs ’oui’ ou ’non’ .
Rq : Si la table est auxiliaire, il faut alors mettre soit-même un AUTO INCREMENT sur la clé primaire.
Exemple ’oui’
Valeur par défaut hérité de la déclaration $tables_principales si existante (compatibilité)
Remplace l’affectation des tableaux dans le pipeline declarer_tables_principales ou declarer_tables_auxiliaires
modeles
Explication permet de déclarer les modèles associés a cet objet
Exemple exemple pour spip_documents : array(’document’, ’doc’, ’img’, ’emb’, ’image’, ’video’, ’text’, ’audio’, ’application’)
Valeur par défaut la valeur de type

Le titre, la date et la gestion du statut

titre
Explication Représentation SQL qui permet de récupérer le titre et la langue de l’objet
Exemple "titre, lang"
Valeur par défaut hérité de la déclaration $tables_titre (compatibilité) ou vide sinon
Remplace la déclaration du titre de l’objet dans le pipeline declarer_tables_interfaces :
$interface['table_titre']['articles'] = "titre, '' AS lang";
date
Explication déclare le champ date de l’objet utilisé pour le dater
Exemple date
Valeur par défaut hérité de la déclaration $tables_date ou vide
Remplace la déclaration de la date de l’objet dans declarer_tables_interfaces :
$interface['table_date']['articles'] = "date";
statut
Explication Déclaration du statut pour l’objet
Exemple
array(array(
  'champ' => 'statut',
  'publie' => 'publie',
  'previsu' => 'publie,prop,prepa/auteur',
  'post_date' => 'date',
  'exception' => 'statut')) 


Rq : "’previsu’ => ’publie,prop,prepa/auteur" indique qu’un objet ayant le statut ’publie’ ou ’prop’ peut être prévisualisé, ainsi qu’un objet ayant le statut ’prepa’ lorsque c’est un de ses auteurs qui le demande

Valeur par défaut vide
Remplace la surcharge des boucles avec conditions where pour gerer le statut. Ici la déclaration est directement prise en compte dans les boucles génériques
statut_titres
Explication Chaines de langue du titre de chaque statut. Définit par la même la liste des statuts autorisés
Exemple
array(
  'prepa'=>'info_article_redaction',
  'prop'=>'info_article_propose',
  'publie'=>'info_article_publie',
  'refuse'=>'info_article_refuse',
  'poubelle'=>'info_article_supprime')
Valeur par défaut null
statut_images
Explication definit les puces associées à chaque statut
Exemple
Valeur par défaut null
Pas d’équivalence
statut_textes_instituer
Explication Chaines de langue du libellé de chaque statut dans le bloc instituer de l’objet
Exemple
array(
  'prepa' => 'texte_statut_en_cours_redaction',
  'prop' => 'texte_statut_propose_evaluation',
  'publie' => 'texte_statut_publie',
  'refuse' => 'texte_statut_refuse',
  'poubelle' => 'texte_statut_poubelle') 
Valeur par défaut null
Pas d’équivalence

L’édition, l’affichage et la recherche

page
Explication Le nom de la page publique de l’objet
Exemple article
Valeur par défaut type si principale=’oui’, rien sinon
Remplace la déclaration de l’url de l’objet dans le pipeline declarer_url_objets()
url_voir
Explication nom de l’exec privé pour voir l’objet
Exemple article
Valeur par défaut type
url_edit
Explication nom de l’exec privé pour éditer l’objet
Exemple article_edit
Valeur par défaut type+_edit
editable
Explication donner acces à une page d’édition dans l’espace privé
Exemple ’oui’ ou false
Valeur par défaut oui
champs_editables
Explication Liste des champs de l’objet pouvant être modifiés dans le formulaire d’édition
Exemple array(’surtitre’, ’titre’, ’soustitre’, ’descriptif’,’nom_site’, ’url_site’, ’chapo’, ’texte’, ’ps’,’virtuel’)
Valeur par défaut vide
listés explicitement dans la fonction articles_set de action/editer_article [2]
icone_objet
Explication nom du fichier d’icône fourni en 16/24/32px
Exemple article
Valeur par défaut type
champs_versionnes
Explication Liste des champs de l’objet soumis au processus de révisions
Exemple array(’id_rubrique’, ’surtitre’, ’titre’, ’soustitre’, ’jointure_auteurs’, ’descriptif’, ’nom_site’, ’url_site’, ’chapo’, ’texte’, ’ps’)
Valeur par défaut array()
rechercher_champs
Explication Déclaration des champs utilisés dans la recherche et de leur score respectif
Exemple array(
’surtitre’ => 5, ’titre’ => 8, ’soustitre’ => 5, ’chapo’ => 3,...)
Valeur par défaut array()
Remplace la déclaration incluse dans le pipeline rechercher_liste_des_champs : même syntaxe
rechercher_jointures
Explication Déclaration des champs et de leurs scores respectifs utilisés via une jointure lors de la recherche.
Préciser la table de ces champs en premier élément de l’array.
Exemple array(
’auteur’ => array(’nom’ => 10)
)
Valeur par défaut array()
Remplace la déclaration incluse dans le pipeline rechercher_liste_des_jointures : même syntaxe

Les chaines de langue

On déclare dans ces items là sous forme de chaine de langue les textes standards utilisés dans l’espace privé, dans les pages générées automatiquement par SPIP.

texte_ajouter
Explication Chaine "Ajouter un ..."
Exemple titre_ajouter_un_auteur
Valeur par défaut texte_ajouter_type
texte_retour
Explication Chaine de langue du bouton retour dans la page d’édition de l’objet
Exemple icone_retour_article
Valeur par défaut icone_retour
texte_modifier
Explication Chaine de langue du bouton modifier permettant d’ouvrir le formulaire d’édition de l’objet
Exemple icone_modifier_article
Valeur par défaut type:icone_modifier_type
texte_creer
Explication Chaine de langue du bouton de création d’un nouvel objet
Exemple icone_ecrire_article
Valeur par défaut type:icone_creer_type
texte_creer_associer
Explication  
Exemple creer_et_associer_un_auteur
Valeur par défaut type:texte_creer_associer_type
texte_signale_edition
Explication Chaine de langue signalant que l’auteur x a travaillé récemment sur l’objet
Exemple texte_travail_article
Valeur par défaut info_qui_edite
texte_objet
Explication Chaine de langue du singulier de l’objet. La valeur est censée être écrite avec une lettre capitale
Exemple public:article
Valeur par défaut type:titre_type
texte_objets
Explication Chaine de langue du pluriel de l’objet La valeur est censée être écrite avec une lettre capitale
Exemple public:articles
Valeur par défaut type:titre_table_objet
info_aucun_objet
Explication Chaine de langue désignant 0 article utilisée dans la fonction objet_afficher_nb()
Exemple info_aucun_article
Valeur par défaut type:info_aucun_type
info_1_objet
Explication Chaine de langue désignant 1 article utilisée dans la fonction objet_afficher_nb()
Exemple info_1_article
Valeur par défaut type:info_1_type
info_nb_objets
Explication Chaine de langue désignant nb article utilisée dans la fonction objet_afficher_nb()
Exemple info_nb_articles
Valeur par défaut type:info_nb_table_objets
texte_logo_objet
Explication Chaine de langue du titre de la boite d’affichage du logo dans la page privée de l’objet
Exemple logo_article
Valeur par défaut type:titre_logo_type
Remplace l’utilisation de la globale $GLOBALS['logo_libelles']['id_objet']

Exemple des brèves

Voici la déclaration telle que réalisée par le plugin qui ajoute les brèves comme objet éditorial dans SPIP :

function breves_declarer_tables_objets_sql($tables){
	$tables['spip_breves'] = array(
		'texte_retour' => 'icone_retour',
		'texte_objets' => 'breves:breves',
		'texte_objet' => 'breves:breve',
		'texte_modifier' => 'breves:icone_modifier_breve',
		'texte_creer' => 'breves:icone_nouvelle_breve',
		'info_aucun_objet'=> 'breves:info_aucun_breve',
		'info_1_objet' => 'breves:info_1_breve',
		'info_nb_objets' => 'breves:info_nb_breves',
		'texte_logo_objet' => 'breves:logo_breve',
		'texte_langue_objet' => 'breves:titre_langue_breve',
		'titre' => 'titre, lang',
		'date' => 'date_heure',
		'principale' => 'oui',
		'field'=> array(
			"id_breve"	=> "bigint(21) NOT NULL",
			"date_heure"	=> "datetime DEFAULT '0000-00-00 00:00:00' NOT NULL",
			"titre"	=> "text DEFAULT '' NOT NULL",
			"texte"	=> "longtext DEFAULT '' NOT NULL",
			"lien_titre"	=> "text DEFAULT '' NOT NULL",
			"lien_url"	=> "text DEFAULT '' NOT NULL",
			"statut"	=> "varchar(6)  DEFAULT '0' NOT NULL",
			"id_rubrique"	=> "bigint(21) DEFAULT '0' NOT NULL",
			"lang"	=> "VARCHAR(10) DEFAULT '' NOT NULL",
			"langue_choisie"	=> "VARCHAR(3) DEFAULT 'non'",
			"maj"	=> "TIMESTAMP"
		),
		'key' => array(
			"PRIMARY KEY"	=> "id_breve",
			"KEY id_rubrique"	=> "id_rubrique",
		),
		'join' => array(
			"id_breve"=>"id_breve",
			"id_rubrique"=>"id_rubrique"
		),
		'statut' =>  array(
			array(
				'champ'=>'statut',
				'publie'=>'publie',
				'previsu'=>'publie,prop',
				'exception'=>'statut'
			)
		),
		'texte_changer_statut' => 'breves:entree_breve_publiee',
		'aide_changer_statut' => 'brevesstatut',
		'statut_titres' => array(
			'prop' => 'breves:titre_breve_proposee',
			'publie' => 'breves:titre_breve_publiee',
			'refuse' => 'breves:titre_breve_refusee',
		),
		'statut_textes_instituer' => 	array(
			'prop' => 'breves:item_breve_proposee', //_T('texte_statut_propose_evaluation')
			'publie' => 'breves:item_breve_validee', //_T('texte_statut_publie')
			'refuse' => 'breves:item_breve_refusee', //_T('texte_statut_refuse')
		),

		'rechercher_champs' => array(
		  'titre' => 8, 'texte' => 2, 'lien_titre' => 1, 'lien_url' => 1
		),
		'rechercher_jointures' => array(
			'document' => array('titre' => 2, 'descriptif' => 1)
		),
		'champs_versionnes' => array('id_rubrique', 'titre', 'lien_titre', 'lien_url', 'texte'),
	);

	return $tables;
}

Notes

[1qui regroupe notamment en une seule, plusieurs déclarations existantes auparavant

[2ce qui obligeait à dupliquer tout le code pour un nouvel objet, à ce détail près. Cette déclaration permet le support générique des objets dans action/editer_objet et ses fonctions objet_modifier/objet_inserer/objet_instituer

Voir aussi sur programmer.spip.net : pipelines : declarer_tables_objets_sql

Auteur cerdic, _Eric_ Publié le : Mis à jour : 23/07/23

Traductions : English, français