API editer_liens

SPIP 3 introduit une gestion générique des tables de liens d’un objet avec n’importe quel autre objet.

  • Apparu en : SPIP 3.0

Table de lien

Les liens sont structurellement non symétriques : il partent d’un objet source pour aller vers n’importe quel objet destination.

Pour être associable en tant que source, un objet bidibule stocké dans une table spip_bidibules doit posséder une table spip_bidibules_liens qui possèdera un champ id_bidibule (même nom que la clé primaire de spip_bidibules) et deux champs id_objet et objet.
La table peut aussi comporter d’autres champs pour qualifier les liens.

API

L’API permet de gérer simplement les liens sans manipuler directement des requêtes SQL, et en offrant systématiquement des points d’entrée aux plugins qui peuvent ainsi savoir quand un lien est ajouté, supprimé, ou modifié et agir en conséquence.

Pour utiliser l’API il faut inclure action/editer_liens.php :

include_spip('action/editer_liens');

objet_associable

objet_associable($objet) teste si un objet peut être associé à d’autres via sa table de liens.

Si l’objet n’est pas associable (il n’a pas de table de liens dédiée), la fonction renvoie false.

Si l’objet est associable, la fonction renvoie un tableau composé du nom de la clé primaire (commune à la table de liens et à la table de l’objet), et le nom de la table de liens.

Par exemple (et par défaut dans SPIP) les auteurs, les documents, les mots sont des objets associables car ils disposent tous d’une table spip_xxx_liens.

Par contre, les articles ne sont pas associables car ils ne disposent pas de table spip_articles_liens. Cela signifie qu’on ne peut pas créer de liens partant des articles vers un autre objet quelconque. En revanche on peut créer un lien depuis un mot, un auteur ou un document vers un article.

objet_associer

objet_associer($objets_source, $objets_lies[,$qualif]) permet d’associer les $objets_lies aux $objets_source via leurs table de lien propres.

$objets_source
Les $objets_source doivent être tous associables au sens de la fonction objet_associable(). Les objets sources sont donc les pivots sur lesquels portent les liens.

Le format de $objets_source est commun a toutes les fonctions de manipulation de liens.
C’est un tableau dont

  • chaque clé correspond au nom de l’objet à associer
  • chaque valeur décrit le ou les id pour chaque objet. Les valeurs peuvent être :
    • le joker "*" qui désigne "tous les id déja dans la table de lien" (il a donc peu d’intérêt dans le cas de l’ajout de liens comme ici)
    • une valeur scalaire autre désigne un id précis
    • un tableau désigne une liste d’id (un tableau ne peut pas contenir le joker "*")
    • un tableau de deux éléments commençant par la valeur ’NOT’ désigne une condition exclusive : tous les id déjà dans la table de lien sauf ceux décrits dans la seconde valeur (qui peut être à son tour un scalaire ou un tableau)

$objets_lies
Le format de $objets_lies est commun a toutes les fonctions de manipulation de liens.
C’est un tableau dont

  • chaque clé correspond au nom de l’objet à associer. La valeur joker "*" désigne "tous les objets présents dans la table de lien" (peu d’intérêt dans le cas d’ajout de lien donc)
  • chaque valeur décrit le ou les id pour chaque objet. Les valeurs peuvent être :
    • le joker "*" qui désigne "tous les id déja dans la table de lien" (il a donc peu d’intérêt dans le cas de l’ajout de liens comme ici)
    • une valeur scalaire autre désigne un id précis
    • un tableau désigne une liste d’id (un tableau ne peut pas contenir le joker "*")
    • un tableau de deux éléments commençant par la valeur ’NOT’ désigne une condition exclusive : tous les id déjà dans la table de lien sauf ceux décrits dans la seconde valeur (qui peut être à son tour un scalaire ou un tableau)

$qualif
La fonction objet_associer peut prendre un troisième argument facultatif $qualif qui est un tableau associatif champ=>valeur avec lequel seront modifiés les liens ajoutés. Cela peut être utile si la table de lien dispose de champs supplémentaires qui décrivent les liens.

Si plusieurs liens sont créés en même temps, ils se voient appliquer tous les mêmes valeurs décrites dans $qualif

exemples
Les exemples ci-dessous sont valides :

objet_associer(array("auteur"=>3), array("article"=>5));
objet_associer(array("auteur"=>3), array("article"=>array(5,6)));
objet_associer(array("auteur"=>array(3,4)), array("article"=>5));
objet_associer(array("auteur"=>array(3,4)), array("article"=>array(5,6)));
objet_associer(array("document"=>3), array("article"=>5), array('vu'=>'oui'));

La fonction renvoie le nombre de liens effectivement créés (certains liens pouvant déjà exister au moment de la tentative d’ajout, qui ne sont alors pas comptés).

objet_dissocier

objet_dissocier($objets_source,$objets_lies) permet de supprimer les liens entre les $objets_source et $objets_lies.

$objets_source
voir le format identique à celui décrit dans objet_associer

$objets_lies
voir le format identique à celui décrit dans objet_associer

exemples
Les exemples ci-dessous sont valides :

objet_dissocier(array("auteur"=>3), array("article"=>5));

/* Exemple pour associer un auteur à une liste d'article et uniquement à ceux là */
objet_associer(array("auteur"=>3), array("article"=>array(5,6)));
objet_dissocier(array("auteur"=>3), array("article"=>array('NOT', array(5,6))));

La fonction renvoie le nombre de liens effectivement supprimés.

objet_qualifier_liens

objet_qualifier_liens($objets_source,$objets_lies,$qualif) permet de modifier les valeurs des champs décrits dans $qualif sur les liens entre $objets_source et $objets_lies

$objets_source
voir le format identique à celui décrit dans objet_associer

$objets_lies
voir le format identique à celui décrit dans objet_associer

$qualif
voir le format identique à celui décrit dans objet_associer

exemples
Les exemples ci-dessous sont valides :

objet_qualifier(array("document"=>3), array("article"=>5), array('vu'=>'oui'));

La fonction renvoie le nombre de mise à jour en base ou false en cas d’échec.

objet_trouver_liens

objet_trouver_liens($objets_source,$objets_lies) permet de retrouver tous les liens de $objets_source vers $objets_lies.

$objets_source
voir le format identique à celui décrit dans objet_associer

$objets_lies
voir le format identique à celui décrit dans objet_associer

La fonction renvoie un tableau constitué d’un tableau associatif pour chaque lien trouvé. Ce dernier contient l’ensemble des champs du lien, auquel sont ajoutés une entrée objet=>id pour la source et la destination du lien, pour simplifier le traitement au retour (évite d’avoir à connaitre les clés primaires par exemple).

objet_optimiser_liens

objet_optimiser_liens($objets_source,$objets_lies) nettoie les liens restant entre $objets_source et $objets_lies lorsque l’un des deux n’existe plus (suppression en base de données).

Cette fonction est classiquement utilisée dans des fonctions crons de nettoyage de la base de données.

$objets_source
voir le format identique à celui décrit dans objet_associer

$objets_lies
voir le format identique à celui décrit dans objet_associer

La fonction renvoie le nombre de liens obsolètes nettoyés

objet_dupliquer_liens

objet_dupliquer_liens($objet,$id_source,$id_cible) va dupliquer tous les liens de l’$objet $id_source sur l’$objet $id_cible.

Pour cela, toutes les tables de liens de tous les objets connus seront parcourues pour trouver les liens depuis et vers l’$objet $id_source.

Chaque lien trouvé sera dupliqué en substituant $id_cible à $id_source

La fonction retourne le nombre de liens dupliqués.

Interface d’édition

Une interface générique #FORMULAIRE_EDITER_LIENS utilisable dans les squelettes permet l’édition des liens. #FORMULAIRE_EDITER_LIENS{auteurs,article,23} installera le formulaire pour associer/dissocier des auteurs de l’article N°23.

Les liens sont portés par la table lien du premier objet passé en argument du formulaire (auteurs dans l’exemple ci-dessus).

On peut utiliser ce formulaire de plusieurs façons :

  • #FORMULAIRE_EDITER_LIENS{auteurs,article,23} pour associer des auteurs à l’article N°23, sur la table pivot spip_auteurs_liens
  • #FORMULAIRE_EDITER_LIENS{auteur,12,articles} pour associer des articles à l’auteur N°12, sur la table pivot spip_auteurs_liens
  • #FORMULAIRE_EDITER_LIENS{mot,15,auteurs} pour associer des auteurs au mot N°15, sur la table pivot spip_mots_liens
  • #FORMULAIRE_EDITER_LIENS{auteurs,mot,15} pour associer des auteurs au mot N°15, sur la table pivot spip_auteurs_liens

On peut donc, par la syntaxe d’appel, définir quels objets sont associé entre eux, ainsi que la table qui supporte les liens.

Remarque : il est possible de filtrer la liste des objets présentés selon la valeur de certains de leurs champs en passant celles-ci en 4ème argument dans un tableau associatif champ=>valeur :

#FORMULAIRE_EDITER_LIENS{auteurs,article,23,#ARRAY{statut,6forum}}

Ne proposera que les auteurs dont le statut est 6forum.

Pour fonctionner, ce formulaire nécessite 2 squelettes correspondant au type d’objet associé. Par exemple pour pouvoir associer ou dissocier des auteurs de n’importe quel autre objet, les squelettes prive/objets/liste/auteurs_lies.html et prive/objets/liste/auteurs_associer.html sont nécessaires au fonctionnement du formulaire. Ils présentent la liste des objets déjà associés ainsi que la sélection des objets à associer. SPIP inclue nativement les vues nécessaires pour les auteurs, les rubriques, ainsi que les mots via le plugin mots. Des plugins peuvent rendre cette interface disponible pour de nouveaux objets éditoriaux par la définition de ces deux squelettes.

Auteur cerdic Publié le : Mis à jour : 26/06/23

Traductions : English, français