L’ajout, la modification et la publication des instances d’objets éditoriaux sont simplifiés par une interface de programmation (ou API) constituée de 3 fonctions génériques qui peuvent servir pour manipuler tous les objets de SPIP.
Insérer
Une nouvelle instance d’un objet éditorial est créée en base par
include_spip('action/editer_objet');
$id_objet = objet_inserer($objet, $id_parent);
objet_inserer
prend 2 arguments :
-
$objet
est le nom de l’objet inséré (article, breve,...) -
$id_parent
(facultatif) est l’id du parent de l’objet (id_rubrique pour un article ou une breve, id_groupe pour un mot...)
La fonction peut prendre un troisième argument optionnel : un tableau contenant les valeurs associées à chaque champ.
Les pipelines pre_insertion et post_insertion sont appelés automatiquement par la fonction.
Si, pour l’objet demandé, une fonction spécifique xxx_inserer
existe dans action/editer_xxx
, elle sera automatiquement appelée par objet_inserer
à la place du traitement générique.
La fonction retourne l’id de l’enregistrement ajouté en base, ou 0 en cas d’échec.
Modifier
Pour modifier une instance d’un objet en base, on utilise la fonction : objet_modifier
include_spip('action/editer_objet');
objet_modifier($objet, $id_objet, $set);
Les 3 arguments :
-
$objet
indique le nom de l’objet modifié -
$id_objet
donne l’id de l’objet modifié -
$set
est un tableau associatif champ=>valeur des champs modifiés
La fonction appelle automatiquement les pipelines pre_edition et post_edition.
Si pour l’objet demandé, une fonction spécifique xxx_modifier
existe dans action/editer_xxx
, elle sera automatiquement appelée par objet_modifier
à la place du traitement générique.
La fonction retourne une chaîne vide si tout s’est bien passé ou l’erreur en cas d’échec.
La fonction objet_modifier
vérifie les droits de l’auteur de la session en cours à faire l’action, via un appel à autoriser('modifier', $objet, $id_objet)
. Si elle est appelée par une tâche anonyme, il sera nécessaire d’accorder une autorisation exceptionnelle comme indiquée dans API de gestion des autorisations (`autoriser`).
Publier
Pour la publication d’un objet (modification du statut ou de la date), il convient d’appeler la même fonction objet_modifier
de la même façon que pour la modification.
Cette fonction délègue à objet_instituer
la mise à jour des champs qui concernent le statut de l’objet. Il est ainsi possible de modifier le contenu d’un objet et de le publier en un seul appel.
Si une fonction xxx_instituer
existe dans action/editer_xxx
elle sera automatiquement appelée par objet_instituer
à la place du traitement générique.
La fonction objet_instituer
vérifie les droits de l’auteur de la session en cours à faire l’action, via un appel à autoriser('instituer', $objet, $id_objet)
. Si elle est appelée par une tâche anonyme, il sera nécessaire d’accorder une autorisation exceptionnelle comme indiquée dans API de gestion des autorisations (`autoriser`).