spip-contrib-extensions
/
n-core
102
2
Fork 0
Code Issues 1 Pull Requests Releases Wiki Activity
Browse Source

Conteneur et PHPDoc

svn/root/tags/v0.10.0
eric@smellup.net 6 years ago
parent
3882878b08
commit
d57506ab01
2 changed files with 62 additions and 64 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 38
      inc/ncore_noisette.php
  2. 88
      ncore/ncore.php

38
inc/ncore_noisette.php
Unescape View File

@ -1,7 +1,7 @@
<?php
/**
* Ce fichier contient l'API N-Core de gestion des noisettes, c'est-à-dire les instances paramétrées
* de types de noisette affectées à un squelette.
* de types de noisette affectées à un conteneur.
*
* @package SPIP\NCORE\API\NOISETTE
*/
@ -11,7 +11,7 @@ if (!defined('_ECRIRE_INC_VERSION')) {
/**
* Ajoute à un squelette contextualisé, à un rang donné ou en dernier rang, une noisette d'un type donné.
* Ajoute à un conteneur, à un rang donné ou en dernier rang, une noisette d'un type donné.
* La fonction met à jour les rangs des autres noisettes si nécessaire.
*
* @api
@ -76,7 +76,7 @@ function noisette_ajouter($plugin, $type_noisette, $conteneur, $rang = 0, $stock
// Ce sont ces fonctions qui aiguillent ou pas vers un service spécifique du plugin.
include_spip('ncore/ncore');
// On récupère les noisettes déjà affectées au squelette contextualisé sous la forme d'un tableau indexé
// On récupère les noisettes déjà affectées au conteneur sous la forme d'un tableau indexé
// par le rang de chaque noisette.
$noisettes = ncore_noisette_lister($plugin, $conteneur, '', 'rang', $stockage);
@ -112,7 +112,7 @@ function noisette_ajouter($plugin, $type_noisette, $conteneur, $rang = 0, $stock
}
/**
* Supprime une noisette donnée du squelette contextualisé auquel elle est associée.
* Supprime une noisette donnée du conteneur auquel elle est associée.
* La fonction met à jour les rangs des autres noisettes si nécessaire.
*
* @api
@ -146,11 +146,11 @@ function noisette_supprimer($plugin, $noisette, $stockage = '') {
// L'identifiant d'une noisette peut être fourni de deux façons :
// - par une valeur unique, celle créée lors de l'ajout et qui peut-être un entier (id d'une table SPIP) ou
// une chaine unique par exemple générée par uniqid().
// - ou par un tableau à trois entrées fournissant le squelette, le contexte d'utilisation et le rang
// (qui est unique pour un squelette contextualisé donné).
// - ou par un tableau à deux entrées fournissant le conteneur et le rang dans le conteneur
// (qui est unique pour un conteneur donné).
if (!empty($noisette) and (is_string($noisette) or is_numeric($noisette) or is_array($noisette))) {
// Avant de supprimer la noisette on sauvegarde sa description.
// Cela permet de conserver le rang, le squelette et le contexte indépendamment de l'identifiant
// Cela permet de conserver le rang et le conteneur indépendamment de l'identifiant
// utilisé pour spécifier la noisette.
$description = ncore_noisette_decrire($plugin, $noisette, $stockage);
@ -158,7 +158,7 @@ function noisette_supprimer($plugin, $noisette, $stockage = '') {
// destockage de choisir la méthode d'identification la plus adaptée.
$retour = ncore_noisette_destocker($plugin, $description, $stockage);
// On récupère les noisettes restant affectées au squelette contextualisé sous la forme d'un tableau indexé par rang.
// On récupère les noisettes restant affectées au conteneur sous la forme d'un tableau indexé par rang.
$autres_noisettes = ncore_noisette_lister(
$plugin,
unserialize($description['conteneur']),
@ -184,7 +184,7 @@ function noisette_supprimer($plugin, $noisette, $stockage = '') {
/**
* Retourne, pour une noisette donnée, la description complète ou seulement un champ précis.
* Les champs textuels peuvent subir une traitement typo si demandé.
* Les champs textuels peuvent subir un traitement typo si demandé.
*
* @api
* @uses ncore_squelette_identifier()
@ -213,7 +213,8 @@ function noisette_supprimer($plugin, $noisette, $stockage = '') {
function noisette_lire($plugin, $noisette, $information = '', $traiter_typo = false, $stockage = '') {
// On indexe le tableau des descriptions par le plugin appelant en cas d'appel sur le même hit
// par deux plugins différents. On gère un tableau par type d'identification (id noisette ou couple squelette/rang).
// par deux plugins différents.
// En outre, on gère un tableau par type d'identification, id noisette ou couple (conteneur, rang).
static $description_noisette_par_id = array();
static $description_noisette_par_rang = array();
@ -252,7 +253,8 @@ function noisette_lire($plugin, $noisette, $information = '', $traiter_typo = fa
}
}
// Sauvegarde de la description de la page pour une consultation ultérieure dans le même hit.
// Sauvegarde de la description de la noisette pour une consultation ultérieure dans le même hit
// en suivant le type d'identification.
if (is_array($noisette)) {
$description_noisette_par_rang[$plugin][$id_conteneur][$noisette['rang']] = $description;
} else {
@ -281,7 +283,7 @@ function noisette_lire($plugin, $noisette, $information = '', $traiter_typo = fa
}
/**
* Déplace une noisette donnée au sein d’un squelette contextualisé.
* Déplace une noisette donnée au sein d’un conteneur.
* La fonction met à jour les rangs des autres noisettes si nécessaire.
*
* @api
@ -316,8 +318,8 @@ function noisette_deplacer($plugin, $noisette, $rang_destination, $stockage = ''
// L'identifiant d'une noisette peut être fourni de deux façons :
// - par une valeur unique, celle créée lors de l'ajout et qui peut-être un entier (id d'une table SPIP) ou
// une chaine unique par exemple générée par uniqid().
// - ou par un tableau à trois entrées fournissant le squelette, le contexte et le rang
// (qui est unique pour un squelette donné).
// - ou par un tableau à deux entrées fournissant le conteneur et le rang
// (qui est unique pour un conteneur donné).
if (!empty($noisette) and (is_string($noisette) or is_numeric($noisette) or is_array($noisette))) {
// Avant de deplacer la noisette on sauvegarde sa description et son rang origine.
$description = ncore_noisette_decrire($plugin, $noisette, $stockage);
@ -325,7 +327,7 @@ function noisette_deplacer($plugin, $noisette, $rang_destination, $stockage = ''
// Si les rangs origine et destination sont identiques on ne fait rien !
if ($rang_destination != $rang_origine) {
// On récupère les noisettes affectées au même squelette sous la forme d'un tableau indexé par le rang.
// On récupère les noisettes affectées au même conteneur sous la forme d'un tableau indexé par le rang.
$noisettes = ncore_noisette_lister(
$plugin,
unserialize($description['conteneur']),
@ -334,14 +336,14 @@ function noisette_deplacer($plugin, $noisette, $rang_destination, $stockage = ''
$stockage
);
// On vérifie que le rang destination soit bien compris entre 1 et le rang max, sinon on le force à une
// On vérifie que le rang destination est bien compris entre 1 et le rang max, sinon on le force à l'une
// des bornes.
$rang_destination = max(1, $rang_destination);
$rang_max = $noisettes ? max(array_keys($noisettes)) : 0;
$rang_destination = min($rang_max, $rang_destination);
// Suivant la position d'origine et de destination de la noisette déplacée on trie les noisettes
// du squelette contextualisé.
// du conteneur.
if ($rang_destination < $rang_origine) {
krsort($noisettes);
} else {
@ -377,7 +379,7 @@ function noisette_deplacer($plugin, $noisette, $rang_destination, $stockage = ''
/**
* Supprime toutes les noisettes d’un squelette contextualisé.
* Supprime toutes les noisettes d’un conteneur.
*
* @api
* @uses ncore_noisette_destocker()

88
ncore/ncore.php
Unescape View File

@ -222,7 +222,7 @@ function ncore_type_noisette_lister($plugin, $information = '', $stockage = '')
// -----------------------------------------------------------------------
/**
* Stocke la description d'une nouvelle noisette et calcule son identifiant unique ou met à jour les paramètres
* Stocke la description d'une nouvelle noisette et calcule son identifiant unique, ou met à jour les paramètres
* d'affichage d'une noisette existante.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
@ -240,7 +240,7 @@ function ncore_type_noisette_lister($plugin, $information = '', $stockage = '')
* Identifiant du service de stockage à utiliser si précisé. Dans ce cas, ni celui du plugin ni celui de N-Core
* ne seront utilisés. En général, cet identifiant est le préfixe du plugin fournissant le stockage.
*
* @return mixed
* @return int|string
* Id de la noisette de type entier ou chaine.
* Le stockage N-Core renvoie lui une chaine construite à partir du plugin et de la fonction uniqid().
*/
@ -257,16 +257,16 @@ function ncore_noisette_stocker($plugin, $description, $stockage = '') {
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// N-Core calcule un identifiant unique pour la noisette qui sera stocké à l'index 'id_noisette' et qui
// vaudra uniqid() avec comme préfixe le plugin appelant.
// [conteneur][rang] = description
// N-Core calcule un identifiant unique pour la noisette qui sera stocké à l'index 'id_noisette' de sa
// description et qui vaudra uniqid() avec comme préfixe le plugin appelant.
// On lit la meta de stockage des noisettes pour le plugin appelant.
include_spip('inc/config');
$noisettes = lire_config("${plugin}_noisettes", array());
// Détermination de l'identifiant du squelette contextualisé. Le squelette et le contexte font partie de
// la description, le contexte est lui sérialisé.
// Détermination de l'identifiant du conteneur. Le conteneur est un tableau sérialisé qui fait partie
// de la description.
$id_conteneur = ncore_conteneur_identifier(
$plugin,
unserialize($description['conteneur']),
@ -276,14 +276,13 @@ function ncore_noisette_stocker($plugin, $description, $stockage = '') {
if (empty($description['id_noisette'])) {
// Ajout de la noisette :
// -- la description est complète à l'exception de l'id unique qui est créé à la volée
// -- et on range la noisette avec les noisettes affectées au même squelette contextualisé
// en fonction de son rang.
// -- et on range la noisette avec les noisettes affectées au même conteneur en fonction de son rang.
$description['id_noisette'] = uniqid("${plugin}_");
$noisettes[$id_conteneur][$description['rang']] = $description;
} else {
// Modification de la noisette :
// -- les informations identifiant sont toujours fournies, à savoir, l'id, le squelette, le contexte et le rang.
// -- on utilise le squelette contextualisé et le rang pour se positionner sur la noisette concernée.
// -- les identifiants de la noisette sont toujours fournies, à savoir, l'id, le conteneur et le rang.
// -- on utilise le conteneur et le rang pour se positionner sur la noisette concernée.
// -- Les modifications ne concernent que les paramètres d'affichage, cette fonction n'est jamais utilisée
// pour le changement de rang.
if (isset($noisettes[$id_conteneur][$description['rang']])) {
@ -306,7 +305,7 @@ function ncore_noisette_stocker($plugin, $description, $stockage = '') {
/**
* Positionne une noisette à un rang différent que celui qu'elle occupe dans le squelette contextualisé.
* Positionne une noisette à un rang différent que celui qu'elle occupe dans le conteneur.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
*
@ -319,7 +318,7 @@ function ncore_noisette_stocker($plugin, $description, $stockage = '') {
* @param array $description
* Description complète de la noisette.
* @param int $rang_destination
* Position à laquelle ranger la noisette au sein du squelette contextualisé.
* Position à laquelle ranger la noisette au sein du conteneur.
* @param string $stockage
* Identifiant du service de stockage à utiliser si précisé. Dans ce cas, ni celui du plugin ni celui de N-Core
* ne seront utilisés. En général, cet identifiant est le préfixe du plugin fournissant le stockage.
@ -343,23 +342,23 @@ function ncore_noisette_ranger($plugin, $description, $rang_destination, $stocka
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// [conteneur][rang] = description
// On lit la meta de stockage des noisettes pour le plugin appelant.
include_spip('inc/config');
$noisettes = lire_config("${plugin}_noisettes", array());
// Détermination de l'identifiant du squelette contextualisé. Le squelette et le contexte font partie de
// la description, le contexte est lui sérialisé.
// Détermination de l'identifiant du conteneur. Le conteneur est un tableau sérialisé qui fait partie
// de la description.
$id_conteneur = ncore_conteneur_identifier(
$plugin,
unserialize($description['conteneur']),
$stockage
);
// On ajoute la noisette au rang choisi même si on doit écraser un index existant.
// Il est donc nécessaire de gérer la collision en amont de cette fonction.
// Par contre, l'ancien rang de la noisette est supprimé sauf si celui-ci est à zéro.
// On ajoute la noisette au rang choisi même si on doit écraser un index existant:
// -- Il est donc nécessaire de gérer la collision en amont de cette fonction.
// -- Par contre, l'ancien rang de la noisette est supprimé sauf si celui-ci est à zéro.
$rang_source = $description['rang'];
$description['rang'] = $rang_destination;
$noisettes[$id_conteneur][$rang_destination] = $description;
@ -376,8 +375,7 @@ function ncore_noisette_ranger($plugin, $description, $rang_destination, $stocka
}
/**
* Retire une noisette donnée de son squelette contextualisé ou retire l'ensemble des noisettes
* d'un squelette contextualisé de l'espace de stockage.
* Retire, de l'espace de stockage, une noisette donnée de son conteneur ou l'ensemble des noisettes d'un conteneur.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
*
@ -388,7 +386,7 @@ function ncore_noisette_ranger($plugin, $description, $rang_destination, $stocka
* Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
* un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
* @param array|string $description
* Description complète de la noisette ou identifiant du squelette contextualisé.
* Description complète de la noisette ou identifiant du conteneur.
* @param string $stockage
* Identifiant du service de stockage à utiliser si précisé. Dans ce cas, ni celui du plugin ni celui de N-Core
* ne seront utilisés. En général, cet identifiant est le préfixe du plugin fournissant le stockage.
@ -412,14 +410,14 @@ function ncore_noisette_destocker($plugin, $description, $stockage = '') {
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// -- $description est soit le tableau descriptif de la noisette, soit le tableau formé uniquement du couple
// (squelette, contexte) et dans ce cas, il faut supprimer toutes les noisettes du squelette contextualisé.
// [conteneur][rang] = description
// -- $description est soit le tableau descriptif de la noisette, soit le conteneur, et dans ce cas, il faut
// supprimer toutes les noisettes du conteneur.
include_spip('inc/config');
$meta_noisettes = lire_config("${plugin}_noisettes", array());
// Détermination de l'identifiant du squelette contextualisé. Le squelette et le contexte font partie de
// la description, le contexte est lui sérialisé.
// Détermination de l'identifiant du conteneur. Le conteneur est un tableau sérialisé qui fait partie
// de la description.
$id_conteneur = ncore_conteneur_identifier(
$plugin,
unserialize($description['conteneur']),
@ -429,13 +427,14 @@ function ncore_noisette_destocker($plugin, $description, $stockage = '') {
if (!empty($description['id_noisette']) and isset($meta_noisettes[$id_conteneur][$description['rang']])) {
// On supprime une noisette donnée.
unset($meta_noisettes[$id_conteneur][$description['rang']]);
// Si c'était la dernière noisette il faut aussi supprimer l'index correspondant au squelette contextualisé.
// Si c'est la dernière noisette du conteneur il faut aussi supprimer l'index correspondant au conteneur.
if (!$meta_noisettes[$id_conteneur]) {
unset($meta_noisettes[$id_conteneur]);
}
ecrire_config("${plugin}_noisettes", $meta_noisettes);
$retour = true;
} elseif (isset($meta_noisettes[$id_conteneur])) {
// On supprime toutes les noisettes du conteneur.
unset($meta_noisettes[$id_conteneur]);
ecrire_config("${plugin}_noisettes", $meta_noisettes);
$retour = true;
@ -447,9 +446,8 @@ function ncore_noisette_destocker($plugin, $description, $stockage = '') {
/**
* Renvoie une donnée ou toute la description des noisettes d'un squelette contextualisé ou de tous les squelettes
* contextualisés.
* Le tableau retourné est indexé soit par identifiant de noisette soit par squelette contextualisé et rang.
* Renvoie un champ ou toute la description des noisettes d'un conteneur ou de tous les conteneurs.
* Le tableau retourné est indexé soit par identifiant de noisette soit par conteneur et rang.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
*
@ -494,12 +492,12 @@ function ncore_noisette_lister($plugin, $conteneur = array(), $information = '',
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// [conteneur][rang] = description
include_spip('inc/config');
$meta_noisettes = lire_config("${plugin}_noisettes", array());
if ($conteneur) {
// Détermination de l'identifiant du squelette contextualisé.
// Détermination de l'identifiant du conteneur.
$id_conteneur = ncore_conteneur_identifier($plugin, $conteneur, $stockage);
if (!empty($meta_noisettes[$id_conteneur])) {
$noisettes = $meta_noisettes[$id_conteneur];
@ -526,8 +524,8 @@ function ncore_noisette_lister($plugin, $conteneur = array(), $information = '',
/**
* Renvoie la description brute d'une noisette sans traitement typo ni désérialisation des champs de type
* tableau sérialisé.
* Renvoie la description brute d'une noisette sans traitement typo des champs textuels ni désérialisation
* des champs de type tableau sérialisé.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
*
@ -563,7 +561,7 @@ function ncore_noisette_decrire($plugin, $noisette, $stockage = '') {
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// [conteneur][rang] = description
include_spip('inc/config');
$meta_noisettes = lire_config("${plugin}_noisettes", array());
@ -588,14 +586,14 @@ function ncore_noisette_decrire($plugin, $noisette, $stockage = '') {
}
} else {
if (isset($noisette['squelette'], $noisette['contexte'], $noisette['rang'])) {
// Détermination de l'identifiant du squelette contextualisé.
// Détermination de l'identifiant du conteneur.
$id_conteneur = ncore_conteneur_identifier(
$plugin,
$noisette['conteneur'],
$stockage
);
if (!empty($meta_noisettes[$id_conteneur][$noisette['rang']])) {
// L'identifiant est un tableau associatif fournissant le squelette contextualisé et le rang.
// L'identifiant est un tableau associatif fournissant le conteneur et le rang.
// Comme la meta de N-Core est structurée ainsi c'est la méthode la plus adaptée pour adresser
// le stockage de N-Core.
$description = $meta_noisettes[$id_conteneur][$noisette['rang']];
@ -609,7 +607,7 @@ function ncore_noisette_decrire($plugin, $noisette, $stockage = '') {
}
/**
* Construit un identifiant unique pour le squelette et son contexte sous forme de chaine.
* Construit un identifiant unique pour le conteneur sous forme de chaine.
* Cette fonction est juste un aiguillage vers la fonction éventuelle du plugin utilisateur
* car N-Core ne fournit pas de calcul par défaut.
*
@ -630,16 +628,14 @@ function ncore_noisette_decrire($plugin, $noisette, $stockage = '') {
* ne seront utilisés. En général, cet identifiant est le préfixe du plugin fournissant le stockage.
*
* @return string
* Identifiant du squelette contextualisé.
* Identifiant du conteneur ou chaine vide en cas d'erreur.
*/
function ncore_conteneur_identifier($plugin, $conteneur, $stockage) {
// Il faut calculer l'identifiant du squelette contextualisé pour accéder à la bonne liste
// de noisettes. N-Core ne propose pas de fonction par défaut car l'élaboration de l'identifiant
// en fonction du contexte est totalement spécifique au plugin utilisateur.
// Il est donc indispensable que le plugin qui nécessite l'utilisation d'un contexte propose la
// fonction de calcul associée sinon le contexte ne sera pas pris en compte et seul l'identifiant
// du squelette sera retourné.
// Il faut calculer l'identifiant du conteneur pour accéder à la bonne liste de noisettes.
// N-Core ne propose pas de fonction par défaut car l'élaboration de l'identifiant est totalement spécifique
// au plugin utilisateur.
// Il est donc indispensable que le plugin utilisateur propose toujours une fonction de calcul de l'identifiant.
$id_conteneur = '';
if ($conteneur) {
include_spip('inc/ncore_utils');

Write Preview
Loading…
Cancel
Save