Les travaux programmés sont à tout moment visualisables dans l'espace d'administration via le menu Maintenance > Liste des travaux. La page de suivi permet de forcer l'exécution immédiate d'une tâche, ou de supprimer certaines tâches.

Ajouter un travail dans la file

Avec les arguments :

• $function : le nom de la fonction PHP qui doit être appelée
• $description : une description humainement compréhensible de ce que fait la tache (essentiellement pour l'affichage dans la page de suivi de l'espace privé)
• $arguments (facultatif, vide par défaut) : les arguments qui seront passés à la fonction, sous forme de tableau PHP
• $file (facultatif, vide par défaut) : nom du fichier à inclure. Si le nom finit par un / alors on considère que c'est un répertoire et SPIP fera un charger_fonction($function,$file)
• $no_duplicate (facultatif, false par défaut)
  • si vaut true la tâche ne sera pas ajoutée si elle existe déjà en file d'attente avec la même fonction et les mêmes arguments.
  • si vaut 'function_only' la tâche ne sera pas ajoutée si elle existe déjà en file d'attente avec la même fonction indépendamment de ses arguments
• $time (facultatif, 0 par défaut) indique la date sous forme de timestamp à laquelle la tâche doit être programmée. Si 0 ou une date passée, la tâche sera exécutée aussitôt que possible (en général en fin hit, en asynchrone).
• $priority (facultatif, 0 par défaut) indique un niveau de priorité entre -10 et +10. Les tâches sont exécutées par ordre de priorité décroissante, une fois leur date d'exécution passée. La priorité est surtout utilisée quand une tâche cron indique qu'elle n'a pas fini et doit être relancée : dans ce cas SPIP réduit sa priorité pour être sûr que celle tâche ne monopolise pas la file d'attente.

La fonction renvoie le numéro de travail ajouté ou 0 si aucun travail n'a été ajouté.

Supprimer un travail de la file

$id_job est le numéro du travail en attente, tel que retourné par la fonction job_queue_add

La fonction retourne true si le travail a bien été trouvé et supprimé, false sinon.

Associer un travail à un objet éditorial

Avec les arguments :

• $id_job : le numéro de travail en attente, tel que retourné par la fonction job_queue_add
• $objets une liste d'objets sous la forme d'un tableau d'objets array(array('objet'=>'article','id_objet'=>23),...)

Lorsque des travaux sont associés à un objet, ils apparaissent sur la page de l'espace privé de cet objet, et les auteurs qui ont le droit de modifier l'objet peuvent aussi supprimer le travail avant son exécution.

Insérer

Une nouvelle instance d'un objet éditorial est créée en base par

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...)

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

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 « 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 « autoriser ».

Vérifier une autorisation

La vérification d'une autorisation se fait par un appel de la forme :

La fonction autoriser($faire, $type, $id, $qui, $opt) accepte 5 arguments dont seul le premier est obligatoire :

• $faire est une chaîne qui désigne l'action soumise à autorisation. C'est en règle générale un verbe simple (modifier, creer, supprimer, voir, configurer...), parfois associé à un contexte (les mots sont alors collés : changerlangue, publierdans...).
  Il y a quelques exceptions où le $faire n'est pas un verbe et s'utilise sans aucun autre argument (autoriser('webmestre') par exemple, ou autoriser('ecrire') —qui désigne ici l'espace d'administration et non l'action—).
• $type est une chaîne qui désigne sur quoi porte l'action. C'est en général le type d'un objet éditorial (article, rubrique, mot, groupe-mots, ...).
• $id désigne l'id (la clé primaire) de l'objet sur lequel porte l'action. $id est en général un nombre entier, mais peut être une chaîne si cela correspond à la clé primaire de la table SQL concernée.
• $qui désigne l'auteur (au sens SPIP) qui va faire l'action. Si il n'est pas fourni (ou null dans l'appel de la fonction autoriser, c'est implicitement l'auteur connecté qui est pris en compte. Sinon $qui peut être l'id_auteur d'un auteur dont on veut vérifier les droits, ou un tableau associatif qui décrit l'auteur (tableau qui contient alors les champs de la table spip_auteurs pour l'auteur concerné)
• $opt est un tableau associatif de données supplémentaires contextuelles concernant l'action qui sont parfois utilisées par l'autorisation. Par exemple lorsqu'on veut modifier/publier un article, on appellera autoriser('instituer', 'article', $id_article, null, array('statut' => 'publie'))

La fonction autoriser retourne « true » ou « false » en fonction des droits de l'auteur à faire l'action demandée.

Dans un squelette, la vérification d'une autorisation se fait par la balise #AUTORISER.

Donner une autorisation exceptionnelle

Il arrive qu'on ait besoin de faire une action qui sera soumise à autorisation pour un auteur qui normalement n'en a pas le droit. Cela peut se produire, par exemple, dans le cas d'une action programmée qui sera alors exécutée anonymement.

Dans ce cas, il existe un mécanisme via la fonction autoriser_exception qui donne une autorisation exceptionnelle, le temps de réaliser l'action concernée.

La fonction autoriser_exception($faire, $type, $id, $autoriser) prend 4 arguments :

• $faire avec la même signification que pour autoriser()
• $type avec la même signification que pour autoriser()
• $id avec la même signification que pour autoriser()
• $autoriser qui est un booléen et indique si l'autorisation exceptionnelle est accordée ou non :
  • Lorsque $autoriser vaut « true » ou n'est pas fourni, on accorde une autorisation exceptionnelle : tous les appels suivant à autoriser() avec les mêmes arguments $faire, $type et $id renverront true
  • Lorsque $autoriser vaut « false » cela signifie que l'autorisation revient sous le régime normal et sera vérifiée selon la règle en vigueur (elle peut donc être encore autorisée ou effectivement interdite). Le false n'indique donc pas ici qu'on interdit l'action, mais simplement qu'il n'y a plus d'exception.

Déclarer une nouvelle autorisation

Lorsque la fonction générique autoriser() est appelée, elle cherche une fonction nommée à laquelle déléguer la vérification.

Si aucun $type n'est fourni dans l'appel à autoriser(), la recherche de la fonction se fait dans l'ordre suivant :

• autoriser_$faire
• autoriser_$faire_dist
• autoriser_defaut
• autoriser_defaut_dist

Si un $type est fourni dans l'appel à autoriser(), la recherche se fait dans l'ordre suivant :

• autoriser_$type_$faire
• autoriser_$type_$faire_dist
• autoriser_$type
• autoriser_$type_dist
• autoriser_$faire
• autoriser_$faire_dist
• autoriser_defaut
• autoriser_defaut_dist

Dans les deux cas, la recherche va du plus précis vers le plus général. Cela permet de définir des familles d'autorisation avec une règle générale (pour une action par exemple), que l'on précise ensuite pour certains objets qui suivent une règle différente.

Pour définir une autorisation, il suffit donc de créer une fonction avec l'un des noms de la liste ci-dessus. La fonction recevra en arguments ceux envoyés à la fonction autoriser() et doit renvoyer « true » ou « false ».

On peut définir une autorisation générique. Lorsque c'est une autorisation qui n'est pas encore définie, on la suffixe en général par un _dist qui permet toujours à un webmestre de la surcharger dans son fichier mes_options.php (en déclarant la fonction de même nom, mais sans son suffixe _dist).

Attention : on voit que dans le nom de la fonction, l'ordre de $faire et $type est inversé par rapport à celui de l'appel à autoriser().

À noter également qu'à partir de SPIP 3.0 le $type est présumé correspondre à un objet, et est normalisé lors de l'appel : vérification qu'il correspond bien à un type d'objet et sinon suppression du « s » final. Cela permet d'assurer qu'on appellera bien la bonne fonction d'autorisation même si on utilise un synonyme du $type (syndic au lieu de site par exemple, ou groupes_mot au lieu de groupe_mots qui est une exception de nommage).
Il est cependant possible d'échapper à cette normalisation en préfixant le $type par un '_' (underscore) dans l'appel à autoriser().

Dans tous les cas, tous les autres caractères '_' sont retirés du $type

Ainsi un appel à autoriser('modifier', 'groupes_mots', $id_groupe) délèguera à la fonction autoriser_groupemots_modifier() (ou l'une des variantes selon la règle ci-dessus si cette fonction précise n'existe pas).
Dans les versions antérieures à SPIP 3.0 il convient de toujours faire très attention à bien utiliser le nom de l'objet sans erreur, car sinon l'autorisation par défaut sera appelée ce qui peut conduire à une erreur d'autorisation plus ou moins grave selon le cas.

Exemple de fonction d'autorisation :

Aide au développement

Lors du développement d'un plugin, il peut être utile de comprendre comment sont appelées les autorisations et dans quel ordre d'enchaînement.

Pour cela il suffit d'ajouter la ligne suivante dans le fichier mes_options.php :

Chaque appel à autoriser() sera alors tracé dans le fichier spip.log avec le nom de la fonction appelée et le résultat qu'elle a retourné.

Il arrive souvent que SPIP, ainsi que les plugins, génèrent des bouts de code HTML sur le site public. Avec l'arrivée du HTML5, on a désormais la possibilité de produire du HTML plus sémantique, que ce soit par les nouvelles balises, les nouveaux éléments de formulaire, etc.

Cependant, sil l'on souhaite continuer à avoir un site valide au sens du W3C (organisme de standardisation du langage HTML entre autres), il est nécessaire que l'utilisation de code HTML5 soit accompagnée de la déclaration du doctype suivant :

Cela signifie donc que SPIP et les plugins ne peuvent pas utiliser aveuglément des éléments de HTML5 : il leur faut une indication de la part de la (ou du) webmestre pour savoir quel est le niveau de compatibilité HTML souhaité. Cela est possible depuis SPIP 3.0 par l'apparition d'une nouvelle option de configuration.

Configuration HTML5

Zone de configuration dans SPIP pour autoriser ou non l'utilisation de HTML5.

La balise #HTML5 permet de tenir compte de ce choix :

• Si le HTML5 est autorisé, la balise renvoie un résultat non-vide (espace)
• Si la configuration reste sur HTML4 (valeur par défaut), la balise renvoie un résultat vide. Sur les versions de SPIP inférieures à SPIP 3.0, la balise est inconnue, et renverra donc également un résultat vide. Il est donc possible de l'utiliser n'importe où, quelle que soit la version de SPIP visée : les sites sous SPIP avant 2.2 seront juste considérés comme étant en HTML4.

Exemples d'utilisation

Par exemple, un plugin ou un squelette qui génère une zone de recherche dans un formulaire pourra utiliser la balise de la manière suivante :

Ce code génèrera, si le HTML5 est activé dans la configuration :

et dans le cas contraire :

Autre exemple : définition d'une zone de saisie de formulaire comme obligatoire :

Le résultat sera donc l'un ou l'autre de ceux-ci suivant la configuration :

Support par les navigateurs

Bien sûr, comme toujours en développement web, n'oubliez pas de vérifier quel est le comportement des navigateurs qui ne connaissent pas les balises HTML et attributs que vous souhaitez utiliser.

Il est nécessaire d'être déjà familier avec les formulaires CVT pour créer un formulaire CVT en plusieurs pages.

Nous allons voir comment construire facilement un formulaire d'inscription en 3 pages distinctes, SPIP prenant en charge la partie compliquée qui consiste à mémoriser les données déja saisies pour le traitement final, et à permettre la navigation entre les pages.

Les squelettes de chaque page

Chaque page du formulaire se présente comme un formulaire complet (avec un bouton de validation qui sert à passer à l'étape suivante).

Chacune des étape est numérotée, à partir de 1, et décrite par un fichier squelette indépendant qui implémente un formulaire autonome pour les saisies de cette page.

Pour l'étape 1, le squelette est formulaires/inscription.html.
Pour l'étape 2, le squelette est formulaires/inscription_2.html.
Pour l'étape 3, le squelette est formulaires/inscription_3.html.

Voici par exemple à quoi ressemble la première page de notre formulaire :

Le critère {tri} simplifie la réalisation de listes triables de la même façon que le critère {pagination} simplifie la réalisation de listes paginées.

Dans une boucle simple, il permet de définir le critère de tri en lui indiquant en argument le champ à utiliser par défaut :

Jusque là rien de nouveau par rapport au critère {par}. Mais {tri} peut être associé à la balise #TRI qui permet de générer un lien pour changer le critère de tri. La balise #TRI prend en premier argument le champ de tri, et en second argument le libellé du lien clicable pour utiliser ce champ pour le tri :

Ce faisant l'utilisateur se voit proposer un menu pour modifier le tri de la boucle. Le tri actuellement utilisé est exposé en gras et non clicable, et les tris non utilisés sont des liens clicables.

Si la boucle est dans une inclusion ajax, il suffit de renseigner la classe ajax en troisième argument de la balise #TRI pour que les liens se comportent avec un rechargement partiel de la page :

Le critère {tri} permet également d'indiquer le sens du tri par défaut en second argument. Il faut indiquer la valeur direct ou 1 pour indiquer un tri croissant par défaut, et inverse ou -1 pour un tri décroissant par défaut :

Par ailleurs il est aussi possible de proposer le choix du sens de tri. Cela se fait en passant > pour un tri croissant et < pour un tri décroissant en premier argument de la balise #TRI :

Cela dit, plutôt que de proposer des boutons de tri systématique, une alternative est possible : adapter automatiquement le sens du tri à la colonne utilisée pour le tri. Cela se fait en passant en second argument de la balise tri un tableau avec le sens par défaut pour chaque colonne :

Ainsi quand l'utilisateur choisira le tri par titre, celui-ci sera dans un ordre croissant. Mais quand il choisira la date ou la date de rédaction, le tri se fera dans un ordre décroissant.

Ces boucles ne portent plus exclusivement sur des requêtes SQL, mais peuvent tourner sur toutes sortes de listes de données. Par exemple :
— un tableau de données produit par une fonction quelconque
— le contenu d'un fichier local au format XML, CSV, JSON, YAML, etc.
— une liste de fichiers dans un répertoire du serveur
— une requête sur un webservice
— etc (LDAP...).

Les boucles SQL

Sans surprise, l'itérateur classique de SPIP s'appelle SQL. Il exécute la requête telle que SPIP l'a calculée, et sait parcourir la liste de résultats pour les envoyer à la boucle.

La boucle (DATA)

C'est une boucle capable d'itérer n'importe quel tableau de données. Sa syntaxe de base est la suivante :

Le critère {source format, données} définit les données sur lesquelles la boucle va itérer.

La définition d'une source de données nécessite deux éléments :

— La partie données : cet élément peut être de plusieurs natures :
- un tableau de données, par exemple #ENV*
- le chemin d'un fichier sur le disque dur, ex : sources/definitions.csv
- l'URL d'un fichier ou d'un webservice, ex : http://per.sonn.es/bases/phobia.fr.yaml
- ou encore, une chaîne quelconque que le format saura transformer en tableau de données, ex : "select * from flickr.photos.search where text='spip'"

— La partie format est à prendre dans la liste ci-dessous :
- table (alias array ou tableau), pour un tableau déjà créé
- csv, json, yaml pour un fichier composé dans l'un de ces formats
- file pour boucler sur les lignes d'un fichier
- glob ou pregfiles pour boucler sur les fichiers d'un répertoire (et plus...)
- rss (alias atom) pour lire un flux de nouvelles
- plugins pour lister les plugins actifs sur le site
- yql pour envoyer une requête sur le webservice de Yahoo Query Language
- sql pour envoyer une requête brute au serveur SQL (utiliser {source sql, connecteur:requete} pour envoyer la requête sur une base externe)
- ics pour boucler sur des calendriers (nécessite le plugin icalendar : lire La boucle iCalendar)
- etc.

Tous ces formats sont déjà disponibles, et il est très aisé d'en ajouter un nouveau, en créant une simple fonction inc_FORMAT_to_array($u). A titre d'exemple voici la fonction qui transforme un fichier JSON en tableau de données :

A lire : Exemples de BOUCLE(DATA) .

YQL — Yahoo Query Language

YQL est un webservice permettant d'interroger de façon simple de nombreux sites comme google, twitter, flickr, etc. Avec la boucle (DATA), SPIP facilite grandement son intégration sous forme de boucles : Cf. Exemples de boucles YQL.

Itérateurs PHP

SPIP est capable d'utiliser les itérateurs PHP standards. Il convient de se reporter à leur documentation, qui est souvent très succincte, et de vérifier que les itérateurs en questions sont disponibles sur votre système.

Notons, par exemple, DirectoryIterator, qui permet de lister les fichiers d'un répertoire :

Boucle :

  {pagination 10}
 {valeur!==^\.}{valeur==\.jpg$}
 >[(#VAL{Y-m-d H:i:s}|date{#GETMTIME})] / #VALEUR
 
 

Résultat :

2008-02-01 23:27:23 / arton2135.jpg 2008-08-21 11:12:58 / DSC03420.jpg 2008-08-21 11:13:11 / DSC03421.jpg 2009-08-27 11:20:11 / hash-1.jpg 2009-08-27 11:20:04 / hash.jpg

Il convient d'indiquer à SPIP qu'il s'agit d'un itérateur PHP, en indiquant (php:...) avant le nom de l'itérateur.

Le critère {args xx,yy} définit les arguments que l'on va passer à l'itérateur lors de son initialisation. Pour DirectoryIterator, il s'agit du chemin du répertoire à lister.

Les méthodes de cet itérateur (cf. http://php.net/manual/fr/class.directoryiterator.php) sont disponibles sous forme de balises (ici, #GETMTIME).

Remarque : pour lister le contenu d'un répertoire, le format glob de la boucle (DATA) est sans doute plus facile à utiliser que cet itérateur PHP.

Filtrage, tri, pagination, fusion

Filtres. Comme les boucles SQL, les boucles (DATA) peuvent être filtrées par des critères du type {valeur=x} ; les opérateurs disponibles sont =, >, <, >=, <=, == (expression rationnelle) et LIKE.

Cependant ce filtrage s'effectue non pas en amont lors de la requête, comme en SQL, mais en aval, sur le tableau de données initialement récupéré.

Tris. Les tris {par xx} sont également possibles, avec leur variante {!par xx} pour trier en ordre inverse.

Pagination. La pagination fonctionne normalement, ainsi que le critère offset/limit {a,b}.

Fusion. Le critère {fusion /x/y} fonctionne aussi. Par exemple, pour un fichier d'adresses au format CSV, si l'email est le champ n° 3, on pourra ne retenir qu'un seul enregistrement par email avec la boucle suivante :

La fusion se fait après le tri, et retient le premier élément
rencontré. De cette manière, si un tableau est trie {!par date} puis fusionné sur l'email, l'enregistrement retenu pour chaque email sera le plus récent.

Dans le prochain article, nous verrons des exemples de boucles (DATA).

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 :

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 :

Le 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 :

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 :

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.

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.