API for declaring editorial objects

In SPIP the creation of new editorial objects is simplified by a programming interface. (or API) [1] which enables SPIP to build a large part of the editing interface for these objects in an automated way.

  • New in : SPIP 3.0

The declaration of a new editorial object is done via the pipeline declarer_tables_objets_sql which allows to populate an associative array:

  • Table keys are the names of SQL tables (example spip_articles)
  • to each key are associated a certain number of values in a table, according to the nomenclature below, presented by type of information

Database

table_objet
Explanation table shortcut name
Example articles for spip_articles
Default value table name without spip_
not declared
table_objet_surnom
Explanation synonyms of table_objet for special cases
Example no surname for articles (but example: groupe_mots for spip_groupes_mots)
Default value no surname
via declarer_tables_objets_surnoms
type
Explanation short name of the object
Example article for the table spip_articles
Default value primary key without id_ at the beginning or s at the end, or by default table name without spip_ at the beginning or s at the end
type_surnoms
Explanation synonym for type for special cases
Example
Default value no surname
field
Explanation SQL declaration of table fields
Example
array(
					"id_article"	=> "bigint(21) NOT NULL",
					"surtitre"	=> "text DEFAULT '' NOT NULL",
					"titre"	=> "text DEFAULT '' NOT NULL",
					"soustitre"	=> "text DEFAULT '' NOT NULL",...) 
Default value inherited from the declaration $tables_principales or $tables_auxiliaires if existing (compatibility)
Replaces the declaration included in the pipeline declarer_tables_principales, with the same syntax
key
Explanation SQL declaration of table keys
Example
array(
					"PRIMARY KEY"		=>"id_article",
					"KEY id_rubrique"	=> "id_rubrique",...)
Default value inherited from the declaration $tables_principales or $tables_auxiliaires if existing (compatibility)
Replaces the declaration included in the pipeline declarer_tables_principales, with the same syntax
join
Explanation the fields declared explicitly for the joins. otherwise the joins will be made exclusively on the primary key. warning: the fields ’idx’, ’maj’, ’date’ and ’statut’ can NOT be declared as possible join fields.
Example
array( 
"id_article"=>"id_article",
"id_rubrique"=>"id_rubrique")
Default value inherited from the declaration $tables_principales or $tables_auxiliaires if existing (compatibility)
Replaces the declaration included in the pipeline declarer_tables_principales, with the same syntax
tables_jointures
Explanation declaration of the link table and its join field. we will thus join (for example) id_article, articles to id_auteur, auteurs through the table auteurs_liens and its rows id_auteur, id_objet, objet (so, here: id_auteur, id_article, articles)
Example array(’id_auteur’ => ’auteurs_liens’)
Default value inherited from the declaration $tables_jointures if existing (compatibility)
$declarer_tables_objets_sql[’spip_articles’][’tables_jointures’] takes over the former content of $tables_jointures[’spip_articles’]
principale
Explanation Indicates whether the table is main or auxiliary table; takes the values ’yes’ or ’no’.
Example ’yes’
Default value inherited from the declaration $tables_principales if existing (compatibility)
Replaces the affectation of tables in the pipeline declarer_tables_principales or declarer_tables_auxiliaires
modeles
Explanation enables to declare the models associated to this object
Example example for spip_documents : array(’document’, ’doc’, ’img’, ’emb’, ’image’, ’video’, ’text’, ’audio’, ’application’)
Default value value of type

Title, date and status management

titre
Explanation SQL representation that allows to retrieve the title and language of the object
Example "titre, lang"
Default value inherited from the declaration $tables_titre (compatibility) or empty if not
Replaces the declaration of the title of the object in the pipeline declarer_tables_interfaces :
$interface['table_titre']['articles'] = "titre, '' AS lang";
date
Explanation declares the date field of the object used to date it
Example date
Default value inherited from the declaration $tables_date or empty
Replaces the declaration of the date of the object in declarer_tables_interfaces :
$interface['table_date']['articles'] = "date";
statut
Explanation Declaration of the status for the object
Example array(array(
’champ’ => ’statut’,
’publie’ => ’publie’,
’previsu’ => ’publie,prop,prepa’,
’post_date’ => ’date’,
’exception’ => ’statut’))
Default value empty
Replaces loop overriding with conditions where to manage the status. Here the declaration is directly taken into account in the generic loops.
statut_titres
Explanation Language strings of the title of each status. Defines the list of authorized statuses
Example array(
’prepa’=>’info_article_redaction’,
’prop’=>’info_article_propose’,
’publie’=>’info_article_publie’,
’refuse’=>’info_article_refuse’,
’poubelle’=>’info_article_supprime’)
Default value null
statut_images
Explanation defines the bullets associated with each status
Example
Default value null
No equivalence
statut_textes_instituer
Explanation Language strings of the wording of each status in the ’instituer’ block of the object
Example array(
’prepa’ => ’texte_statut_en_cours_redaction’,
’prop’ => ’texte_statut_propose_evaluation’,
’publie’ => ’texte_statut_publie’,
’refuse’ => ’texte_statut_refuse’,
’poubelle’ => ’texte_statut_poubelle’)
Default value null
No equivalence

Editing, Displaying and Searching

page
Explanation The name of the public page of the object
Example article
Default value type if main=’yes’, nothing otherwise
Replaces the declaration of the url of the object in the pipeline declarer_url_objets()
url_voir
Explanation name of the private exec to see the object
Example article
Default value type
url_edit
Explanation name of the private exec to edit the object
Example article_edit
Default value type+_edit
editable
Explanation give access to an editing page in the private area
Example ’yes’ or false
Default value yes
champs_editables
Explanation List of object fields that can be modified in the editing form
Example array(’surtitre’, ’titre’, ’soustitre’, ’descriptif’,’nom_site’, ’url_site’, ’chapo’, ’texte’, ’ps’,’virtuel’)
Default value empty
explicitly listed in the articles_set function of action/editer_article [2]
icone_objet
Explanation name of the icon file provided in 16/24/32px
Example article
Default value type
champs_versionnes
Explanation List of object fields subject to the revision process
Exemple array(’id_rubrique’, ’surtitre’, ’titre’, ’soustitre’, ’jointure_auteurs’, ’descriptif’, ’nom_site’, ’url_site’, ’chapo’, ’texte’, ’ps’)
Default value array()
rechercher_champs
Explanation Declaration of the fields used in the search and their respective scores
Example array(
’surtitre’ => 5, ’titre’ => 8, ’soustitre’ => 5, ’chapo’ => 3,...)
Default value array()
Replaces the declaration included in the pipeline rechercher_liste_des_champs: same syntax
rechercher_jointures
Explanation Declaration of the fields and their respective scores used via a join during the search.
Specify the table of these fields in the first element of the array.
Example array(
’auteur’ => array(’nom’ => 10)
)
Default value array()
Replaces the declaration included in the pipeline rechercher_liste_des_jointures : same syntax

Language strings

In these items, the standard texts used in the private area, in the pages automatically generated by SPIP, are declared in the form of a language string.

texte_ajouter
Explanation Chaine "Ajouter un ..."
Example titre_ajouter_un_auteur
Default value texte_ajouter_type
texte_retour
Explanation Language string of the back button in the object edit page
Example icone_retour_article
Valeur par défaut icone_retour
texte_modifier
Explanation Language string of the edit button to open the editing form of the object.
Example icone_modifier_article
Default value type:icone_modifier_type
texte_creer
Explanation Language string of the button to create a new object
Example icone_ecrire_article
Default value type:icone_creer_type
texte_creer_associer
Explanation  
Example creer_et_associer_un_auteur
Default value type:texte_creer_associer_type
texte_signale_edition
Explanation Language string indicating that author x has recently worked on the object
Example texte_travail_article
Default value info_qui_edite
texte_objet
Explanation Language string in singular of the object. The value is supposed to be written with a capital letter.
Example public:article
Default value type:titre_type
texte_objets
Explanation Language string of the plural of the object The value is supposed to be written with a capital letter.
Example public:articles
Default value type:titre_table_objet
info_aucun_objet
Explanation Language string designating 0 item used in the function objet_afficher_nb()
Example info_aucun_article
Default value type:info_aucun_type
info_1_objet
Explanation Language string designating 1 item used in the function objet_afficher_nb()
Example info_1_article
Default value type:info_1_type
info_nb_objets
Explanation Language string designating nb article used in the function objet_afficher_nb()
Example info_nb_articles
Default value type:info_nb_table_objets
texte_logo_objet
Explanation Language string of the title of the display box of the logo in the private page of the object
Example logo_article
Default value type:titre_logo_type
Replaces the use of the global $GLOBALS['logo_libelles']['id_objet']

News items example

Here is the declaration as created by the plugin that adds the news items as editorial objects in 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;
}

Footnotes

[1which notably groups together into a single one, several previously existing declarations

[2which meant that all the code had to be duplicated for a new object, except for this detail. This declaration allows the generic support of objects in action/editer_objet and its functions objet_modifier/objet_inserer/objet_instituer

Author jack Published : Updated : 23/07/23

Translations : English, français