SPIP
Article validated
The article « API editer_liens
(https://www.spip.net/en_article6594.html) » was validated by George.
API editer_liens
Friday 16 September 2022 , by jack
SPIP 3 introduces generic management of the link tables between an object
and any other object.
Table of contents
- Link table
- API
- objet_associable
- objet_associer
- objet_dissocier
- objet_qualifier_liens
- objet_trouver_liens
- objet_optimiser_liens
- objet_dupliquer_liens
- Editing Interface
Link table|Back to the table of contents
Links are structurally non-symmetrical: they start from a source object and
go to any destination object.
To be associable as a source, an object bidibule stored in a table
spip_bidibules must have a table spip_bidibules_links that will have
one field id_bidibule (same name as the primary key of spip_bidibules)
and two fields id_objet and objet.
The table can also have other fields to describe the links.
API|Back to the table of contents
The API makes it easy to manage links without directly manipulating SQL
queries, and by systematically providing entry points for plug-ins enabling
them to know when a link is added, removed, or modified and act
accordingly.
To use the API you need to include action/edit_links.php:
include_spip
(
'action/editer_liens'
)
;
objet_associable|Back to the table of contents
objet_associable($objet) tests whether an object can be linked to others
via its link table.
If the object is not associable (it has no dedicated link table), the
function returns false.
If the object is associable, the function returns an array composed of the
name of the primary key (common to the link table and the object table),
and the name of the link table.
For example (and by default in SPIP) authors, documents and keywords are
associable objects because they all have a spip_xxx_links tables.
On the other hand, articles are not associable because they do not have a
spip_articles_links table. This means that you cannot create links from
the articles to any other object, but you can create a link from a keyword,
an author or a document to an article.
objet_associer|Back to the table of contents
objet_associer($objets_source, $objets_lies[,$qualif]) allows to
associate the $objets_lies to the $objets_source via their own link
table.
$objets_source
The $objets_source must all be associable in the sense of the function
objet_associable(). The source objects are therefore the pivots on which
the links are based.
The format of $objets_source is common to all link manipulation
functions.
It is an array of which
- each key corresponds to the name of the object to be associated
- each value describes the id(s) for each object. The values can be :
- the wildcard « * » which stands for « all ids already in the link
table » (so it has little interest in the case of adding links like here) - an integer denotes a specific id
- an array refers to a list of ids (an array cannot contain the
wildcard « * ») - an array of two elements beginning with the value ’NOT’
indicates an exclusive condition: all the ids already in the link table
except those described in the second value (which can be an integer or an
array in turn)
- the wildcard « * » which stands for « all ids already in the link
$objets_lies
The format of $objets_lies is common to all link manipulation functions.
It is an array of which
- each key corresponds to the name of the object to be associated. The
wildcard value « * » indicates « all objects present in the link table » (of
little interest in the case of adding a link). - each value describes the id(s) for each object. The values can be :
- the wildcard « * » which stands for « all ids already in the link
table » (so it has little interest in the case of adding links like here) - an integer denotes a specific id
- an array refers to a list of ids (an array cannot contain the
wildcard « * ») - an array of two elements beginning with the value ’NOT’
indicates an exclusive condition: all the ids already in the link table
except those described in the second value (which can be an integer or an
array in turn)
- the wildcard « * » which stands for « all ids already in the link
$qualif
The function objet_associer can take an optional third argument $qualif
which is an associative array field=>value with which the
added links will be modified. This can be useful if the link table has
additional fields that describe the links.
If multiple links are created at the same time, the same values described
in $qualif are applied to all of them.
examples
The examples below are valid:
objet_associer
(
array
(http://www.php.net/array)
(
"auteur"
=>
3
)
,
array
(http://www.php.net/array)
(
"article"
=>
5
)
)
;
objet_associer
(
array
(http://www.php.net/array)
(
"auteur"
=>
3
)
,
array
(http://www.php.net/array)
(
"article"
=>
array
(http://www.php.net/array)
(
5
,
6
)
)
)
;
objet_associer
(
array
(http://www.php.net/array)
(
"auteur"
=>
array
(http://www.php.net/array)
(
3
,
4
)
)
,
array
(http://www.php.net/array)
(
"article"
=>
5
)
)
;
objet_associer
(
array
(http://www.php.net/array)
(
"auteur"
=>
array
(http://www.php.net/array)
(
3
,
4
)
)
,
array
(http://www.php.net/array)
(
"article"
=>
array
(http://www.php.net/array)
(
5
,
6
)
)
)
;
objet_associer
(
array
(http://www.php.net/array)
(
"document"
=>
3
)
,
array
(http://www.php.net/array)
(
"article"
=>
5
)
,
array
(http://www.php.net/array)
(
'vu'
=>
'oui'
)
)
;
The function returns the number of links actually created (some links may
already exist at the time of the addition attempt, which are then not
counted).
objet_dissocier|Back to the table of contents
objet_dissocier($objets_source,$objets_lies) is used to remove the links
between $objets_source and $objets_lies.
$objets_source
see the same format as described in objet_associer
$objets_lies
see the same format as described in objet_associer
examples
The examples below are valid:
objet_dissocier
(
array
(http://www.php.net/array)
(
"auteur"
=>
3
)
,
array
(http://www.php.net/array)
(
"article"
=>
5
)
)
;
/* Example for associating an author to a list of articles and only to
those articles */
objet_associer
(
array
(http://www.php.net/array)
(
"auteur"
=>
3
)
,
array
(http://www.php.net/array)
(
"article"
=>
array
(http://www.php.net/array)
(
5
,
6
)
)
)
;
objet_dissocier
(
array
(http://www.php.net/array)
(
"auteur"
=>
3
)
,
array
(http://www.php.net/array)
(
"article"
=>
array
(http://www.php.net/array)
(
'NOT'
,
array
(http://www.php.net/array)
(
5
,
6
)
)
)
)
;
The function returns the number of links actually deleted.
objet_qualifier_liens[|Back to the table of
contents](#s-objet_qualifier_liens)
objet_qualifier_liens($objets_source,$objets_lies,$qualif) allows to
modify the values of the fields described in $qualif on the links between
$objets_source and $objets_lies
$objets_source
see the same format as described in objet_associer
$objets_lies
see the same format as described in objet_associer
$qualif
see the same format as described in objet_associer
examples
The examples below are valid:
objet_qualifier
(
array
(http://www.php.net/array)
(
"document"
=>
3
)
,
array
(http://www.php.net/array)
(
"article"
=>
5
)
,
array
(http://www.php.net/array)
(
'vu'
=>
'oui'
)
)
;
The function returns the number of updates in base or false in case of
failure.
objet_trouver_liens[|Back to the table of
contents](#s-objet_trouver_liens)
objet_trouver_liens($objets_source,$objets_lies) allows to retrieve all
links from $objets_source to $objets_lies.
$objets_source
see the same format as described in objet_associer
$objets_lies
see the same format as described in objet_associer
The function returns an array consisting of an associative array for each
link found. The latter contains all the fields of the link, to which is
added an entry objet=>id for the source and destination of the link, to
simplify processing on return (avoids having to know the primary keys for
example).
objet_optimiser_liens[|Back to the table of
contents](#s-objet_optimiser_liens)
objet_optimiser_liens($objets_source,$objets_lies) clears the remaining
links between $objets_source and $objets_lies when one of the two no
longer exists (database deletion).
This function is classically used in cron functions for database cleansing.
$objets_source
see the same format as described in objet_associer
$objets_lies
see the same format as described in objet_associer
The function returns the number of obsolete links cleaned up.
objet_dupliquer_liens[|Back to the table of
contents](#s-objet_dupliquer_liens)
objet_dupliquer_liens($objet,$id_source,$id_cible) will duplicate all the
links in the $objet $id_source on the $objet $id_cible.
To do this, all the link tables of all known objects will be browsed to
find links from and to the $objet $id_source.
Each link found will be duplicated by substituting $id_cible into
$id_source
The function returns the number of duplicate links.
Editing Interface|Back to the table of contents
A generic interface #FORMULAIRE_EDITER_LIENSusable in the templates
allows the edition of links.
#FORMULAIRE_EDITER_LIENS{auteurs,article,23} will install the form to
associate/dissociate the authors of article N°23.
The links are carried by the link table of the first object passed as
argument of the form (authors in the example above).
This form can be used in several ways:
-
#FORMULAIRE_EDITER_LIENS{auteurs,article,23}to associate authors to
article N°23, on the pivot table spip_auteurs_liens -
#FORMULAIRE_EDITER_LIENS{auteur,12,articles}to associate articles
with author N°12, on the pivot table spip_auteurs_liens -
#FORMULAIRE_EDITER_LIENS{mot,15,auteurs}to associate authors with
the keyword N°15, on the pivot table spip_mots_liens -
#FORMULAIRE_EDITER_LIENS{auteurs,mot,15}to associate authors with
the keyword N°15, on the pivot table spip_auteurs_liens
We can therefore, through the call syntax, define which objects are
associated with each other, as well as the table that supports the links.
Note: it is possible to filter the list of objects presented according to
the value of some of their fields by passing these as the 4th argument in
an associative array field=>value:
- #FORMULAIRE_EDITER_LIENS {auteurs,article,23, #ARRAY {statut,6forum}}
Will propose only authors whose status is
6forum.
To work, this form requires 2 templates corresponding to the type of
associated object. For example, in order to be able to associate or
dissociate authors from any other object, the templates
prive/objets/liste/auteurs_lies.html and
prive/objets/liste/auteurs_associer.html are necessary for the operation
of the form. They present the list of objects already associated as well as
the selection of objects to be associated.
SPIP natively includes the necessary views for authors, headings and
keywords via the plug-in Mots.
Plug-ins can make this interface available for new editorial objects by
defining these two templates.
— Sent by SPIP (https://www.spip.net/)
