source: spip-zone/_plugins_/n-core/trunk/ncore_fonctions.php @ 112829

Last change on this file since 112829 was 112829, checked in by eric@…, 2 years ago

L'argument stockage est toujours optionnel.

  • Property svn:eol-style set to native
File size: 18.5 KB
Line 
1<?php
2/**
3 * Ce fichier contient les filtres de compilation des noisettes appelés par la balise #COMPILER_NOISETTE.
4 *
5 */
6if (!defined('_ECRIRE_INC_VERSION')) {
7        return;
8}
9
10
11// -----------------------------------------------------------------------
12// --------------------- FILTRES TYPES DE NOISETTE -----------------------
13// -----------------------------------------------------------------------
14
15/**
16 * Détermine si le type de noisette spécifié doit être inclus en AJAX ou pas. Cette fonction gère un cache
17 * des indicateurs ajax.
18 *
19 * @package SPIP\NCORE\TYPE_NOISETTE\API
20 *
21 * @api
22 * @filtre
23 *
24 * @uses cache_lire()
25 * @uses cache_ecrire()
26 * @uses ncore_type_noisette_lister()
27 * @uses ncore_type_noisette_initialiser_ajax()
28 *
29 * @param string $plugin
30 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
31 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
32 * @param string        $type_noisette
33 *            Identifiant du type de noisette.
34 * @param string $stockage
35 *        Identifiant du service de stockage à utiliser si précisé.
36 *
37 * @return bool
38 *              `true` si la noisette doit être ajaxée, `false` sinon.
39 */
40function type_noisette_ajaxifier($plugin, $type_noisette, $stockage = '') {
41
42        // On indexe le tableau des indicateurs ajax par le plugin appelant en cas d'appel sur le même hit
43        // par deux plugins différents.
44        static $est_ajax = array();
45
46        if (!isset($est_ajax[$plugin][$type_noisette])) {
47                include_spip('inc/ncore_cache');
48                // On vérifie si on doit recalculer le cache ou pas.
49                if ((_request('var_mode') == 'recalcul')
50                or (defined('_NO_CACHE') and (_NO_CACHE != 0))
51                or (!$est_ajax[$plugin] = cache_lire($plugin, _NCORE_NOMCACHE_TYPE_NOISETTE_AJAX))) {
52                        // On charge l'API de N-Core.
53                        include_spip("ncore/ncore");
54
55                        // On détermine la valeur par défaut de l'ajax des noisettes pour le plugin appelant.
56                        $defaut_ajax = ncore_type_noisette_initialiser_ajax($plugin);
57
58                        // On répertorie la configuration ajax de toutes les noisettes disponibles et on compare
59                        // avec la valeur par défaut configurée pour le service appelant.
60                        if ($ajax_types_noisette = ncore_type_noisette_lister($plugin,'ajax', $stockage)) {
61                                foreach ($ajax_types_noisette as $_type_noisette => $_ajax) {
62                                        $est_ajax[$plugin][$_type_noisette] = ($_ajax == 'defaut')
63                                                ? $defaut_ajax
64                                                : ($_ajax == 'non' ? false : true);
65                                }
66                        }
67
68                        // On vérifie que la noisette demandée est bien dans la liste.
69                        // Si non, on la rajoute en utilisant la valeur ajax par défaut afin de toujours renvoyer
70                        // quelque chose.
71                        if (!isset($est_ajax[$plugin][$type_noisette])) {
72                                $est_ajax[$plugin][$type_noisette] = $defaut_ajax;
73                        }
74
75                        // In fine, on met à jour le cache
76                        cache_ecrire($plugin, _NCORE_NOMCACHE_TYPE_NOISETTE_AJAX, $est_ajax[$plugin]);
77                }
78        }
79
80        return $est_ajax[$plugin][$type_noisette];
81}
82
83/**
84 * Détermine si la noisette spécifiée doit être incluse dynamiquement ou pas. Cette fonction gère un cache
85 * des indicateurs d'inclusion dynamique.
86 *
87 * @package SPIP\NCORE\TYPE_NOISETTE\API
88 *
89 * @api
90 * @filtre
91 *
92 * @uses cache_lire()
93 * @uses cache_ecrire()
94 * @uses ncore_type_noisette_lister()
95 *
96 * @param string $plugin
97 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
98 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
99 * @param string $type_noisette
100 *            Identifiant du type de noisette.
101 * @param string $stockage
102 *        Identifiant du service de stockage à utiliser si précisé.
103 *
104 * @return bool
105 *              `true` si le type de noisette doit être inclus dynamiquement, `false` sinon.
106 */
107function type_noisette_dynamiser($plugin, $type_noisette, $stockage = '') {
108
109        // On indexe le tableau des indicateurs ajax par le plugin appelant en cas d'appel sur le même hit
110        // par deux plugins différents.
111        static $est_dynamique = array();
112
113        if (!isset($est_dynamique[$plugin][$type_noisette])) {
114                include_spip('inc/ncore_cache');
115                // On doit recalculer le cache ou pas.
116                if ((_request('var_mode') == 'recalcul')
117                or (defined('_NO_CACHE') and (_NO_CACHE != 0))
118                or (!$est_dynamique[$plugin] = cache_lire($type_noisette, _NCORE_NOMCACHE_TYPE_NOISETTE_INCLUSION))) {
119                        // On charge l'API de N-Core.
120                        // Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
121                        include_spip("ncore/ncore");
122
123                        // On répertorie la configuration d'inclusion de toutes le types noisettes disponibles et on
124                        // détermine si le type demandé est dynamique ou pas.
125                        if ($inclusion_types_noisette = ncore_type_noisette_lister($plugin, 'inclusion', $stockage)) {
126                                foreach ($inclusion_types_noisette as $_type_noisette => $_inclusion) {
127                                        $est_dynamique[$plugin][$_type_noisette] = ($_inclusion == 'dynamique') ? true : false;
128                                }
129                        }
130
131                        // On vérifie que le type de noisette demandé est bien dans la liste.
132                        // Si non, on le rajoute en utilisant en positionnant l'inclusion dynamique à false ce qui est le défaut.
133                        if (!isset($est_dynamique[$plugin][$type_noisette])) {
134                                $est_dynamique[$plugin][$type_noisette] = false;
135                        }
136
137                        // In fine, on met à jour le cache
138                        cache_ecrire($plugin, _NCORE_NOMCACHE_TYPE_NOISETTE_INCLUSION, $est_dynamique[$plugin]);
139                }
140        }
141
142        return $est_dynamique[$plugin][$type_noisette];
143}
144
145/**
146 * Renvoie le dossier relatif des types de noisette pour le plugin appelant ou la localisation
147 * du type de noisette demandé.
148 * Cette fonction gère le cas particulier de la noisette conteneur fournie par N-Core qui est elle
149 * toujours dans le dossier par défaut de N-Core et n'est donc pas surchargeable.
150 *
151 * @package SPIP\NCORE\TYPE_NOISETTE\API
152 *
153 * @api
154 * @filtre
155 *
156 * @uses ncore_type_noisette_initialiser_dossier()
157 *
158 * @param string $plugin
159 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
160 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
161 * @param string $type_noisette
162 *            Identifiant du type de noisette ou chaine vide si on ne veut que le dossier.
163 *
164 * @return string
165 *        Chemin relatif du dossier où chercher les types de noisette ou du type de noisette demandé.
166 */
167function type_noisette_localiser($plugin, $type_noisette = '') {
168
169        // Si le type de noisette est précisé et correspond à la noisette conteneur fournie par N-Core
170        // alors on impose le dossier à celui par défaut de N-Core.
171        // Sinon on prend le dossier du plugin appelant.
172        include_spip('ncore/ncore');
173        if ($type_noisette == 'conteneur') {
174                $dossier = ncore_type_noisette_initialiser_dossier('ncore');
175        } else {
176                $dossier = ncore_type_noisette_initialiser_dossier($plugin);
177        }
178
179        // Si le type de noisette est vide on ne renvoie que le dossier, sinon on renvoie le chemin de
180        // la noisette.
181        return $dossier . $type_noisette;
182}
183
184
185// -----------------------------------------------------------------------
186// -------------------- FILTRES & BALISES NOISETTES ----------------------
187// -----------------------------------------------------------------------
188include_spip('public/noisette_compiler');
189include_spip('public/noisette_preview');
190include_spip('public/noisette_repertorier');
191
192/**
193 * Renvoie le contexte de la noisette sous la forme d'un tableau éventuellement vide. Cette fonction gère un cache
194 * des contextes non valorisés des types de noisette disponibles.
195 *
196 * @package SPIP\NCORE\NOISETTE\API
197 *
198 * @api
199 * @filtre
200 *
201 * @uses cache_lire()
202 * @uses cache_ecrire()
203 * @uses ncore_type_noisette_lister()
204 *
205 * @param string $plugin
206 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
207 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
208 * @param mixed  $noisette
209 *        Tableau des identifiants de la noisette qui peut prendre la forme d'un tableau avec pour index
210 *        id_noisette, id conteneur et rang_noisette, ce qui permet d'utiliser l'un ou l'autre des identifiants
211 *        de la noisette.
212 * @param string $type_noisette
213 *            Identifiant du type de noisette.
214 * @param array  $environnement
215 *            Tableau de l'environnement reçu par la noisette.
216 * @param string $stockage
217 *        Identifiant du service de stockage à utiliser si précisé.
218 *
219 * @return array
220 *              Le tableau éventuellement vide des éléments de contexte de la noisette.
221 */
222function noisette_contextualiser($plugin, $noisette, $type_noisette, $environnement, $stockage = '') {
223
224        // Initialisation du tableau des contexte générique de chaque type de noisette.
225        static $contextes_type_noisette = array();
226
227        // On initialise le contexte de la noisette a minima.
228        // -- on transmet toujours les identifiants de la noisette id_noisette et couple (id_conteneur, rang) qui sont
229        //    fournis par la balise.
230        $contexte = $noisette ? $noisette : array();
231
232        // Récupération du contexte défini pour le type de noisette. Ce contexte est juste une liste de variables non
233        // valorisées. La valorisation sera faite avec l'environnement.
234        // -- les contextes sont stockés dans un cache dédié.
235        if (!isset($contextes_type_noisette[$plugin][$type_noisette])) {
236                // On vérifie si on doit recalculer le cache le cache ou pas.
237                include_spip('inc/ncore_cache');
238                if ((_request('var_mode') == 'recalcul')
239                or (defined('_NO_CACHE') and (_NO_CACHE != 0))
240                or (!$contextes_type_noisette[$plugin] = cache_lire($plugin, _NCORE_NOMCACHE_TYPE_NOISETTE_CONTEXTE))) {
241                        // On répertorie la configuration du contexte de toutes les noisettes disponibles et on
242                        // le renvoie le résultat tel quel.
243                        include_spip('ncore/ncore');
244                        $contextes_type_noisette[$plugin] = ncore_type_noisette_lister($plugin, 'contexte', $stockage);
245
246                        // On vérifie que le type de noisette demandé est bien dans la liste.
247                        // Si non, on la rajoute en utilisant en positionnant le contexte à tableau vide.
248                        if (!isset($contextes_type_noisette[$plugin][$type_noisette])) {
249                                $contextes_type_noisette[$plugin][$type_noisette] = serialize(array());
250                        }
251
252                        // In fine, on met à jour le cache
253                        cache_ecrire($plugin, _NCORE_NOMCACHE_TYPE_NOISETTE_CONTEXTE, $contextes_type_noisette[$plugin]);
254                }
255        }
256        // -- on inverse les index et valeurs du tableau de contexte pour obtenir un tableau similaire au contexte.
257        $contexte_type_noisette = array_flip(unserialize($contextes_type_noisette[$plugin][$type_noisette]));
258
259        // On construit le contexte final en fonction de celui du type de noisette.
260        // On renvoie systématiquement le contexte minimal déjà initialisé et si le contexte du type de noisette contient:
261        // - aucun => rien de plus.
262        // - env ou vide => l'environnement complet également.
263        // - une liste de variables => on renvoie également l'intersection de cette liste avec l'environnement.
264        if (!isset($contexte_type_noisette['aucun'])) {
265                if (isset($contexte_noisette['env'])) {
266                        $contexte = array_merge($environnement, $contexte);
267                } else {
268                        $contexte = array_merge(array_intersect_key($environnement, $contexte_type_noisette), $contexte);
269                }
270        }
271
272        return $contexte;
273}
274
275
276/**
277 * Encapsule, si demandé, le contenu compile d'une ou d'un ensemble de noisettes dans un balisage HTML
278 * plus ou moins complexe appelé une capsule.
279 * Une noisette conteneur est considérée comme une capsule et donc traitée en tant que tel.
280 *
281 * @package SPIP\NCORE\NOISETTE\API
282 *
283 * @api
284 * @filtre
285 *
286 * @uses ncore_noisette_initialiser_encapsulation()
287 * @uses type_noisette_localiser()
288 *
289 * @param string $plugin
290 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
291 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
292 * @param string $contenu
293 *        Contenu compilé à encapsuler.
294 * @param string $encapsulation
295 *            Indicateur d'encapsulation du contenu par un capsule ou par une noisette conteneur. Prend les valeurs
296 *        `oui`, `non`, `defaut` pour une capsule et `conteneur` pour une noisette conteneur.
297 * @param string $parametres
298 *        Liste des paramètres de l'encapsulation. Pour une capsule, les index sont limités à `type_noisette`,
299 *        `id_noisette` et `css`. Pour une noisette conteneur cette liste correspond au champ `parametres` de la
300 *        noisette et à son type.
301 * @param string $stockage
302 *        Identifiant du service de stockage à utiliser si précisé.
303 *
304 * @return string
305 *              Le contenu fourni encapsulé dans un balisage HTML ou tel que fourni en entrée si pas d'encapsulation.
306 */
307function noisette_encapsuler($plugin, $contenu, $encapsulation, $parametres, $stockage = '') {
308
309        // Initialisation du tableau du HTML des capsules indexé par plugin et nom de capsule.
310        static $defaut_encapsulation = array();
311
312        // Détermination du défaut d'encapsulation.
313        if (!isset($defaut_encapsulation[$plugin])) {
314                $defaut_encapsulation[$plugin] = ncore_noisette_initialiser_encapsulation($plugin);
315        }
316
317        // Une noisette conteneur peut être assimilée à une capsule qui englobe non pas une noisette mais un ensemble
318        // de noisettes. A ce titre, une noisette conteneur n'a jamais de capsule car elle est déjà une capsule.
319        if (($encapsulation == 'oui') 
320        or ($encapsulation == 'conteneur') 
321        or (($encapsulation == 'defaut') and ($defaut_encapsulation[$plugin]))) {
322                // Détermination de la capsule à appliquer
323                if ($encapsulation == 'conteneur') {
324                        // Noisette conteneur:
325                        // La capsule est la noisette elle-même.
326                        $fond_capsule = type_noisette_localiser($plugin, $parametres['type_noisette']);
327                } else {
328                        // Capsule de noisette:
329                        // On utilise soit la capsule propre au type de noisette si elle existe,
330                        // soit on utilise la capsule générique pour toute noisette qui porte le nom 'dist',
331                        // soit on utilise une pseudo-capsule qui englobe la noisette dans un div.
332                        if (find_in_path("capsules/{$parametres['type_noisette']}.html")) {
333                                $fond_capsule = "capsules/{$parametres['type_noisette']}";
334                        } elseif (find_in_path('capsules/dist.html')) {
335                                $fond_capsule = 'capsules/dist';
336                        } else {
337                                $fond_capsule = '';
338                        }
339                }
340
341                // Si on veut insérer la pseudo-capsule (cas le plus fréquent), on accélère le processus en évitant de
342                // faire systématiquement un appel à recuperer_fond(): on construit le HTML.
343                // De fait, le fichier HTML de la pseudo-capsule n'existe pas et n'est donc pas surchargeable.
344                if (!$fond_capsule) {
345                        $capsule =
346'<div class="noisette noisette_' . $parametres['type_noisette'] . ($parametres['css'] ? " {$parametres['css']}" : '') . '">
347        <!--noisettes-->
348</div>';
349                } else {
350                        $capsule = recuperer_fond($fond_capsule, $parametres);
351                }
352
353                // On insère le contenu de la noisette dans la capsule ou la noisette conteneur qui contient toujours
354                // une indication d'insertion explicite.
355                $contenu = str_replace('<!--noisettes-->', $contenu, $capsule);
356        }
357
358        return $contenu;
359}
360
361
362/**
363 * Renvoie une liste de descriptions de noisettes appartenant à un conteneur donné ou pas et éventuellement filtrée
364 * sur certains champs.
365 * Le tableau retourné est indexé soit par identifiant de noisette soit par identifiant du conteneur et rang de la
366 * noisette.
367 *
368 * @package SPIP\NCORE\NOISETTE\API
369 *
370 * @api
371 * @filtre
372 *
373 * @uses ncore_noisette_lister()
374 *
375 * @param string $plugin
376 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
377 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
378 * @param array|string $conteneur
379 *        Tableau descriptif du conteneur ou identifiant du conteneur ou vide si on souhaite adresser tous les
380 *        conteneurs.
381 * @param string $cle
382 *        Champ de la description d'une noisette servant d'index du tableau. On utilisera soit `id_noisette`
383 *        soit `rang_noisette` (défaut).
384 * @param array  $filtres
385 *        Tableau associatif `[champ] = valeur` de critères de filtres sur les descriptions de types de noisette.
386 *        Le seul opérateur possible est l'égalité.
387 * @param string $stockage
388 *        Identifiant du service de stockage à utiliser si précisé.
389 *
390 * @return array
391 *        Tableau des descriptions des noisettes du conteneur indexé par le champ fourni en argument (par défaut le
392 *        rang).
393 */
394function noisette_repertorier($plugin, $conteneur = array(), $cle = 'rang_noisette', $filtres = array(), $stockage = '') {
395
396        // On indexe le tableau des noisettes par le plugin appelant en cas d'appel sur le même hit
397        // par deux plugins différents et aussi par la clé d'indexation.
398        static $noisettes = array();
399
400        if (!isset($noisettes[$plugin][$cle])) {
401                // On charge l'API de N-Core.
402                // Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
403                include_spip("ncore/ncore");
404
405                // On récupère la description complète de tous les types de noisettes détectés par le plugin appelant
406                $noisettes[$plugin][$cle] = ncore_noisette_lister($plugin, $conteneur, '', $cle, $stockage);
407        }
408
409        // Application des filtres éventuellement demandés en argument de la fonction
410        $noisettes_filtrees = $noisettes[$plugin][$cle];
411        if ($filtres) {
412                foreach ($noisettes_filtrees as $_noisette => $_description) {
413                        foreach ($filtres as $_critere => $_valeur) {
414                                if (isset($_description[$_critere]) and ($_description[$_critere] != $_valeur)) {
415                                        unset($noisettes_filtrees[$_noisette]);
416                                        break;
417                                }
418                        }
419                }
420        }
421
422        return $noisettes_filtrees;
423}
424
425 
426// -----------------------------------------------------------------------
427// --------------------- FILTRES & BALISES CONTENEURS --------------------
428// -----------------------------------------------------------------------
429include_spip('public/conteneur_identifier');
430
431/**
432 * Calcule l'identifiant unique pour le conteneur sous forme de chaine.
433 * Cette fonction est juste un wrapper pour le service ncore_conteneur_identifier().
434 * Elle est utilisée par les balises #NOISETTE_COMPILER et #CONTENEUR_IDENTIFIER
435 *
436 * @package SPIP\NCORE\CONTENEUR\API
437 *
438 * @api
439 * @filtre
440 *
441 * @uses ncore_conteneur_identifier()
442 *
443 * @param string $plugin
444 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
445 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
446 * @param array  $conteneur
447 *        Tableau associatif descriptif du conteneur.
448 * @param string $stockage
449 *        Identifiant du service de stockage à utiliser si précisé.
450 *
451 * @return string
452 *        Identifiant du conteneur ou chaine vide en cas d'erreur.
453 */
454function conteneur_identifier($plugin, $conteneur, $stockage = '') {
455
456        include_spip('ncore/ncore');
457        $identifiant = ncore_conteneur_identifier($plugin, $conteneur, $stockage);
458
459        return $identifiant;
460}
Note: See TracBrowser for help on using the repository browser.