declarer_tables_interfaces

Ce pipeline sert à déclarer des informations relatives aux tables SQL ou à certains champs de ces tables. Il permet de compléter les informations données par ecrire/public/interfaces.php

La fonction prend en paramètre le tableau des éléments déclarés, souvent nommé $interface et doit le retourner. Ce tableau est composé de différents éléments eux aussi tabulaires :

• table_des_tables déclare des alias de tables SQL,
• exceptions_des_tables attribue des alias de colonne SQL sur une table donnée,
• table_titre indique la colonne SQL d’un objet servant à définir le titre pour certains types de jeux d’URL
• table_date indique une colonne SQL de type date pour une table SQL donnée, permettant d’utiliser dessus des critères spécifiques (age, age_relatif, ...)
• tables_jointures explicite des jointures possibles entre tables SQL
• exceptions_des_jointures crée des alias de colonnes SQL issus d’une jointure
• table_des_traitements indique des filtres à appliquer systématiquement sur des balises SPIP.

table_des_tables

Déclare des alias pour des tables SQL, relatifs aux déclarations données dans les tables principales ou auxiliaires.

En général, tout plugin proposant un nouvel objet éditorial déclare également un alias identique au nom de l’objet. Cela permet d’écrire des boucles <BOUCLEx(NOM)>, identiques à <BOUCLEx(spip_nom)> (qui indique simplement le nom de la table SQL).

// 'nom_declare' = 'spip_rubriques', mais sans le prefixe 'spip_'
$interface['table_des_tables']['alias'] = 'nom_declare';
// exemples
$interface['table_des_tables']['articles'] = 'articles'; // boucles ARTICLES sur spip_articles
$interface['table_des_tables']['billets'] = 'articles'; // boucles BILLETS sur spip_articles

exceptions_des_tables

De la même manière que la déclaration d’alias de table SQL, il est possible de déclarer des alias de colonnes SQL. Ces alias peuvent aussi forcer une jointure sur une autre table.

// balise #COLONNE_ALIAS ou critere {colonne_alias} dans la boucle concernee
$interface['exceptions_des_tables']['alias']['colonne_alias'] = 'colonne';
$interface['exceptions_des_tables']['alias']['colonne_alias'] = array('table', 'colonne');
// exemples
$interface['exceptions_des_tables']['breves']['date'] = 'date_heure'; 
$interface['exceptions_des_tables']['billets']['id_billet'] = 'id_article';
$interface['exceptions_des_tables']['documents']['type_document'] = array('types_documents'
, 'titre');
// permet d'utiliser les criteres racine, meme_parent, id_parent
$interface['exceptions_des_tables']['evenements']['id_parent'] = 'id_evenement_source';
$interface['exceptions_des_tables']['evenements']['id_rubrique'] = array('spip_articles', 'id_rubrique');

table_titre

Indique quel champ sera utilisé pour générer des titres pour certains jeux d’URL (propre, arborescent...). La chaîne transmise est une déclaration de sélection SQL (SELECT), qui doit renvoyer 2 colonnes (ou alias de colonne SQL) : « titre » et « lang ». Lorsque l’objet n’a pas de champ « lang » correspondant, on doit donc renvoyer '' AS lang.

$interface['table_titre']['alias']= "colonne_titre AS titre, colonne_lang AS lang";
// exemples
$interface['table_titre']['mots']= "titre, '' AS lang";
$interface['table_titre']['breves']= 'titre , lang';

Lorsqu’un objet a déclaré son titre, le générateur d’URL peut créer de belles URL automatiquement (en fonction du jeu d’URL utilisé par le site).

table_date

Cette information permet de déclarer certaines colonnes SQL comme des entrées de type date. Le compilateur de SPIP pourra alors appliquer des critères spécifiques à ces types de champs, tel que « age », « age_relatif », « jour_relatif »... Il n’y a qu’un seul champ déclaré de type date possible par table.

$interface['table_date']['alias'] = 'colonne';
// exemples
$interface['table_date']['articles']='date';
$interface['table_date']['evenements'] = 'date_debut';

tables_jointures

Ces déclarations permettent au compilateur de déterminer explicitement les jointures possibles lorsqu’une boucle sur une table demande un champ (balise ou critère) inconnu.

Le compilateur sait retrouver de façon implicite certaines jointures (sans les déclarer donc) en recherchant la colonne demandée dans les autres tables SQL qu’il connait. Le compilateur ne cherche pas sur toutes les tables, mais uniquement sur celles ayant des colonnes spécifiques communes :

• même nom que la clé primaire,
• même nom qu’une colonne déclarée en jointure potentielle dans le descriptif join des tables principales ou auxiliaires.

Dans de nombreux cas, il est utile et préférable de déclarer de façon explicite au compilateur les jointures qu’il peut tenter lorsqu’un champ inconnu sur une table se présente à lui. C’est le but de cette déclaration. L’ordre des déclarations a parfois son importance, puisque dès que le compilateur trouvera le champ recherché dans une des tables possibles à joindre, il liera alors cette table. Même si le champ voulu se trouvait dans la table déclarée ensuite.

$interface['tables_jointures']['spip_nom'][] = 'autre_table';
$interface['tables_jointures']['spip_nom']['colonne'] = 'autre_table';
// exemples
// {id_mot} sur ARTICLES
$interface['tables_jointures']['spip_articles'][]= 'mots_articles';
$interface['tables_jointures']['spip_articles'][]= 'mots';
// jointures evenements (plugin agenda) sur les mots ou articles
$interface['tables_jointures']['spip_evenements'][]= 'mots'; // a placer avant la jointure sur articles
$interface['tables_jointures']['spip_evenements'][] = 'articles';
$interface['tables_jointures']['spip_evenements'][] = 'mots_evenements';
// jointures articles vers evenements
$interface['tables_jointures']['spip_articles'][] = 'evenements';

La plupart du temps, aidé aussi de la description « exceptions_des_jointures » expliqué ensuite, cela suffit pour qu’une boucle SPIP sache calculer les jointures qui lui sont nécessaires pour afficher les différentes balises demandées. Si ce n’est toujours pas suffisant, ne pas oublier que les squelettes aussi peuvent indiquer les jointures qu’ils souhaitent avec les boucles et critères (cf. Forcer des jointures).

exceptions_des_jointures

Cette définition permet d’attribuer un alias de colonne créant une jointure sur une table pour récupérer un autre champ, si la jointure est réalisable. C’est un peu le pendant de « exception_des_tables » déclarant une jointure, mais non spécifique à une table donnée. On pourra alors utiliser cet alias comme balise SPIP ou comme critère de boucle.

Notons que lorsqu’on utilise ces jointures uniquement comme critère de boucle tel que {titre_mots=xx}, il est préférable d’écrire {mots.titre=xx}, plus générique et qui ne nécessite pas de déclaration.

$interface['exceptions_des_jointures']['colonne_alias'] = array('table', 'colonne');
// exemples
$interface['exceptions_des_jointures']['titre_mot'] = array('spip_mots', 'titre');

Un cas particulier existe : un troisième argument peut être donné contenant le nom de la fonction qui va créer la jointure. C’est un usage rare, utilisé par le plugin « Forms & Tables »

// cas particulier
$interface['exceptions_des_jointures']['forms_donnees']['id_mot'] = array('spip_forms_donnees_champs', 'valeur', 'forms_calculer_critere_externe');

table_des_traitements

Cette description est très utile ; elle permet de définir des traitements systématiques (filtres) sur certaines balises de SPIP. L’étoile (#BALISE*) désactive ces traitements.

Concrètement, pour chaque balise, ou couple balise / boucle, les fonctions indiquées seront exécutées. %s sera remplacé par le contenu réel que retourne la balise.

Deux constantes sont à disposition pour les usages les plus fréquents :

// traitements typographiques
define('_TRAITEMENT_TYPO', 'typo(%s, "TYPO", $connect)');
// traitements des raccourcis SPIP ([->artXX], <cadre>, {{}}, ...)
define('_TRAITEMENT_RACCOURCIS', 'propre(%s, $connect)');

$interface['table_des_traitements']['BALISE'][]= 'filtre_A(%s)';
$interface['table_des_traitements']['BALISE'][]= 'filtre_B(filtre_A(%s))';
$interface['table_des_traitements']['BALISE'][]= _TRAITEMENT_TYPO;
$interface['table_des_traitements']['BALISE'][]= _TRAITEMENT_RACCOURCIS;
$interface['table_des_traitements']['BALISE']['boucle']= _TRAITEMENT_TYPO;
// exemples dans SPIP
$interface['table_des_traitements']['BIO'][]= _TRAITEMENT_RACCOURCIS;
$interface['table_des_traitements']['CHAPO'][]= _TRAITEMENT_RACCOURCIS;
$interface['table_des_traitements']['DATE'][]= 'normaliser_date(%s)';
$interface['table_des_traitements']['ENV'][]= 'entites_html(%s,true)';
// exemples dans le plugin d'exemple "chat"
$interface['table_des_traitements']['RACE']['chats'] = _TRAITEMENT_TYPO;
$interface['table_des_traitements']['INFOS']['chats'] = _TRAITEMENT_RACCOURCIS;

Un exemple très souvent utile est la suppression automatique des numéros sur des titres de rubriques. Cela peut être réalisé comme ceci dans son fichier config/mes_options.php (ou en utilsant ce pipeline dans un plugin évidemment !) :

// version simple
$GLOBALS['table_des_traitements']['TITRE'][]= 'typo(supprimer_numero(%s), "TYPO", $connect)';

// version complexe (ne pas ecraser la definition existante)
if (isset($GLOBALS['table_des_traitements']['TITRE'][0])) {
	$s = $GLOBALS['table_des_traitements']['TITRE'][0];
} else {
	$s = '%s';
}
$GLOBALS['table_des_traitements']['TITRE'][0] = str_replace('%s', 'supprimer_numero(%s)', $s);