Link table
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
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
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
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)
$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)
$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("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'));
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
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("auteur"=>3), array("article"=>5));
/* Example for associating an author to a list of articles and only to those articles */
objet_associer(array("auteur"=>3), array("article"=>array(5,6)));
objet_dissocier(array("auteur"=>3), array("article"=>array('NOT', array(5,6))));
The function returns the number of links actually deleted.
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("document"=>3), array("article"=>5), array('vu'=>'oui'));
The function returns the number of updates in base or false in case of failure.
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
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
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
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.