Changeset 106494 in spip-zone


Ignore:
Timestamp:
Oct 2, 2017, 5:54:09 PM (2 years ago)
Author:
eric@…
Message:

Du PHPdoc et des commentaires.

Location:
_plugins_/n-core/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • _plugins_/n-core/trunk/inc/ncore_noisette.php

    r106481 r106494  
    1313/**
    1414 * Ajoute à un squelette contextualisé, à un rang donné ou en dernier rang, une noisette d'un type donné.
     15 * La fonction met à jour les rangs des autres noisettes si nécessaire.
    1516 *
    1617 * @api
     
    2627 *              Identifiant du type de noisette à ajouter au squelette.
    2728 * @param string        $squelette
    28  *              Chemin relatif du squelette où ajouter la noisette.
     29 *              Chemin relatif du squelette auquel associer la noisette.
    2930 * @param array     $contexte
    3031 *              Tableau éventuellement vide matérialisant le contexte d'utilisation du squelette.
    3132 * @param int           $rang
    32  *              Rang dans le squelette où insérer la noisette. Si l'argument n'est pas fourni ou est égal à 0 on insère la
    33  *      noisette en fin de bloc.
     33 *              Rang dans le squelette contextualisé où insérer la noisette. Si l'argument n'est pas fourni ou est égal à 0
     34 *      on insère la noisette en fin de bloc.
    3435 * @param string        $stockage
    3536 *      Identifiant du service de stockage à utiliser si précisé. Dans ce cas, ni celui du plugin
     
    3738 *              fournissant le service de stockage souhaité.
    3839 *
    39  * @return mixed
     40 * @return int|string|bool
    4041 *              Retourne l'identifiant de la nouvelle instance de noisette créée ou `false` en cas d'erreur.
    4142 **/
     
    7172                );
    7273
    73                 // On charge l'API de N-Core.
    74                 // Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
     74                // On charge les services de N-Core.
     75                // Ce sont ces fonctions qui aiguillent ou pas vers un service spécifique du plugin.
    7576                include_spip("ncore/ncore");
    7677
     
    8788                        // En effet, si le rang est supérieur au rang max c'est que la nouvelle noisette est ajoutée
    8889                        // après les noisettes existantes, donc cela revient à insérer la noisette en fin de liste.
    89                         // On positionne le rang à max + 1 permet d'éviter d'avoir des trous dans la liste des rangs.
     90                        // Postionner le rang à max + 1 permet d'éviter d'avoir des trous dans la liste des rangs.
    9091                        $description['rang'] = $rang_max + 1;
    9192                } else {
    92                         // Si le rang est non nul c'est qu'on insère la noisette dans la liste existante.
    93                         // Il faut décaler les noisettes de rang supérieur ou égal si elle existent.
     93                        // Si le rang est non nul et inférieur ou égal au rang max c'est qu'on insère la noisette dans la liste
     94                        // existante : il faut décaler d'un rang les noisettes de rang supérieur ou égal si elle existent pour
     95                        // libérer la position de la nouvelle noisette.
    9496                        if ($rang <= $rang_max) {
    9597                                krsort($noisettes);
     
    102104                }
    103105
    104                 // La description de la nouvelle noisette est prête à être stockée.
     106                // La description de la nouvelle noisette est prête à être stockée à sa position.
    105107                $noisette_ajoutee = ncore_noisette_stocker($plugin, $description, $stockage);
    106108        }
     
    137139        $retour = false;
    138140
    139         // On charge l'API de N-Core.
    140         // Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
     141        // On charge les services de N-Core.
     142        // Ce sont ces fonctions qui aiguillent ou pas vers un service spécifique du plugin.
    141143        include_spip("ncore/ncore");
    142144
     
    144146        // - par une valeur unique, celle créée lors de l'ajout et qui peut-être un entier (id d'une table SPIP) ou
    145147        //   une chaine unique par exemple générée par uniqid().
    146         // - ou par un tableau à deux entrées fournissant le squelette et le rang (qui est unique pour un squelette donné).
     148        // - ou par un tableau à trois entrées fournissant le squelette, le contexte d'utilisation et le rang
     149        //   (qui est unique pour un squelette contextualisé donné).
    147150        if (!empty($noisette) and (is_string($noisette) or is_numeric($noisette) or is_array($noisette))) {
    148151                // Avant de supprimer la noisette on sauvegarde sa description.
     152                // Cela permet de conserver le rang, le squelette et le contexte indépendamment de l'identifiant
     153                // utilisé pour spécifier la noisette.
    149154                $description = ncore_noisette_decrire($plugin, $noisette, $stockage);
    150155
    151156                // Suppression de la noisette. On passe la description complète ce qui permet à la fonction de
    152                 // destockage de choisir la méthode pour identifier la noisette.
     157                // destockage de choisir la méthode d'identification la plus adaptée.
    153158                $retour = ncore_noisette_destocker($plugin, $description, $stockage);
    154159
    155                 // On récupère les noisettes restant affectées au squelette sous la forme d'un tableau indexé par l'identifiant
    156                 // de la noisette stocké dans l'index 'id_noisette' mais toujours trié de façon à ce que les rangs soient croissants.
     160                // On récupère les noisettes restant affectées au squelette contextualisé sous la forme d'un tableau indexé par rang.
    157161                $autres_noisettes = ncore_noisette_lister(
    158162                        $plugin,
     
    165169                // Si il reste des noisettes, on tasse d'un rang les noisettes qui suivaient la noisette supprimée.
    166170                if ($autres_noisettes) {
     171                        // On lit les noisettes restantes dans l'ordre décroissant pour éviter d'écraser une noisette.
    167172                        ksort($autres_noisettes);
    168173                        foreach ($autres_noisettes as $_rang => $_autre_description) {
     
    182187 *
    183188 * @api
     189 * @uses ncore_squelette_identifier()
    184190 * @uses ncore_noisette_decrire()
    185191 *
     
    215221
    216222        if (!empty($noisette) and (is_string($noisette) or is_numeric($noisette) or is_array($noisette))) {
    217                 // On charge l'API de N-Core.
    218                 // Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
     223                // On charge les services de N-Core.
     224                // Ce sont ces fonctions qui aiguillent ou pas vers un service spécifique du plugin.
    219225                include_spip("ncore/ncore");
    220226
     
    292298 * @param mixed         $noisette
    293299 *        Identifiant de la noisette qui peut prendre soit la forme d'un entier ou d'une chaine unique, soit la forme
    294  *        d'un couple (squelette, rang).
     300 *        d'un triplet (squelette, contexte, rang).
    295301 * @param string        $stockage
    296302 *      Identifiant du service de stockage à utiliser si précisé. Dans ce cas, ni celui du plugin
     
    305311        $retour = false;
    306312
    307         // On charge l'API de N-Core.
    308         // Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
     313        // On charge les services de N-Core.
     314        // Ce sont ces fonctions qui aiguillent ou pas vers un service spécifique du plugin.
    309315        include_spip("ncore/ncore");
    310316
     
    312318        // - par une valeur unique, celle créée lors de l'ajout et qui peut-être un entier (id d'une table SPIP) ou
    313319        //   une chaine unique par exemple générée par uniqid().
    314         // - ou par un tableau à deux entrées fournissant le squelette et le rang (qui est unique pour un squelette donné).
     320        // - ou par un tableau à trois entrées fournissant le squelette, le contexte et le rang
     321        //   (qui est unique pour un squelette donné).
    315322        if (!empty($noisette) and (is_string($noisette) or is_numeric($noisette) or is_array($noisette))) {
    316323                // Avant de deplacer la noisette on sauvegarde sa description et son rang origine.
    317                 // On met le rang à zéro pour indiquer que la noisette est sortie temporairement du rangement.
    318324                $description = ncore_noisette_decrire($plugin, $noisette, $stockage);
    319325                $rang_origine = $description['rang'];
    320                 $description['rang'] = 0;
    321326
    322327                // Si les rangs origine et destination sont identiques on ne fait rien !
    323328                if ($rang_destination != $rang_origine) {
    324                         // On récupère les noisettes affectées au même squelette sous la forme d'un tableau indexé par le rang
    325                         // et on déplace les noisettes impactées.
     329                        // On récupère les noisettes affectées au même squelette sous la forme d'un tableau indexé par le rang.
    326330                        $noisettes = ncore_noisette_lister(
    327331                                $plugin,
     
    339343
    340344                        // Suivant la position d'origine et de destination de la noisette déplacée on trie les noisettes
    341                         // du squelette.
     345                        // du squelette contextualisé.
    342346                        if ($rang_destination < $rang_origine) {
    343347                                krsort($noisettes);
     
    346350                        }
    347351
    348                         // On déplace les noisettes impactées.
     352                        // On déplace les noisettes impactées à l'exception de la noisette concernée par le déplacement
     353                        // afin de créer une position libre.
    349354                        foreach ($noisettes as $_rang => $_description) {
    350355                                if ($rang_destination < $rang_origine) {
     
    362367
    363368                        // On positionne le rang de la noisette à déplacer au rang destination.
     369                        // On met le rang à zéro pour indiquer que l'emplacement d'origine n'est plus occupé par la
     370                        // noisette et qu'il ne faut pas le supprimer lors du rangement.
     371                        $description['rang'] = 0;
    364372                        ncore_noisette_ranger($plugin, $description, $rang_destination, $stockage);
    365373                }
  • _plugins_/n-core/trunk/ncore/ncore.php

    r106481 r106494  
    225225
    226226/**
     227 * Stocke la description d'une nouvelle noisette et calcule son identifiant unique ou met à jour les paramètres
     228 * d'affichage d'une noisette existante.
    227229 *
    228230 * @package SPIP\NCORE\SERVICE\NOISETTE
     
    250252                //    N-Core calcule un identifiant unique pour la noisette qui sera stocké à l'index 'id_noisette' et qui
    251253                //    vaudra uniqid() avec comme préfixe le plugin appelant.
     254
     255                // On lit la meta de stockage des noisettes pour le plugin appelant.
    252256                include_spip('inc/config');
    253 
    254                 // On lit la meta de stockage des noisettes pour le plugin appelant.
    255                 // Le tableau est au format [squelette][rang] = description.
    256257                $noisettes = lire_config("${plugin}_noisettes", array());
    257258
    258                 // Détermination de l'identifiant du squelette contextualisé.
     259                // Détermination de l'identifiant du squelette contextualisé. Le squelette et le contexte font partie de
     260                // la description, le contexte est lui sérialisé.
    259261                $squelette_contextualise = ncore_squelette_identifier(
    260262                        $plugin,
     
    272274                } else {
    273275                        // Modification de la noisette :
    274                         // -- les informations identifiant sont toujours fournies, à savoir, l'id, le squelette et le rang.
    275                         // -- on utilise le squelette et le rang pour se positionner sur la noisette concernée.
     276                        // -- les informations identifiant sont toujours fournies, à savoir, l'id, le squelette, le contexte et le rang.
     277                        // -- on utilise le squelette contextualisé et le rang pour se positionner sur la noisette concernée.
    276278                        // -- Les modifications ne concernent que les paramètres d'affichage, cette fonction n'est jamais utilisée
    277279                        //    pour le changement de rang.
     
    295297
    296298/**
     299 * Positionne une noisette à un rang différent que celui qu'elle occupe.
    297300 *
    298301 * @package SPIP\NCORE\SERVICE\NOISETTE
     
    322325                // -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
    323326                //    [squelette contextualisé][rang] = description
    324                 //    N-Core calcule un identifiant unique pour la noisette qui sera stocké à l'index 'id_noisette' et qui
    325                 //    vaudra uniqid() avec comme préfixe le plugin appelant.
     327
     328                // On lit la meta de stockage des noisettes pour le plugin appelant.
    326329                include_spip('inc/config');
    327 
    328                 // On lit la meta de stockage des noisettes pour le plugin appelant.
    329                 // Le tableau est au format [squelette][rang] = description.
    330330                $noisettes = lire_config("${plugin}_noisettes", array());
    331331
    332                 // Détermination de l'identifiant du squelette contextualisé.
     332                // Détermination de l'identifiant du squelette contextualisé. Le squelette et le contexte font partie de
     333                // la description, le contexte est lui sérialisé.
    333334                $squelette_contextualise = ncore_squelette_identifier(
    334335                        $plugin,
     
    339340                // On ajoute la noisette au rang choisi même si on doit écraser un index existant.
    340341                // Il est donc nécessaire de gérer la collision en amont de cette fonction.
    341                 // De plus, l'ancien rang de la noisette est pas supprimé sauf si celui-ci est à zéro pour indiquer
    342                 // que la noisette a été temporairement sortie.
     342                // Par contre, l'ancien rang de la noisette est supprimé sauf si celui-ci est à zéro.
    343343                $rang_source = $description['rang'];
    344344                $description['rang'] = $rang_destination;
     
    357357
    358358/**
     359 * Retire une noisette et donc sa description de l'espace de stockage.
    359360 *
    360361 * @package SPIP\NCORE\SERVICE\NOISETTE
     
    383384                // -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
    384385                //    [squelette contextualisé][rang] = description
    385                 // -- $description est soit le tableau descriptif de la noisette, soit une chaine représentant l'identifiant du
    386                 //    squelette contextualisé et dans ce cas, il faut supprimer toutes les noisettes du squelette contextualisé.
     386                // -- $description est soit le tableau descriptif de la noisette, soit le tableau formé uniquement du couple
     387                //    (squelette, contexte) et dans ce cas, il faut supprimer toutes les noisettes du squelette contextualisé.
    387388                include_spip('inc/config');
    388389                $meta_noisettes = lire_config("${plugin}_noisettes", array());
    389390
    390                 // Détermination de l'identifiant du squelette contextualisé.
     391                // Détermination de l'identifiant du squelette contextualisé. Le squelette et le contexte font partie de
     392                // la description, le contexte est lui sérialisé.
    391393                $squelette_contextualise = ncore_squelette_identifier(
    392394                        $plugin,
     
    416418
    417419/**
     420 * Renvoie un données ou toute la description des noisettes d'un squelette contextualisé ou de tous les squelettes
     421 * contextualisés.
     422 * Le tableau retourné est indexé soit par id_noisette soit par squelette contextualisé et rang.
    418423 *
    419424 * @package SPIP\NCORE\SERVICE\NOISETTE
     
    593598        // de noisettes. N-Core ne propose pas de fonction par défaut car l'élaboration de l'identifiant
    594599        // en fonction du contexte est totalement spécifique au plugin utilisateur.
    595         // Il est donc indispensable que le plugin qui nécessite l'utilise d'un contexte propose la
     600        // Il est donc indispensable que le plugin qui nécessite l'utilisation d'un contexte propose la
    596601        // fonction de calcul associée sinon le contexte ne sera pas pris en compte et seul l'identifiant
    597602        // du squelette sera retourné.
Note: See TracChangeset for help on using the changeset viewer.