**SPIP**
# Article submitted
The article "**API for declaring editorial objects**
(https://www.spip.net/ecrire/?exec=article&id_article=6598)" is submitted
for publication. on Wednesday 2 September 2020.
* * *
## API for declaring editorial objects
Wednesday 2 September 2020 , by [jack](.././?page=auteur&id_auteur=593&)
In SPIP 3.0 (https://www.spip.net/ecrire/?exec=article&id_article=5533) the
creation of new editorial objects is simplified by a programming interface
(https://en.wikipedia.org/wiki/API). (or API) [1] which enables SPIP to
build a large part of the editing interface for these objects in an
automated way.
## Table of contents
* Database
* Title, date and status management
* Editing, Displaying and Searching
* Language strings
* News items example
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[|Back to the table of contents](#s-Database)
**table_objet**
Explanation
table shortcut name
Example
*articles* for *spip_articles*
Default value
table name without spip_
in SPIP 2.1
*not declared*
---------------------------------------------------------------------------
**table\_objet\_surnom**
Explanation
synonyms of *table_objet* for special cases
Example
no surname for items (but example: groupe\_mots for spip\_groupes_mots)
Default value
no surname
in SPIP 2.1
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
in SPIP 2.1
---------------------------------------------------------------------------
**type_surnoms**
Explanation
synonym for *type* for special cases
Example
Default value
no surname
in SPIP 2.1
---------------------------------------------------------------------------
**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)
in SPIP 2.1
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)
in SPIP 2.1
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. attention: 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)
in SPIP 2.1
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 lines 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)
in SPIP 2.1
$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)
in SPIP 2.1
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*
in SPIP 2.1
---------------------------------------------------------------------------
## Title, date and status management[|Back to the table of
contents](#s-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
in SPIP 2.1
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
in SPIP 2.1
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
in SPIP 2.1
Replaces loop surcharge 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
in SPIP 2.1
---------------------------------------------------------------------------
**statut_images**
Explanation
defines the bullets associated with each status
Example
Default value
null
in SPIP 2.1
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
in SPIP 2.1
No equivalence
---------------------------------------------------------------------------
## Editing, Displaying and Searching[|Back to the table of
contents](#s-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
in SPIP 2.1
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
in SPIP 2.1
---------------------------------------------------------------------------
**url_edit**
Explanation
name of the private exec to edit the object
Example
article_edit
Default value
type+_edit
in SPIP 2.1
---------------------------------------------------------------------------
**editable**
Explanation
give access to an editing page in the back office
Example
’yes’ or false
Default value
yes
in SPIP 2.1
---------------------------------------------------------------------------
**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
in SPIP 2.1
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
in SPIP 2.1
---------------------------------------------------------------------------
**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()
in SPIP 2.1
---------------------------------------------------------------------------
**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()
in SPIP 2.1
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()
in SPIP 2.1
Replaces the declaration included in the pipeline
rechercher\_liste\_des_jointures : same syntax
---------------------------------------------------------------------------
## Language strings[|Back to the table of contents](#s-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*
in SPIP 2.1
---------------------------------------------------------------------------
**texte_retour**
Explanation
Language string of the back button in the object edit page
Example
icone\_retour\_article
Valeur par défaut
icone_retour
dans SPIP 2.1
---------------------------------------------------------------------------
**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*
in SPIP 2.1
---------------------------------------------------------------------------
**texte_creer**
Explanation
Language string of the button to create a new object
Example
icone\_ecrire\_article
Default value
*type*:icone\_creer\_*type*
in SPIP 2.1
---------------------------------------------------------------------------
**texte\_creer\_associer**
Explanation
Example
creer\_et\_associer\_un\_auteur
Default value
*type*:texte\_creer\_associer_*type*
in SPIP 2.1
---------------------------------------------------------------------------
**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
in SPIP 2.1
---------------------------------------------------------------------------
**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*
in SPIP 2.1
---------------------------------------------------------------------------
**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*
in SPIP 2.1
---------------------------------------------------------------------------
**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*
in SPIP 2.1
---------------------------------------------------------------------------
**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*
in SPIP 2.1
---------------------------------------------------------------------------
**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*
in SPIP 2.1
---------------------------------------------------------------------------
**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*
in SPIP 2.1
Replaces the use of the global `$GLOBALS['logo_libelles']['id_objet']`
---------------------------------------------------------------------------
## News items example[|Back to the table of
contents](#s-News-items-example)
Here is the declaration as realized by the plugin that adds the news items
as editorial objects in SPIP :
function
breves_declarer_tables_objets_sql
(
$tables
)
{
$tables
[
'spip_breves'
]
=
array
(http://www.php.net/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
(http://www.php.net/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
(http://www.php.net/array)
(
"PRIMARY KEY"
=>
"id_breve"
,
"KEY id_rubrique"
=>
"id_rubrique"
,
)
,
'join'
=>
array
(http://www.php.net/array)
(
"id_breve"
=>
"id_breve"
,
"id_rubrique"
=>
"id_rubrique"
)
,
'statut'
=>
array
(http://www.php.net/array)
(
array
(http://www.php.net/array)
(
'champ'
=>
'statut'
,
'publie'
=>
'publie'
,
'previsu'
=>
'publie,prop'
,
'exception'
=>
'statut'
)
)
,
'texte_changer_statut'
=>
'breves:entree_breve_publiee'
,
'aide_changer_statut'
=>
'brevesstatut'
,
'statut_titres'
=>
array
(http://www.php.net/array)
(
'prop'
=>
'breves:titre_breve_proposee'
,
'publie'
=>
'breves:titre_breve_publiee'
,
'refuse'
=>
'breves:titre_breve_refusee'
,
)
,
'statut_textes_instituer'
=>
array
(http://www.php.net/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
(http://www.php.net/array)
(
'titre'
=>
8
,
'texte'
=>
2
,
'lien_titre'
=>
1
,
'lien_url'
=>
1
)
,
'rechercher_jointures'
=>
array
(http://www.php.net/array)
(
'document'
=>
array
(http://www.php.net/array)
(
'titre'
=>
2
,
'descriptif'
=>
1
)
)
,
'champs_versionnes'
=>
array
(http://www.php.net/array)
(
'id_rubrique'
,
'titre'
,
'lien_titre'
,
'lien_url'
,
'texte'
)
,
)
;
return
$tables
;
}
[1] which notably groups together into a single one, several previously
existing declarations
[2] which 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
— Sent by SPIP (https://www.spip.net/)
