Coding with SPIP 4

editer_liens API to link object tables

Jack, JLuc — 2025-08-22T07:55:35Z

SPIP 3 introduces generic management of the link tables between an object and any other object.

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.

post_insertion

Mark Baber — 2010-11-10T08:09:44Z

This pipeline is a trigger that runs after the insertion of new records into the database. This allows you to perform specific actions after record insertion.

The pipeline passes the name of the table, the identifier of the record created and an array of the fields and values inserted:

pipeline('post_insertion', array( 'args' => array( 'table' => 'spip_articles', 'id_objet' => $id_article ), 'data' => $champs ) );

libelle_association_mots

Mark Baber — 2010-10-13T06:35:13Z

The libelle_association_mots pipeline is called in ecrire/exec/mots_tous.php to display the text description of the elements that can be linked to a given keyword group. Each object is associated with a language string identifier:

$libelles = array( 'articles'=>'info_articles_2', 'breves'=>'info_breves_02', 'rubriques'=>'info_rubriques', 'syndic'=>'icone_sites_references' ); $libelles = pipeline('libelle_association_mots', $libelles);

So the pipeline is passed an associative array with keys being the object names (written in the plural) and values being the names of the corresponding language string identifier.

afficher_nombre_objets_associes_a

Mark Baber — 2010-10-13T06:28:42Z

The afficher_nombre_objets_associes_a pipeline is called to display information about the number of elements linked to a given editorial object. It can therefore be used to provide the number of elements linked to a given keyword when called from the keyword groups page as shown below:

$texte_lie = pipeline( 'afficher_nombre_objets_associes_a', array( 'args'=>array( 'objet'=>'mot', 'id_objet'=>$id_mot), 'data'=>$texte_lie));

The object's type and identifier for which the associated links are to be counted are passed as arguments to the pipeline. The data key is an array of values that will be comma-separated and concatenated for display purposes.

objet_compte_enfants

Mark Baber — 2010-10-13T06:16:58Z

This pipeline is used to augment or modify the count of children of an object.

It is called as show below in the ecrire/inc/rubriques.php file:

// We pass the table of counts in a pipeline so that the plugins can add (or remove) children $compte = pipeline('objet_compte_enfants', array( 'args' => array( 'objet' => 'rubrique', 'id_objet' => $id_rubrique, 'statut' => 'publie', 'date' => $date ), 'data' => $compte ) );

It accepts an argument which is the object for which you wish to count children using the objet and id_objet parameters. It can also be passed the status of the children that you want to be used to filter the count.

In the call above, we requested a count of the "published" children in a specific section.

The data contents of the pipeline is an associative array, with the key being the type of object in the plural (e.g. "articles"), and the value being an integer which matches the number of children of that type.

Definition

Mark Baber — 2010-05-29T16:22:48Z

A pipeline is used to make one of SPIP's standard functions perform different or additional functionality by passing it custom-made functions that will be automatically triggered at the right times.

Declaration within a plugin

Any plugin can use any existing pipeline. To do so, it declares it in the plugin.xml file as illustrated here below:

 header_prive cfg_pipeline.php

Nom: specifies the name of the pipeline to be used,
Inclure: specifies the name of the file that contains the function to be executed when the pipeline is called (prefixPlugin_PipelineName()).

Declaration without using a plugin

One usage of a pipeline outside that of plugins does remain possible. In this case, it must be declared directly in the config/mes_options.php file:

$GLOBALS['spip_pipeline']['name_of_the_pipeline'] .= "|name_of_the_function"; // Example of adding into the "insert_head" pipeline: $GLOBALS['spip_pipeline']['insert_head'] .= "|name_of_the_function"; function name_of_the_function($flux) { return $flux .= "This text will be appended"; }

The function called must be declared already at the time that the pipeline is called, with the simplest solution being to declare it as above with a name_of_the_function function defined in the options file.

Note that SPIP uses a cache of the pipelines used, and that any new declaration will require this cache to be refreshed. This can be done by navigating to the "Plugin management" page in the private zone (?exec=admin_plugin).

sql_quote

Mark Baber — 2010-05-17T14:04:52Z

The sql_quote() function is used to secure or filter data content (with apostrophes) in order to avoid SQL injection attacks. This function is very important and must be used whenever content is provided by user data entry. The sql_insertq, sql_updateq, and sql_replace functions automatically apply this filtering for any inserted data (but not for the other parameters like $where which ought to be filtered nonetheless anyway).

It accepts 3 parameters:

$val is the expression to be filtered,
$serveur,
$type optional, is the type of value expected. This would equal int for an integer value.

It is used as shown below:

$charstring = sql_quote("David's car"); $fieldname = sql_quote($fieldname); sql_select('column', 'table', 'titre=' . sql_quote($titre)); sql_updateq('table', array('column'=>'value'), 'titre=' . sql_quote($titre));

Whenever a numeric identifier is expected, which is often the case for primary keys, the filtering may simply apply the PHP intval() function (the value zero will be returned if the content passed is not numeric):

$id_table = intval(_request('id_table')); sql_select('column', 'table', 'id_table=' . intval($id));

Processing without AJAX

Mark Baber — 2010-05-17T13:54:23Z

If a form is called using AJAX but then redirects to another page after finishing its processes, this would require Javascript tricks (managed by SPIP) to capture that redirection and effectively send the browser to another URL instead of the normal response.

Whenever a redirection is certain, it is possible to prevent AJAX for the form's processing, while still maintaining it for the verification phase. This means that the form would be reloaded in the event of an error in verifier(), but if the processing is executed, then the whole page will be immediately reloaded.

To do this, you must call the refuser_traiter_formulaire_ajax()function right at the start of the processes:

function formulaires_nom_traiter(){ // Prevent AJAX processing since we know that the form will redirect elsewhere refuser_traiter_formulaire_ajax(); // Execute the processes // Return values return array( 'redirect' => 'Another URL' ); }

Executing the processes

Mark Baber — 2010-05-17T13:44:16Z

Whenever the verification function doesn't return an error, the form then moves on to the traiter() (processing) function. It is in this function that the desired operations should be performed with the data from the form (send an email, update the database, etc.).

The function must return an associative table:

function formulaires_nom_traiter(){ // Execute the processes // Return values return array( 'message_ok' => 'Excellent !', // or perhaps 'message_erreur' => 'Sorry, an error has occurred.' ); }

Important values

Here are some of the values frequently returned:

message_ok is used to return a pleasant message to the user indicating that everything processed normally.
message_erreur, on the other hand, is used to return an error message when the processing didn't work correctly.
editable, as for loading, this is used to display or hide the editable portion of the form. By default it is set to false, but you may assign it a value of true if your form can be used several times in a row.
redirect is a URL which is used to tell SPIP which page it should redirect to after processing the form. By default, the page will loop back to itself.

The formulaire_traiter (form_process) pipeline

Once the formulaires_nom_traiter function has completed, the formulaire_traiter pipeline is executed, thereby enabling other plugins to complete the processes for this form.

AJAX

Mark Baber — 2010-05-17T13:34:39Z

The term AJAX, an acronym for "Asynchronous JavaScript and XML", is used to describe a collection of technologies used to create asynchronous client-server interactions.

These constructions, which make it possible to only request a partial page update from the server (or partial element update), can significantly reduce the data volumes that need to be transmitted and often make an application appear more responsive to its users.