Browse Source

Avancée sur l'API de gestion des noisettes.

svn/attic/tags/v010/106508
eric@smellup.net 5 years ago
parent
commit
38bcca1cf1
  1. 162
      inc/ncore_noisette.php
  2. 17
      inc/ncore_type_noisette.php
  3. 198
      ncore/ncore.php

162
inc/ncore_noisette.php

@ -24,7 +24,7 @@ if (!defined('_ECRIRE_INC_VERSION')) {
* @param string $type_noisette
* Identifiant du type de noisette à ajouter au squelette.
* @param string $squelette
* Nom du bloc où ajouter la noisette.
* Chemin relatif du squelette où ajouter la noisette.
* @param int $rang
* Rang dans le squelette où insérer la noisette. Si l'argument n'est pas fourni ou est égal à 0 on insère la
* noisette en fin de bloc.
@ -77,14 +77,16 @@ function noisette_ajouter($plugin, $type_noisette, $squelette, $rang = 0, $stock
// On calcule le rang max déjà utilisé.
$rang_max = $noisettes ? max(array_column($noisettes, 'rang')) : 0;
if (!$rang) {
// Si, le rang est nul, on positionne la noisette à ajouter au rang max + 1.
if (!$rang or ($rang and ($rang > $rang_max))) {
// Si, le rang est nul ou si il est strictement supérieur au rang_max, on positionne la noisette
// à ajouter au rang max + 1.
// En effet, si le rang est supérieur au rang max c'est que la nouvelle noisette est ajoutée
// après les noisettes existantes, donc cela revient à insérer la noisette en fin de liste.
// On positionne le rang à max + 1 permet d'éviter d'avoir des trous dans la liste des rangs.
$description['rang'] = $rang_max + 1;
} else {
// Si le rang est non nul c'est qu'on insère la noisette dans la liste existante. Néanmoins, si le rang
// est strictement supérieur au rang_max c'est que la nouvelle noisette est ajoutée après les noisettes
// existantes, donc on ne fait rien.
// Sinon, il faut décaler les noisettes de rang supérieur ou égal.
// Si le rang est non nul c'est qu'on insère la noisette dans la liste existante.
// Il faut décaler les noisettes de rang supérieur ou égal si elle existent.
if ($rang <= $rang_max) {
foreach ($noisettes as $_id_noisette => $_description) {
if ($_description['rang'] >= $rang) {
@ -103,24 +105,148 @@ function noisette_ajouter($plugin, $type_noisette, $squelette, $rang = 0, $stock
}
/**
* @param $plugin
* @param $identifiant
* @param string $stockage
* Supprime un noisette donnée d’un squelette.
* La fonction met à jour les rangs des autres noisettes si nécessaire.
*
* @api
* @uses ncore_noisette_decrire()
* @uses ncore_noisette_destocker()
* @uses ncore_noisette_lister()
* @uses ncore_noisette_stocker()
*
* @param string $plugin
* 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 mixed $noisette
* Identifiant de la noisette qui peut prendre soit la forme d'un entier ou d'une chaine unique, soit la forme
* d'un couple (squelette, rang).
* @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 d'un plugin
* fournissant le service de stockage souhaité.
*
* @return bool
*/
function noisette_supprimer($plugin, $identifiant, $stockage = '') {
function noisette_supprimer($plugin, $noisette, $stockage = '') {
// Initialisation du retour
$retour = false;
if (intval($identifiant)) {
// Suppression d'un noisette connue par son id.
$retour = ncore_noisette_destocker($plugin, $identifiant, $stockage);
} elseif (is_string($identifiant) and $identifiant) {
// Suppression de toutes les noisettes affectées à un squelette.
$retour = ncore_noisette_destocker_squelette($plugin, $identifiant, $stockage);
// On charge l'API de N-Core.
// Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
include_spip("ncore/ncore");
// 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 à deux entrées fournissant le squelette et le rang (qui est unique pour un squelette 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.
$description = ncore_noisette_decrire($plugin, $noisette, $stockage);
// Suppression de la noisette. On passe la description complète ce qui permet à la fonction de
// destockage de choisir la méthode pour identifier la noisette.
$retour = ncore_noisette_destocker($plugin, $description, $stockage);
// On récupère les noisettes restant affectées au squelette sous la forme d'un tableau indexé par l'identifiant
// de la noisette stocké dans l'index 'id_noisette'.
$autres_noisettes = ncore_noisette_lister($plugin, $description['squelette'], '', $stockage);
// Si il reste des noisettes, on tasse d'un rang les noisettes qui suivaient la noisette supprimée.
if ($autres_noisettes) {
foreach ($autres_noisettes as $_id_noisette => $_autre_description) {
if ($_autre_description['rang'] > $description['rang']) {
$_autre_description['rang'] -= 1;
ncore_noisette_stocker($plugin, 'modification', $_autre_description, $stockage);
}
}
}
}
return $retour;
}
/**
* 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é.
*
* @api
* @uses ncore_noisette_decrire()
*
* @param string $plugin
* 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 mixed $noisette
* Identifiant de la noisette qui peut prendre soit la forme d'un entier ou d'une chaine unique, soit la forme
* d'un couple (squelette, rang).
* @param string $information
* Information spécifique à retourner ou vide pour retourner toute la description.
* @param boolean $traiter_typo
* Indique si les données textuelles doivent être retournées brutes ou si elles doivent être traitées
* en utilisant la fonction _T_ou_typo. Par défaut l'indicateur vaut `false`.
* Les champs sérialisés sont eux toujours désérialisés.
* Pour l'instant il n'y a pas de champ textuel directement associé à une noisette.
* @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 d'un plugin
* fournissant le service de stockage souhaité.
*
* @return bool
*/
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).
static $description_noisette_par_id = array();
static $description_noisette_par_rang = array();
// Initialisation de la description en sortie.
$retour = array();
if (!empty($noisette) and (is_string($noisette) or is_numeric($noisette) or is_array($noisette))) {
// Stocker la description de la noisette si besoin
if ((!is_array($noisette) and !isset($description_noisette[$plugin][$noisette]))
or (is_array($noisette) and isset($noisette['squelette']) and isset($noisette['rang'])
and !isset($description_noisette[$plugin][$noisette['squelette']][$noisette['rang']]))) {
// On charge l'API de N-Core.
// Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
include_spip("ncore/ncore");
// Lecture de toute la configuration de la noisette: les données retournées sont brutes.
$description = ncore_noisette_decrire($plugin, $noisette, $stockage);
// Sauvegarde de la description de la page pour une consultation ultérieure dans le même hit.
if ($description) {
// Traitements des champs tableaux sérialisés si nécessaire
if (is_string($description['parametres'])) {
$description['parametres'] = unserialize($description['parametres']);
}
}
// Stockage de la description
if (is_array($noisette)) {
$description_noisette_par_rang[$plugin][$noisette['squelette']][$noisette['rang']] = $description;
} else {
$description_noisette_par_id[$plugin][$noisette] = $description;
}
}
if ($information) {
if ((!is_array($noisette) and isset($description_noisette_par_id[$plugin][$noisette][$information]))
or (is_array($noisette)
and isset($description_noisette_par_rang[$plugin][$noisette['squelette']][$noisette['rang']][$information]))) {
$retour = is_array($noisette)
? $description_noisette_par_rang[$plugin][$noisette['squelette']][$noisette['rang']][$information]
: $description_noisette_par_id[$plugin][$noisette][$information];
} else {
$retour = '';
}
} else {
$retour = is_array($noisette)
? $description_noisette_par_rang[$plugin][$noisette['squelette']][$noisette['rang']]
: $description_noisette_par_id[$plugin][$noisette];
}
}
return $retour;
}
}

17
inc/ncore_type_noisette.php

@ -209,7 +209,7 @@ function type_noisette_charger($plugin, $dossier = 'noisettes/', $recharger = fa
*/
function type_noisette_lire($plugin, $type_noisette, $information = '', $traiter_typo = false, $stockage = '') {
// On indexe le tableau des indicateurs ajax par le plugin appelant en cas d'appel sur le même hit
// On indexe le tableau des descriptions par le plugin appelant en cas d'appel sur le même hit
// par deux plugins différents.
static $donnees_typo = array('nom', 'description');
static $description_noisette = array();
@ -229,12 +229,10 @@ function type_noisette_lire($plugin, $type_noisette, $information = '', $traiter
$description['contexte'] = unserialize($description['contexte']);
$description['necessite'] = unserialize($description['necessite']);
$description['parametres'] = unserialize($description['parametres']);
// Stockage de la description
$description_noisette[$plugin][$type_noisette] = $description;
} else {
$description_noisette[$plugin][$type_noisette] = array();
}
// Stockage de la description
$description_noisette[$plugin][$type_noisette] = $description;
}
if ($information) {
@ -252,9 +250,10 @@ function type_noisette_lire($plugin, $type_noisette, $information = '', $traiter
$retour = $description_noisette[$plugin][$type_noisette];
// Traitements des données textuels
if ($traiter_typo) {
$retour['nom'] = _T_ou_typo($retour['nom']);
if (isset($retour['description'])) {
$retour['description'] = _T_ou_typo($retour['description']);
foreach ($donnees_typo as $_champ) {
if (isset($retour[$_champ])) {
$retour[$_champ] = _T_ou_typo($retour[$_champ]);
}
}
}
}

198
ncore/ncore.php

@ -28,29 +28,29 @@ if (!defined('_ECRIRE_INC_VERSION')) {
*
* @package SPIP\NCORE\SERVICE\TYPE_NOISETTE
*
* @uses cache_lire()
* @uses cache_ecrire()
* @uses cache_lire()
* @uses cache_ecrire()
*
* @param string $plugin
* 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 $types_noisette
* Tableau associatif à 3 entrées fournissant les descriptions des types de noisettes nouveaux, obsolètes
* et modifiés:
* `a_effacer` : liste des identifiants de type de noisette devenus obsolètes.
* `a_changer` : liste des descriptions des types de noisette dont le fichier YAML a été modifié.
* `a_ajouter` : liste des descriptions des nouveaux types de noisette.
* Si $recharger est à `true`, seul l'index `nouvelles` est fourni dans le tableau $types_noisette.
* @param bool $recharger
* Indique si le chargement en cours est forcé ou pas. Cela permet à la fonction N-Core ou au service
* concerné d'optimiser le traitement sachant que seules les types de noisette nouveaux sont fournis.
* @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 d'un plugin
* fournissant le service de stockage souhaité.
* @param string $plugin
* 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 $types_noisette
* Tableau associatif à 3 entrées fournissant les descriptions des types de noisettes nouveaux, obsolètes
* et modifiés:
* `a_effacer` : liste des identifiants de type de noisette devenus obsolètes.
* `a_changer` : liste des descriptions des types de noisette dont le fichier YAML a été modifié.
* `a_ajouter` : liste des descriptions des nouveaux types de noisette.
* Si $recharger est à `true`, seul l'index `nouvelles` est fourni dans le tableau $types_noisette.
* @param bool $recharger
* Indique si le chargement en cours est forcé ou pas. Cela permet à la fonction N-Core ou au service
* concerné d'optimiser le traitement sachant que seules les types de noisette nouveaux sont fournis.
* @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 d'un plugin
* fournissant le service de stockage souhaité.
*
* @return bool
* `true` si le traitement s'est bien déroulé, `false` sinon.
* `true` si le traitement s'est bien déroulé, `false` sinon.
*/
function ncore_type_noisette_stocker($plugin, $types_noisette, $recharger, $stockage = '') {
@ -82,7 +82,7 @@ function ncore_type_noisette_stocker($plugin, $types_noisette, $recharger, $stoc
} else {
// On lit les cache existants et on applique les modifications.
$descriptions = cache_lire($plugin, _NCORE_NOMCACHE_TYPE_NOISETTE_DESCRIPTION);
$signatures = cache_lire($plugin,_NCORE_NOMCACHE_TYPE_NOISETTE_SIGNATURE);
$signatures = cache_lire($plugin, _NCORE_NOMCACHE_TYPE_NOISETTE_SIGNATURE);
// On supprime les noisettes obsolètes
if (!empty($types_noisette['a_effacer'])) {
@ -122,21 +122,21 @@ function ncore_type_noisette_stocker($plugin, $types_noisette, $recharger, $stoc
*
* @package SPIP\NCORE\SERVICE\TYPE_NOISETTE
*
* @uses cache_lire()
* @uses cache_lire()
*
* @param string $plugin
* 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 string $type_noisette
* Identifiant du type de noisette.
* @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 d'un plugin
* fournissant le service de stockage souhaité.
* @param string $plugin
* 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 string $type_noisette
* Identifiant du type de noisette.
* @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 d'un plugin
* fournissant le service de stockage souhaité.
*
* @return array
* Tableau de la description du type de noisette. Les champs textuels et les champs de type tableau sérialisé
* sont retournés en l'état.
* Tableau de la description du type de noisette. Les champs textuels et les champs de type tableau sérialisé
* sont retournés en l'état.
*/
function ncore_type_noisette_decrire($plugin, $type_noisette, $stockage = '') {
@ -170,21 +170,21 @@ function ncore_type_noisette_decrire($plugin, $type_noisette, $stockage = '') {
*
* @package SPIP\NCORE\SERVICE\TYPE_NOISETTE
*
* @uses cache_lire()
* @uses cache_lire()
*
* @param string $plugin
* 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 string $information
* Identifiant d'un champ de la description d'un type de noisette ou `signature`.
* Si l'argument est vide, la fonction renvoie les descriptions complètes et si l'argument est
* un champ invalide la fonction renvoie un tableau vide.
* @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.
* @param string $plugin
* 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 string $information
* Identifiant d'un champ de la description d'un type de noisette ou `signature`.
* Si l'argument est vide, la fonction renvoie les descriptions complètes et si l'argument est
* un champ invalide la fonction renvoie un tableau vide.
* @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.
*
* @return array
* Tableau de la forme `[noisette] = information ou description complète`.
* Tableau de la forme `[noisette] = information ou description complète`.
*/
function ncore_type_noisette_lister($plugin, $information = '', $stockage = '') {
@ -226,6 +226,7 @@ function ncore_type_noisette_lister($plugin, $information = '', $stockage = '')
/**
*
* @package SPIP\NCORE\SERVICE\NOISETTE
*
* @param $plugin
* @param $action
* @param $description
@ -285,6 +286,37 @@ function ncore_noisette_stocker($plugin, $action, $description, $stockage = '')
return $noisette;
}
function ncore_noisette_destocker($plugin, $description, $stockage = '') {
// Initialisation de la sortie.
$retour = false;
// On cherche le service de stockage à utiliser selon la logique suivante :
// - si le service de stockage est non vide on l'utilise en considérant que la fonction existe forcément;
// - sinon, on utilise la fonction du plugin appelant si elle existe;
// - et sinon, on utilise la fonction de N-Core.
include_spip('inc/ncore_utils');
if ($destocker = ncore_chercher_service($plugin, 'noisette_destocker', $stockage)) {
// On passe le plugin appelant à la fonction car cela permet ainsi de mutualiser les services de stockage.
$retour = $destocker($plugin, $description);
} 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][rang] = description
include_spip('inc/config');
$meta_noisettes = lire_config("${plugin}_noisettes", array());
if (isset($meta_noisettes[$description['squelette']][$description['rang']])) {
unset($meta_noisettes[$description['squelette']][$description['rang']]);
ecrire_config("${plugin}_noisettes", $meta_noisettes);
$retour = true;
}
}
return $retour;
}
/**
*
* @package SPIP\NCORE\SERVICE\NOISETTE
@ -335,3 +367,79 @@ function ncore_noisette_lister($plugin, $squelette = '', $information = '', $sto
return $noisettes;
}
/**
* Renvoie la description brute d'un type de noisette sans traitement typo ni désérialisation des champs de type
* tableau sérialisé.
*
* Le service N-Core lit la description du type de noisette concerné dans le cache des descriptions.
*
* @package SPIP\NCORE\SERVICE\TYPE_NOISETTE
*
* @uses cache_lire()
*
* @param string $plugin
* 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 mixed $noisette
* Identifiant de la noisette qui peut prendre soit la forme d'un entier ou d'une chaine unique, soit la forme
* d'un couple (squelette, rang).
* @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 d'un plugin
* fournissant le service de stockage souhaité.
*
* @return array
* Tableau de la description du type de noisette. Les champs textuels et les champs de type tableau sérialisé
* sont retournés en l'état.
*/
function ncore_noisette_decrire($plugin, $noisette, $stockage = '') {
$description = array();
// On cherche le service de stockage à utiliser selon la logique suivante :
// - si le service de stockage est non vide on l'utilise en considérant que la fonction existe forcément;
// - sinon, on utilise la fonction du plugin appelant si elle existe;
// - et sinon, on utilise la fonction de N-Core.
include_spip('inc/ncore_utils');
if ($decrire = ncore_chercher_service($plugin, 'noisette_decrire', $stockage)) {
// On passe le plugin appelant à la fonction car cela permet ainsi de mutualiser les services de stockage.
$description = $decrire($plugin, $noisette);
} 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][rang] = description
include_spip('inc/config');
$meta_noisettes = lire_config("${plugin}_noisettes", array());
// On recherche la description dans la meta.
if ($meta_noisettes) {
if (!is_array($noisette)) {
// L'identifiant est l'id unique de la noisette. Il faut donc parcourir le tableau pour trouver la
// noisette désirée
// => ce n'est pas la méthode optimale pour le stockage N-Core.
$noisette_trouvee = false;
foreach ($meta_noisettes as $_noisettes_squelette) {
foreach ($_noisettes_squelette as $_noisette) {
if ($_noisette['id_noisette'] == $noisette) {
$description = $_noisette;
$noisette_trouvee = true;
break;
}
}
if ($noisette_trouvee) {
break;
}
}
} elseif (isset($noisette['squelette']) and isset($noisette['rang']) and !empty($meta_noisettes[$noisette['squelette']][$noisette['rang']])) {
// L'identifiant est un tableau associatif fournissant le squelette 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[$noisette['squelette']][$noisette['rang']];
}
}
}
return $description;
}

Loading…
Cancel
Save