Changeset 65685 in spip-zone


Ignore:
Timestamp:
Sep 8, 2012, 1:48:23 PM (7 years ago)
Author:
marcimat@…
Message:

PHPDoc complet de Champs Extras Core

Location:
_plugins_/champs_extras/core/trunk
Files:
7 edited

Legend:

Unmodified
Added
Removed
  • _plugins_/champs_extras/core/trunk/base/cextras.php

    r65577 r65685  
    11<?php
     2
     3/**
     4 * Déclaration colonnes SQL des champs extras
     5 *
     6 * @package SPIP\Cextras\Pipelines
     7**/
     8
     9// sécurité
    210if (!defined("_ECRIRE_INC_VERSION")) return;
    311
    412
    5 /*
    6  * Déclarer les nouveaux champs et
    7  * les nouvelles infos des objets éditoriaux
     13/**
     14 * Déclarer les nouveaux champs et les nouvelles infos des objets éditoriaux
     15 *
     16 * La fonction déclare tous les champs extras (saisies de type sql).
     17 *
     18 * Elle déclare aussi, en fonction des options choisies pour les champs
     19 * - la recherche dans le champs, avec une certaine pondération,
     20 * - le versionnage de champ
    821 *
    9  * /!\ Ne pas utiliser table_objet() qui ferait une reentrance et des calculs faux.
     22 * @note
     23 *     Ne pas utiliser dans le code de cette fonction
     24 *     table_objet() qui ferait une réentrance et des calculs faux.
     25 *
     26 * @pipeline declarer_tables_objets_sql
     27 * @param array $tables
     28 *     Description des tables
     29 * @return array
     30 *     Description complétée des tables
    1031 */
    1132function cextras_declarer_tables_objets_sql($tables){
     
    7596 * en ce qui concerne les traitements automatiques sur les balises.
    7697 *
     98 * @pipeline declarer_tables_interfaces
     99 * @param array $interfaces
     100 *     Déclarations d'interface pour le compilateur
     101 * @return array
     102 *     Déclarations d'interface pour le compilateur
    77103**/
    78 function cextras_declarer_tables_interfaces($interface){
     104function cextras_declarer_tables_interfaces($interfaces){
    79105
    80106        include_spip('inc/cextras');
     
    90116        $saisies_tables = pipeline('declarer_champs_extras', array());
    91117        if (!$saisies_tables) {
    92                 return $interface;
     118                return $interfaces;
    93119        }
    94120
     
    101127                        $balise = strtoupper($saisie['options']['nom']);
    102128                        // definir
    103                         if (!isset($interface['table_des_traitements'][$balise])) {
    104                                 $interface['table_des_traitements'][$balise] = array();
     129                        if (!isset($interfaces['table_des_traitements'][$balise])) {
     130                                $interfaces['table_des_traitements'][$balise] = array();
    105131                        }
    106132                        // le traitement peut etre le nom d'un define
    107133                        $traitement = defined($traitement) ? constant($traitement) : $traitement;
    108        
     134
    109135                        // SPIP 3 permet de declarer par la table sql directement.
    110                         $interface['table_des_traitements'][$balise][$table] = $traitement;             
    111                        
     136                        $interfaces['table_des_traitements'][$balise][$table] = $traitement;
     137
    112138                }
    113139        }
    114140
    115141        // ajouter les champs au tableau spip
    116         return $interface;
     142        return $interfaces;
    117143}
    118144
  • _plugins_/champs_extras/core/trunk/cextras_fonctions.php

    r64475 r65685  
    11<?php
    22
    3 
    4 /**
    5  * Retourne la description de la saisie du champ demande
    6  * permettant ainsi d'exploiter ses donnees.
    7  *
    8  * <BOUCLE_x(TABLE)>
    9  *  - #CHAMP_EXTRA{nom_du_champ}
    10  *  - #CHAMP_EXTRA{nom_du_champ,label}
    11  * </BOUCLE_x>
    12  *
    13  * @return ChampExtra
     3/**
     4 * Déclarations de balises pour les squelettes
     5 *
     6 * @package SPIP\Cextras\Fonctions
     7**/
     8
     9// sécurité
     10if (!defined("_ECRIRE_INC_VERSION")) return;
     11
     12/**
     13 * Retourne la description de la saisie du champ demandé
     14 * permettant ainsi d'exploiter ses données.
     15 *
     16 * @example
     17 *     <BOUCLE_x(TABLE)>
     18 *      - #CHAMP_EXTRA{nom_du_champ}
     19 *      - #CHAMP_EXTRA{nom_du_champ,label}
     20 *     </BOUCLE_x>
     21 *
     22 * @balise CHAMP_EXTRA
     23 * @note
     24 *     Lève une erreur de squelette si le nom de champs extras
     25 *     n'est pas indiqué en premier paramètre de la balise
     26 *
     27 * @param Champ $p
     28 *     AST au niveau de la balise
     29 * @return Champ
     30 *     AST complété par le code PHP de la balise
    1431**/
    1532function balise_CHAMP_EXTRA_dist($p) {
     
    1734        $id_boucle = $p->nom_boucle ? $p->nom_boucle : $p->id_boucle;
    1835        $objet = $p->boucles[$id_boucle]->id_table;
    19        
     36
    2037        // recuperer les parametres : colonne sql (champ)
    2138        if (!$colonne = interprete_argument_balise(1, $p)) {
    22                 $msg = array('zbug_balise_sans_argument',       array('balise' => ' CHAMP_EXTRA'));
    23                 erreur_squelette($msg, $p);
    24         }
    25                
     39                $msg = array('zbug_balise_sans_argument', array('balise' => ' CHAMP_EXTRA'));
     40                erreur_squelette($msg, $p);
     41        }
     42
    2643        $demande = sinon(interprete_argument_balise(2, $p), "''");
    2744        $p->code = "calculer_balise_CHAMP_EXTRA('$objet', $colonne, $demande)";
     
    2946}
    3047
    31 // retourne un champ extra donne (le tableau de description des options de saisies)
    32 // ou un des attributs de ce tableau
     48/**
     49 * Retourne la description d'un champ extra indiqué
     50 *
     51 * Retourne le tableau de description des options de saisies
     52 * ou un des attributs de ce tableau
     53 *
     54 * @param string $objet
     55 *     Type d'objet
     56 * @param string $colonne
     57 *     Nom de la colonne SQL
     58 * @param string $demande
     59 *     Nom du paramètre demandé.
     60 *     Non renseigné, tout le tableau de description est retourné
     61 * @return mixed
     62 *     - Tableau si toute la description est demandée
     63 *     - Indéfini si un élément spécifique de la description est demandé.
     64 *     - Chaine vide si le champs extra n'est pas trouvé
     65 */
    3366function calculer_balise_CHAMP_EXTRA($objet, $colonne, $demande='') {
    3467        // Si la balise n'est pas dans une boucle, on cherche un objet explicite dans le premier argument
     
    6598 * Retourne les choix possibles d'un champ extra donné
    6699 *
    67  * #LISTER_CHOIX{champ}
    68  * #LISTER_CHOIX{champ, " > "}
    69  * #LISTER_CHOIX**{champ} // retourne un tableau cle/valeur
    70  *
    71  * @return ChampExtra
     100 * @example
     101 *     #LISTER_CHOIX{champ}
     102 *     #LISTER_CHOIX{champ, " > "}
     103 *     #LISTER_CHOIX**{champ} // retourne un tableau cle/valeur
     104 *
     105 * @balise LISTER_CHOIX
     106 * @param Champ $p
     107 *     AST au niveau de la balise
     108 * @return Champ
     109 *     AST complété par le code PHP de la balise
    72110**/
    73111function balise_LISTER_CHOIX_dist($p) {
     
    109147
    110148
     149/**
     150 * Retourne les choix possibles d'un champ extra indiqué
     151 *
     152 * @param string $objet
     153 *     Type d'objet
     154 * @param string $colonne
     155 *     Nom de la colonne SQL
     156 * @return string|array
     157 *     - Tableau des couples (clé => valeur) des choix
     158 *     - Chaîne vide si le champs extra n'est pas trouvé
     159 */
    111160function calculer_balise_LISTER_CHOIX($objet, $colonne) {
    112161        if ($options = calculer_balise_CHAMP_EXTRA($objet, $colonne)) {
     
    121170
    122171
    123 /*
     172/**
    124173 * Liste les valeurs des champs de type liste (enum, radio, case)
    125  * Ces champs enregistrent en base la valeur de la cle
    126  * Il faut donc transcrire cle -> valeur
    127  *
    128  * #LISTER_VALEURS{champ}
    129  * #LISTER_VALEURS{champ, " > "}
    130  * #LISTER_VALEURS**{champ} // retourne un tableau cle/valeur
    131  *
    132  * /!\
    133  * Pour des raisons d'efficacite des requetes SQL
    134  * le parametre "champ" ne peut etre calcule
    135  * #LISTER_VALEURS{#GET{champ}} ne peut pas fonctionner.
    136  *
    137  * Si cette restriction est trop limitative, on verra par la suite
    138  * pour l'instant, on laisse comme ca...
    139  *
     174 *
     175 * Ces champs enregistrent en base la valeur de la clé
     176 * Il faut donc transcrire clé -> valeur
     177 *
     178 * @example
     179 *     #LISTER_VALEURS{champ}
     180 *     #LISTER_VALEURS{champ, " > "}
     181 *     #LISTER_VALEURS**{champ} // retourne un tableau cle/valeur
     182 *
     183 * @note
     184 *     Pour des raisons d'efficacité des requetes SQL
     185 *     le parametre "champ" ne peut être calculé
     186 *     #LISTER_VALEURS{#GET{champ}} ne peut pas fonctionner.
     187 *
     188 *     Si cette restriction est trop limitative, on verra par la suite
     189 *     pour l'instant, on laisse comme ca...
     190 *
     191 * @balise LISTER_VALEURS
     192 * @param Champ $p
     193 *     AST au niveau de la balise
     194 * @return Champ
     195 *     AST complété par le code PHP de la balise
    140196 */
    141197function balise_LISTER_VALEURS_dist($p) {
     
    157213        // recuperer les parametres : colonne sql (champ)
    158214        if (!$colonne = interprete_argument_balise(1, $p)) {
    159                 $msg = array('zbug_balise_sans_argument',       array('balise' => ' LISTER_VALEURS'));
     215                $msg = array('zbug_balise_sans_argument', array('balise' => ' LISTER_VALEURS'));
    160216                erreur_squelette($msg, $p);
    161217                $p->code = "''";
     
    178234       
    179235        $valeur = champ_sql($texte_colonne, $p);
    180        
     236
    181237        // generer le code d'execution
    182         $p->code = "calculer_balise_LISTER_VALEURS('$objet', '$_id_objet', $colonne, $id_objet, $valeur)";
    183        
     238        $p->code = "calculer_balise_LISTER_VALEURS('$objet', $colonne, $valeur)";
     239
    184240        // retourne un array si #LISTER_VALEURS**
    185241        // sinon fabrique une chaine avec le separateur designe.
     
    187243                $p->code = "(is_array(\$a = $p->code) ? join($separateur, \$a) : " . $p->code . ")";
    188244        }
    189        
     245
    190246        return $p;
    191247}
    192248
    193249
    194 // retourne un tableau de la liste des valeurs choisies pour un champ extra de table donne
    195 function calculer_balise_LISTER_VALEURS($objet, $_id_objet, $colonne, $id_objet, $cles) {
     250/**
     251 * Retourne liste des valeurs choisies pour un champ extra indiqué
     252 *
     253 * @param string $objet
     254 *     Type d'objet
     255 * @param string $colonne
     256 *     Nom de la colonne SQL
     257 * @param string $cles
     258 *     Valeurs enregistrées pour ce champ dans la bdd pour l'objet en cours
     259 *
     260 * @return string|array
     261 *     - Tableau des couples (clé => valeur) des choix
     262 *     - Chaîne vide si le champs extra n'est pas trouvé
     263**/
     264function calculer_balise_LISTER_VALEURS($objet, $colonne, $cles) {
    196265        // exploser les cles !
    197266        $cles = explode(',', $cles);
  • _plugins_/champs_extras/core/trunk/cextras_options.php

    r62349 r65685  
    11<?php
    22
    3         // utiliser ce pipeline a part
    4         // afin d'etre certain d'arriver apres les autres plugins
    5         // sinon toutes les tables ne sont pas declarees
    6         // et les champs supplementaires ne peuvent pas se declarer comme il faut
     3/**
     4 * Options globales chargées à chaque hit
     5 *
     6 * @package SPIP\Cextras\Options
     7**/
    78
    8         if (!isset($GLOBALS['spip_pipeline']['declarer_tables_objets_sql'])) {
    9                 $GLOBALS['spip_pipeline']['declarer_tables_objets_sql'] = '';
    10         }
    11         if (!isset($GLOBALS['spip_pipeline']['declarer_tables_interfaces'])) {
    12                 $GLOBALS['spip_pipeline']['declarer_tables_interfaces'] = '';
    13         }
     9// sécurité
     10if (!defined("_ECRIRE_INC_VERSION")) return;
    1411
    15         $GLOBALS['spip_pipeline']['declarer_tables_objets_sql'] .= '||cextras_declarer_champs_apres_les_autres';
    16         function cextras_declarer_champs_apres_les_autres($tables) {
    17                 include_spip('base/cextras');
    18                 return cextras_declarer_tables_objets_sql($tables);
    19         }
    20         $GLOBALS['spip_pipeline']['declarer_tables_interfaces'] .= '||cextras_declarer_champs_interfaces_apres_les_autres';
    21         function cextras_declarer_champs_interfaces_apres_les_autres($interface) {
    22                 include_spip('base/cextras');
    23                 return cextras_declarer_tables_interfaces($interface);
    24         }
     12// utiliser ces pipelines a part
     13// afin d'etre certain d'arriver apres les autres plugins
     14// sinon toutes les tables ne sont pas declarees
     15// et les champs supplementaires ne peuvent pas se declarer comme il faut
     16
     17if (!isset($GLOBALS['spip_pipeline']['declarer_tables_objets_sql'])) {
     18        $GLOBALS['spip_pipeline']['declarer_tables_objets_sql'] = '';
     19}
     20if (!isset($GLOBALS['spip_pipeline']['declarer_tables_interfaces'])) {
     21        $GLOBALS['spip_pipeline']['declarer_tables_interfaces'] = '';
     22}
     23
     24$GLOBALS['spip_pipeline']['declarer_tables_objets_sql'] .= '||cextras_declarer_champs_apres_les_autres';
     25$GLOBALS['spip_pipeline']['declarer_tables_interfaces'] .= '||cextras_declarer_champs_interfaces_apres_les_autres';
     26
     27/**
     28 * Ajouter les déclaration dechamps extras sur les objets éditoriaux
     29 *
     30 * @pipeline declarer_tables_objets_sql
     31 * @see cextras_declarer_tables_objets_sql()
     32 * @param array $tables
     33 *     Description des objets éditoriaux
     34 * @return array
     35 *     Description des objets éditoriaux
     36**/
     37function cextras_declarer_champs_apres_les_autres($tables) {
     38        include_spip('base/cextras');
     39        return cextras_declarer_tables_objets_sql($tables);
     40}
     41
     42/**
     43 * Ajouter les déclaration d'interface des champs extras pour le compilateur
     44 *
     45 * @pipeline declarer_tables_interfaces
     46 * @see cextras_declarer_tables_interfaces()
     47 * @param array $interface
     48 *     Description des interfaces pour le compilateur
     49 * @return array
     50 *     Description des interfaces pour le compilateur
     51**/
     52function cextras_declarer_champs_interfaces_apres_les_autres($interface) {
     53        include_spip('base/cextras');
     54        return cextras_declarer_tables_interfaces($interface);
     55}
    2556?>
  • _plugins_/champs_extras/core/trunk/cextras_pipelines.php

    r63406 r65685  
    11<?php
     2
     3/**
     4 * Utilisations de pipelines
     5 *
     6 * @package SPIP\Cextras\Pipelines
     7**/
     8
     9// sécurité
    210if (!defined("_ECRIRE_INC_VERSION")) return;
    311
    4 
    5 /**
    6  * Retourne la liste des saisies extras concernant un objet donné
    7  *
    8  * @param string $table Nom d'une table SQL éditoriale
    9  * @return array Liste des saisies extras de l'objet
     12/**
     13 * Retourne la liste des saisies de champs extras concernant un objet donné
     14 *
     15 * @pipeline_appel declarer_champs_extras
     16 * @param string $table
     17 *     Nom d'une table SQL éditoriale
     18 * @return array
     19 *     Liste des saisies de champs extras de l'objet
    1020**/
    1121function champs_extras_objet($table) {
     
    1424                $saisies_tables = pipeline('declarer_champs_extras', array());
    1525        }
    16        
     26
    1727        return isset($saisies_tables[$table]) ? $saisies_tables[$table] : array();
    1828}
     
    2131 * Filtrer par autorisation les saisies transmises
    2232 *
    23  * @param String $faire Type d'autorisation testee : 'voir', 'modifier'
    24  * @param String $quoi Objet d'application : 'article'
    25  * @param Array $saisies Liste des saisies à filtrer
    26  * @param Array $args Arguments pouvant être utiles à l'autorisation
    27  * @return Array Liste des saisies filtrées
     33 * Chacune des saisies est parcourue et si le visiteur n'a pas l'autorisation
     34 * de la voir, elle est enlevée de la liste.
     35 * La fonction ne retourne donc que la liste des saisies que peut voir
     36 * la personne.
     37 *
     38 * @param string $faire
     39 *     Type d'autorisation testée : 'voir', 'modifier'
     40 * @param string $quoi
     41 *     Type d'objet tel que 'article'
     42 * @param array $saisies
     43 *     Liste des saisies à filtrer
     44 * @param array $args
     45 *     Arguments pouvant être utiles à l'autorisation
     46 * @return array
     47 *     Liste des saisies filtrées
    2848**/
    2949function champs_extras_autorisation($faire, $quoi='', $saisies=array(), $args=array()) {
     
    5979 * Ajoute pour chaque saisie de type SQL un drapeau (input hidden)
    6080 * permettant de retrouver les saisies editées.
     81 *
    6182 * Particulièrement utile pour les checkbox qui ne renvoient
    6283 * rien si on les décoche.
    6384 *
    64  * @param Array $saisies liste de saisies
    65  * @return Array $saisies Saisies complétées des drapeaux d'édition
    66 **/
    67 function champs_extras_ajouter_drapeau_edition($saisies, $inc = false) {
     85 * @param array $saisies
     86 *     Liste de saisies
     87 * @return array $saisies
     88 *     Saisies complétées des drapeaux d'édition
     89**/
     90function champs_extras_ajouter_drapeau_edition($saisies) {
    6891        $saisies_sql = saisies_lister_avec_sql($saisies);
    6992        foreach ($saisies_sql as $saisie) {
     
    83106
    84107
    85 // ajouter les champs sur les formulaires CVT editer_xx
     108/**
     109 * Ajouter les champs extras sur les formulaires CVT editer_xx
     110 *
     111 * Liste les champs extras de l'objet, et s'il y en a les ajoute
     112 * sur le formulaire d'édition en ayant filtré uniquement les saisies
     113 * que peut voir le visiteur et en ayant ajouté des champs hidden
     114 * servant à champs extras.
     115 *
     116 * @pipeline editer_contenu_objet
     117 * @param array $flux Données du pipeline
     118 * @return array      Données du pipeline
     119**/
    86120function cextras_editer_contenu_objet($flux){
    87121       
     
    104138
    105139
    106 // ajouter les champs extras soumis par les formulaire CVT editer_xx
     140/**
     141 * Ajouter les champs extras soumis par les formulaire CVT editer_xx
     142 *
     143 * Pour chaque champs extras envoyé par le formulaire d'édition,
     144 * ajoute les valeurs dans l'enregistrement à effectuer.
     145 *
     146 * @pipeline pre_edition
     147 * @param array $flux Données du pipeline
     148 * @return array      Données du pipeline
     149**/
    107150function cextras_pre_edition($flux){
    108151       
     
    127170
    128171
    129 // ajouter le champ extra sur la visualisation de l'objet
     172/**
     173 * Ajouter les champs extras sur la visualisation de l'objet
     174 *
     175 * S'il y a des champs extras sur l'objet, la fonction les ajoute
     176 * à la vue de l'objet, en enlevant les saisies que la personne n'a
     177 * pas l'autorisation de voir.
     178 *
     179 * @pipeline afficher_contenu_objet
     180 * @param array $flux Données du pipeline
     181 * @return array      Données du pipeline
     182**/
    130183function cextras_afficher_contenu_objet($flux){
    131184        // recuperer les saisies de l'objet en cours
     
    168221}
    169222
    170 // verification de la validite des champs extras
     223/**
     224 * Vérification de la validité des champs extras
     225 *
     226 * Lorsqu'un formulaire 'editer_xx' se présente, la fonction effectue,
     227 * pour chaque champs extra les vérifications prévues dans la
     228 * définition de la saisie, et retourne les éventuelles erreurs rencontrées.
     229 *
     230 * @pipeline formulaire_verifier
     231 * @param array $flux Données du pipeline
     232 * @return array      Données du pipeline
     233**/
    171234function cextras_formulaire_verifier($flux){
    172235        $form = $flux['args']['form'];
  • _plugins_/champs_extras/core/trunk/inc/cextras.php

    r55268 r65685  
    11<?php
     2
     3/**
     4 * Déclaration d'autorisations pour les champs extras
     5 *
     6 * @package SPIP\Cextras\Fonctions
     7**/
     8
     9// sécurité
    210if (!defined("_ECRIRE_INC_VERSION")) return;
    311
    412
    513/**
    6  * Log une information
    7  * Info importante si le second parametre est true.
     14 * Log une information
     15 *
     16 * @param mixed $contenu
     17 *     Contenu à loger
     18 * @param bool $important
     19 *     Est-ce une info importante à loger ?
    820 */
    921function extras_log($contenu, $important=false) {
     
    1628
    1729
    18 // retourne la liste des objets valides utilisables par le plugin
    19 // (dont on peut afficher les champs dans les formulaires)
     30/**
     31 * Retourne la liste des objets valides utilisables
     32 *
     33 * C'est à dire les objets dont on peut afficher les champs dans les
     34 * formulaires, ce qui correspond aux objets éditoriaux déclarés
     35 * comme avec l'option principale.
     36 *
     37 * @return array
     38 *    Couples (table sql => description de l'objet éditorial)
     39 */
    2040function cextras_objets_valides(){
    2141       
     
    3454
    3555
    36 // formater pour les boucles pour 'type'=>'nom'
    37 function cextras_objets_valides_boucle_pour(){
    38         $objets = array();
    39         foreach(lister_tables_objets_sql() as $table => $desc) {
    40                 $objets[ $table ] = _T($desc['texte_objets']);
    41         }
    42         return $objets;
    43 }
    44 
    45 
    46 // retourne la liste des types de formulaires de saisie
    47 // utilisables par les champs extras
    48 // (crayons appelle cela des 'controleurs')
    49 function cextras_types_formulaires(){
    50         $types = array();
    51         include_spip('inc/saisies');
    52         foreach(saisies_lister_disponibles() as $saisie => $desc) {
    53                 $types[$saisie] = $desc['titre'];
    54         }
    55 
    56         return $types;
    57 }
    5856
    5957
    6058/**
    6159 * Liste les saisies ayant des traitements
    62  * 
    63  *
    64  * @param Array $saisies liste de saisies
    65  * @param String $tri tri par défaut des résultats (s'ils ne sont pas deja triés) ('nom', 'identifiant')
    66  * @return liste de ces saisies triees par nom ayant des traitements définis
     60 *
     61 * Retourne uniquement les saisies ayant traitements à appliquer sur
     62 * les champs tel que des traitements typo ou traitements raccourcis.
     63 *
     64 * @param array $saisies
     65 *     Liste de saisies
     66 * @param String $tri
     67 *     Tri par défaut des résultats (s'ils ne sont pas deja triés) ('nom', 'identifiant')
     68 * @return array
     69 *     Liste de ces saisies triées par nom ayant des traitements définis
    6770**/
    6871function saisies_lister_avec_traitements($saisies, $tri = 'nom') {
     
    7376
    7477/**
    75  * Créer les champs extras
     78 * Créer les champs extras (colonnes en base de données)
    7679 * definies par le lot de saisies donné
    7780 *
    78  * @param
    79  * @return
     81 * @param string $table
     82 *     Nom de la table SQL
     83 * @param array $saisies
     84 *     Description des saisies
     85 * @return bool|void
     86 *     False si pas de table ou aucune saisie de type SQL
    8087**/
    8188function champs_extras_creer($table, $saisies) {
     
    93100                return false;
    94101        }
    95        
     102
    96103        $desc = lister_tables_objets_sql($table);
    97104
     
    113120
    114121/**
    115  * Supprimer les champs extras
    116  * definies par le lot de saisies donné
    117  *
    118  * @param
    119  * @return
     122 * Supprimer les champs extras (colonne dans la base de données)
     123 * definies par le lot de saisies donné
     124 *
     125 * @param string $table
     126 *     Nom de la table SQL
     127 * @param array $saisies
     128 *     Description des saisies
     129 * @return bool
     130 *     False si pas de table, aucune saisie de type SQL, ou une suppression en erreur
     131 *     True si toutes les suppressions sont OK
    120132**/
    121133function champs_extras_supprimer($table, $saisies) {
     
    148160
    149161/**
    150  * Modifier les champs extras
     162 * Modifier les champs extras (colonne dans la base de données)
    151163 * definies par le lot de saisies donné   
    152164 *
    153  * @param
    154  * @return
     165 * Permet de changer la structure SQL ou le nom de la colonne
     166 * des saisies
     167 *
     168 * @param string $table
     169 *     Nom de la table SQL
     170 * @param array $saisies_nouvelles
     171 *     Description des saisies nouvelles
     172 * @param array $saisies_anciennes
     173 *     Description des saisies anciennes
     174 * @return bool
     175 *     True si les changement SQL sont correctement effectués
    155176**/
    156177function champs_extras_modifier($table, $saisies_nouvelles, $saisies_anciennes) {
     
    170191
    171192/**
    172  * Crée un tableau de mise à jour pour installer les champs extras.
    173  * Exemple d'usage :
    174  * cextras_api_upgrade(motus_declarer_champs_extras(), $maj['create']);
     193 * Complète un tableau de mise à jour de plugin afin d'installer les champs extras.
     194 *
     195 * @example
     196 *     cextras_api_upgrade(motus_declarer_champs_extras(), $maj['create']);
    175197 *
    176198 * @param array $declaration_champs_extras
    177  *              Liste de champs extras à installer, c'est à dire la liste de saisies
    178  *              présentes dans le pipeline declarer_champs_extras() du plugin qui demande l'installation
    179  * @param array &$maj_item
    180  *              Un des éléments du tableau d'upgrade $maj,
    181  *              il sera complété des actions d'installation des champs extras demandés
     199 *     Liste de champs extras à installer, c'est à dire la liste de saisies
     200 *     présentes dans le pipeline declarer_champs_extras() du plugin qui demande l'installation
     201 * @param array $maj_item
     202 *     Un des éléments du tableau d'upgrade $maj,
     203 *     il sera complété des actions d'installation des champs extras demandés
    182204 *
    183205 * @return bool
    184  *              Les actions ont été faites.
     206 *     false si les déclarations sont mal formées
     207 *     true sinon
    185208**/
    186209function cextras_api_upgrade($declaration_champs_extras, &$maj_item) {
     
    201224/**
    202225 * Supprime les champs extras declarés
    203  * Exemple d'usage :
    204  * cextras_api_vider_tables(motus_declarer_champs_extras());
     226 *
     227 * @example
     228 *     cextras_api_vider_tables(motus_declarer_champs_extras());
    205229 *
    206230 * @param array $declaration_champs_extras
    207  *              Liste de champs extras à désinstaller, c'est à dire la liste de saisies
    208  *              présentes dans le pipeline declarer_champs_extras() du plugin qui demande la désinstallation
     231 *     Liste de champs extras à désinstaller, c'est à dire la liste de saisies
     232 *     présentes dans le pipeline declarer_champs_extras() du plugin qui demande la désinstallation
    209233 *
    210234 * @return bool
    211  *              Les actions ont été faites.
     235 *     false si déclaration mal formée
     236 *     true sinon
    212237**/
    213238function cextras_api_vider_tables($declaration_champs_extras) {
    214239        if (!is_array($declaration_champs_extras)) {
    215240                return false;
    216         }       
     241        }
    217242        foreach($declaration_champs_extras as $table=>$champs) {
    218243                champs_extras_supprimer($table, $champs);
     
    222247
    223248
    224 /**
     249/*
    225250 *
    226251 * Rechercher les champs non declares mais existants
     
    230255 */
    231256
    232 // liste les tables et les champs que le plugin et spip savent gerer
     257/**
     258 * Liste les tables et les champs que le plugin et spip savent gérer
     259 * mais qui ne sont pas déclarés à SPIP
     260 *
     261 * @param string $connect
     262 *     Nom du connecteur de base de données
     263 * @return array
     264 *     Tableau (table => couples(colonne => description SQL))
     265 */
    233266function extras_champs_utilisables($connect='') {
    234267        $tout = extras_champs_anormaux($connect);
     
    237270}
    238271
    239 // Liste les champs anormaux par rapport aux definitions de SPIP
    240 // (aucune garantie que $connect autre que la connexion principale fasse quelque chose)
     272/**
     273 * Liste les champs anormaux par rapport aux définitions de SPIP
     274 *
     275 * @note
     276 *     Aucune garantie que $connect autre que la connexion principale fasse quelque chose
     277 *
     278 * @param string $connect
     279 *     Nom du connecteur de base de données
     280 * @return array
     281 *     Tableau (table => couples(colonne => description SQL))
     282 */
    241283function extras_champs_anormaux($connect='') {
    242284        static $tout = false;
     
    284326}
    285327
    286 // etablit la liste de tous les champs de toutes les tables du connect donne
    287 // ignore la table 'spip_test'
     328/**
     329 * Établit la liste de tous les champs de toutes les tables de la connexion
     330 * sql donnée
     331 *
     332 * Ignore la table 'spip_test'
     333 *
     334 * @param string $connect
     335 *     Nom du connecteur de base de données
     336 * @return array
     337 *     Tableau (table => couples(colonne => description SQL))
     338 */
    288339function extras_base($connect='') {
    289340        $champs = array();
     
    297348}
    298349
    299 // liste les tables dispos dans la connexion $connect
     350
     351/**
     352 * Liste les tables SQL disponibles de la connexion sql donnée
     353 *
     354 * @param string $connect
     355 *     Nom du connecteur de base de données
     356 * @return array
     357 *     Liste de tables SQL
     358 */
    300359function extras_tables($connect='') {
    301360        $a = array();
     
    312371
    313372
    314 // liste les champs dispos dans la table $table de la connexion $connect
     373/**
     374 * Liste les champs dispos dans la table SQL de la connexion sql donnée
     375 *
     376 * @param string $table
     377 *     Nom de la table SQL
     378 * @param string $connect
     379 *     Nom du connecteur de base de données
     380 * @return array
     381 *     Couples (colonne => description SQL)
     382 */
    315383function extras_champs($table, $connect) {
    316384        $desc = sql_showtable($table, true, $connect);
  • _plugins_/champs_extras/core/trunk/inc/cextras_autoriser.php

    r57365 r65685  
    11<?php
     2
     3/**
     4 * Déclaration d'autorisations pour les champs extras
     5 *
     6 * @package SPIP\Cextras\Autorisations
     7**/
     8
     9// sécurité
    210if (!defined("_ECRIRE_INC_VERSION")) return;
    311
    4 // mes_fonctions peut aussi declarer des autorisations
    5 
    6 // fonction pour le pipeline autoriser
     12
     13/**
     14 * Fonction d'appel pour le pipeline autoriser
     15 * @pipeline autoriser
     16 */
    717function cextras_autoriser(){}
    818
     
    1121 * Retourne si une saisie peut s'afficher ou non
    1222 *
    13  * @param Array $saisie Saisie que l'on traite.
    14  * @param String $action Le type d'action : voir | modifier
    15  * @param String $table La table d'application : spip_articles
    16  * @param Int $id Identifiant de la table : 3
    17  * @param Array $qui L'auteur en cours
    18  * @param Array $opt Options de l'autorisation
    19  * @return Bool : la saisie peut elle s'afficher ?
     23 * Teste les options de restrictions de la saisie si il y en a
     24 * et calcule en fonction l'autorisation
     25 *
     26 * @param array $saisie
     27 *     Saisie que l'on traite.
     28 * @param string $action
     29 *     Le type d'action : voir | modifier
     30 * @param string $table
     31 *     La table d'application : spip_articles
     32 * @param int $id
     33 *     Identifiant de la table : 3
     34 * @param array $qui
     35 *     Description de l'auteur en cours
     36 * @param Array $opt
     37 *     Options de l'autorisation
     38 * @return Bool
     39 *     La saisie peut elle s'afficher ?
    2040**/
    2141function champs_extras_restrictions($saisie, $action, $table, $id, $qui, $opt) {
     
    7696                        if ($restriction and $restriction($opt['type'], $opt['id_objet'], $opt, $ids, $cible)) {
    7797                                return true;
    78                         }       
     98                        }
    7999                }
    80100                // aucune des restrictions n'a ete validee
     
    86106
    87107/**
    88   * Autorisation de voir un champ extra
    89   * autoriser('voirextra','auteur', $id_auteur,'',array('champ'=>'prenom', 'saisie'=>$saisie, ...));
    90   *
    91   * -> autoriser_auteur_voirextra_prenom_dist() ...
    92   */
     108 * Autorisation de voir un champ extra
     109 *
     110 * Cherche une autorisation spécifique pour le champ si elle existe
     111 * (autoriser_{objet}_voirextra_{colonne}_dist), sinon applique
     112 * l'autorisation prévue par la description de la saisie
     113 *
     114 * @example
     115 *     autoriser('voirextra','auteur', $id_auteur,'',
     116 *         array('champ'=>'prenom', 'saisie'=>$saisie, ...));
     117 *
     118 *      Appelle autoriser_auteur_voirextra_prenom_dist() si la fonction existe...
     119 *
     120 * @param  string $faire Action demandée
     121 * @param  string $type  Type d'objet sur lequel appliquer l'action
     122 * @param  int    $id    Identifiant de l'objet
     123 * @param  array  $qui   Description de l'auteur demandant l'autorisation
     124 * @param  array  $opt   Options de cette autorisation
     125 * @return bool          true s'il a le droit, false sinon
     126**/
    93127function autoriser_voirextra_dist($faire, $type, $id, $qui, $opt){
    94128        if (isset($opt['saisie'])) {
     
    106140
    107141/**
    108   * Autorisation de modifier un champ extra
    109   * autoriser('modifierextra','auteur', $id_auteur,'',array('champ'=>'prenom', 'saisie'=>$saisie, ...));
    110   *
    111   * -> autoriser_auteur_modifierextra_prenom_dist()
    112   */
     142 * Autorisation de modifier un champ extra
     143 *
     144 * Cherche une autorisation spécifique pour le champ si elle existe
     145 * (autoriser_{objet}_modifierextra_{colonne}_dist), sinon applique
     146 * l'autorisation prévue par la description de la saisie
     147 *
     148 * @example
     149 *     autoriser('modifierextra','auteur', $id_auteur,'',
     150 *         array('champ'=>'prenom', 'saisie'=>$saisie, ...));
     151 *     
     152 *     Appelle autoriser_auteur_modifierextra_prenom_dist() si elle existe
     153 *
     154 * @param  string $faire Action demandée
     155 * @param  string $type  Type d'objet sur lequel appliquer l'action
     156 * @param  int    $id    Identifiant de l'objet
     157 * @param  array  $qui   Description de l'auteur demandant l'autorisation
     158 * @param  array  $opt   Options de cette autorisation
     159 * @return bool          true s'il a le droit, false sinon
     160**/
    113161function autoriser_modifierextra_dist($faire, $type, $id, $qui, $opt){
    114162        if (isset($opt['saisie'])) {
     
    128176
    129177/**
    130  *
    131  * API pour aider les plus demunis
    132  * Permet d'indiquer que tels champs extras se limitent a telle ou telle rubrique
    133  * et cela en creant a la volee les fonctions d'autorisations adequates.
    134  *
    135  * Exemples :
    136  *   restreindre_extras('article', array('nom', 'prenom'), array(8, 12));
    137  *   restreindre_extras('site', 'url_doc', 18, true); // recursivement aux sous rubriques
    138  *
    139  * @param string $objet      objet possedant les extras
    140  * @param mixed  $noms       nom des extras a restreindre
    141  * @param mixed  $ids        identifiant (des rubriques par defaut) sur lesquelles s'appliquent les champs
    142  * @param string $cible      type de la fonction de test qui sera appelee, par defaut "rubrique". Peut aussi etre "secteur", "groupe" ou des fonctions definies
    143  * @param bool   $recursif   application recursive sur les sous rubriques ? ATTENTION, c'est gourmand en requetes SQL :)
    144  *
    145  * @return bool : true si on a fait quelque chose
     178 * Fonction d'aide pour créer des autorisations de champs spécifiques
     179 *
     180 * Permet d'indiquer que tels champs extras se limitent à telle ou telle rubrique
     181 * et cela en créant à la volée les fonctions d'autorisations adéquates.
     182 *
     183 * @example
     184 *     restreindre_extras('article', array('nom', 'prenom'), array(8, 12));
     185 *     restreindre_extras('site', 'url_doc', 18, true); // recursivement aux sous rubriques
     186 *
     187 * @param string $objet
     188 *     Objet possédant les extras
     189 * @param mixed $noms
     190 *     Nom des extras a restreindre
     191 * @param mixed $ids
     192 *     Identifiant (des rubriques par defaut) sur lesquelles s'appliquent les champs
     193 * @param string $cible
     194 *     Type de la fonction de test qui sera appelee, par defaut "rubrique". Peut aussi etre "secteur", "groupe" ou des fonctions definies
     195 * @param bool $recursif
     196 *     Application recursive sur les sous rubriques ? ATTENTION, c'est gourmand en requetes SQL :)
     197 * @return bool
     198 *     true si on a fait quelque chose
    146199 */
    147200function restreindre_extras($objet, $noms=array(), $ids=array(), $cible='rubrique', $recursif=false) {
     
    184237
    185238/**
    186  *
    187  * Fonction d'autorisation interne a la fonction restreindre_extras()
    188  * Teste si un objet a le droit d'afficher des champs extras
     239 * Fonction d'autorisation interne à la fonction restreindre_extras()
     240 *
     241 * Teste si un objet à le droit d'afficher des champs extras
    189242 * en fonction de la rubrique (ou autre defini dans la cible)
    190  * dans laquelle il se trouve et des rubriques autorisees
    191  *
    192  * On cache pour eviter de plomber le serveur SQL, vu que la plupart du temps
    193  * un hit demandera systematiquement le meme objet/id_objet lorsqu'il affiche
     243 * dans laquelle il se trouve et des rubriques autorisées
     244 *
     245 * On met en cache pour éviter de plomber le serveur SQL, vu que la plupart du temps
     246 * un hit demandera systématiquement le même objet/id_objet lorsqu'il affiche
    194247 * un formulaire.
    195248 *
    196  * @param string $objet      objet possedant les extras
    197  * @param int    $id_objet   nom des extras a restreindre
    198  * @param array  $opt        options des autorisations
    199  * @param mixed  $ids        identifiant(s) (en rapport avec la cible) sur lesquelles s'appliquent les champs
    200  * @param string $cible      type de la fonction de test qui sera appelee, par defaut "rubrique". Peut aussi etre "secteur", "groupe" ou des fonctions definies
    201  * @param bool   $recursif   application recursive sur les sous rubriques ? ATTENTION, c'est gourmand en requetes SQL :)
    202  *
    203  * @return bool : autorise ou non .
    204  */
     249 * @param string $objet
     250 *     Objet possédant les extras
     251 * @param int $id_objet
     252 *     Nom des extras a restreindre
     253 * @param array $opt
     254 *     Options des autorisations
     255 * @param mixed $ids
     256 *     Identifiant(s) (en rapport avec la cible) sur lesquelles s'appliquent les champs
     257 * @param string $cible
     258 *     Type de la fonction de test qui sera appelee, par defaut "rubrique".
     259 *     Peut aussi etre "secteur", "groupe" ou des fonctions definies
     260 * @param bool $recursif
     261 *     Application recursive sur les sous rubriques ? ATTENTION, c'est
     262 *     gourmand en requetes SQL :)
     263 * @return bool
     264 *     Autorisé ou non
     265**/
    205266function _restreindre_extras_objet($objet, $id_objet, $opt, $ids, $cible='rubrique', $recursif=false) {
    206267        static $autorise = array();
     
    225286
    226287/**
    227  *
    228  * Fonction d'autorisation interne a la fonction restreindre_extras()
    229  * Teste si un objet a le droit d'afficher des champs extras
     288 * Fonction d'autorisation interne à la fonction restreindre_extras()
     289 *
     290 * Teste si un objet à le droit d'afficher des champs extras
    230291 * en fonction de la rubrique (ou autre defini dans la cible)
    231  * dans laquelle il se trouve et des rubriques autorisees
    232  * Le dernier argument donne la colonne a chercher dans l'objet correspondant
    233  *
    234  * @param string $objet      objet possedant les extras
    235  * @param int    $id_objet   nom des extras a restreindre
    236  * @param array  $opt        options des autorisations
    237  * @param mixed  $ids        identifiant(s) (en rapport avec la cible) sur lesquelles s'appliquent les champs
    238  * @param bool   $_id_cible  nom de la colonne SQL cible (id_rubrique, id_secteur, id_groupe...)
    239  *
    240  * @return mixed : true : autorise, false : non autorise, 0 : incertain.
    241  *
    242  */
     292 * dans laquelle il se trouve et des rubriques autorisées
     293 *
     294 * Le dernier argument donne la colonne à chercher dans l'objet correspondant
     295 *
     296 * @param string $objet
     297 *     Objet possédant les extras
     298 * @param int $id_objet
     299 *     Nom des extras a restreindre
     300 * @param array $opt
     301 *     Options des autorisations
     302 * @param mixed $ids
     303 *     Identifiant(s) (en rapport avec la cible) sur lesquelles s'appliquent les champs
     304 * @param bool $_id_cible
     305 *     Nom de la colonne SQL cible (id_rubrique, id_secteur, id_groupe...)
     306 * @return bool|int
     307 *     - true : autorisé,
     308 *     - false : non autorisé,
     309 *     - 0 : incertain.
     310**/
    243311function _restreindre_extras_objet_sur_cible($objet, $id_objet, $opt, $ids, $_id_cible) {
    244312
     
    282350
    283351
     352/**
     353 * Fonction d'autorisation interne à la fonction restreindre_extras()
     354 * spécifique au test d'appartenance à une branche de rubrique
     355 *
     356 * @note ATTENTION, c'est gourmand en requetes SQL :)
     357 *
     358 * @see inc_restreindre_extras_objet_sur_rubrique_dist()
     359 * @param string $objet
     360 *     Objet possédant les extras
     361 * @param int $id_objet
     362 *     Nom des extras a restreindre
     363 * @param array $opt
     364 *     Options des autorisations
     365 * @param mixed $ids
     366 *     Identifiant(s) des branches de rubrique sur lesquelles s'appliquent les champs
     367 * @param bool $recursif
     368 *     Non utilisé
     369 * @return bool
     370 *     Autorisé ou non
     371 */
    284372function inc_restreindre_extras_objet_sur_branche_dist($objet, $id_objet, $opt, $ids, $recursif) {
    285373        return inc_restreindre_extras_objet_sur_rubrique_dist($objet, $id_objet, $opt, $ids, true);
     
    287375
    288376/**
    289  *
    290  * Fonction d'autorisation interne a la fonction restreindre_extras()
    291  * specifique au test d'appartenance a une rubrique
    292  *
    293  * @param string $objet      objet possedant les extras
    294  * @param int    $id_objet   nom des extras a restreindre
    295  * @param array  $opt        options des autorisations
    296  * @param mixed  $ids        identifiant(s) des rubriques sur lesquelles s'appliquent les champs
    297  * @param bool   $recursif   application recursive sur les sous rubriques ? ATTENTION, c'est gourmand en requetes SQL :)
    298  *
    299  * @return bool : autorise ou non .
     377 * Fonction d'autorisation interne à la fonction restreindre_extras()
     378 * spécifique au test d'appartenance à une rubrique
     379 *
     380 * @param string $objet
     381 *     Objet possédant les extras
     382 * @param int $id_objet
     383 *     Nom des extras a restreindre
     384 * @param array $opt
     385 *     Options des autorisations
     386 * @param mixed $ids
     387 *     Identifiant(s) des rubriques sur lesquelles s'appliquent les champs
     388 * @param bool $recursif
     389 *     Application récursive sur les sous rubriques ?
     390 *     ATTENTION, c'est gourmand en requetes SQL :)
     391 * @return bool
     392 *     Autorisé ou non
    300393 */
    301394function inc_restreindre_extras_objet_sur_rubrique_dist($objet, $id_objet, $opt, $ids, $recursif) {
     
    333426
    334427
    335 
    336 /**
    337  *
    338  * Fonction d'autorisation interne a la fonction restreindre_extras()
    339  * specifique au test d'appartenance a une rubrique
    340  *
    341  * @param string $objet      objet possedant les extras
    342  * @param int    $id_objet   nom des extras a restreindre
    343  * @param array  $opt        options des autorisations
    344  * @param mixed  $ids        identifiant(s) des rubriques sur lesquelles s'appliquent les champs
    345  * @param bool   $recursif   (non utilise)
    346  *
    347  * @return bool : autorise ou non .
     428/**
     429 * Fonction d'autorisation interne à la fonction restreindre_extras()
     430 * spécifique au test d'appartenance à un secteur
     431 *
     432 * @param string $objet
     433 *     Objet possédant les extras
     434 * @param int $id_objet
     435 *     Nom des extras a restreindre
     436 * @param array $opt
     437 *     Options des autorisations
     438 * @param mixed $ids
     439 *     Identifiant(s) des secteurs sur lesquelles s'appliquent les champs
     440 * @param bool $recursif
     441 *     Non utilisé
     442 * @return bool
     443 *     Autorisé ou non
    348444 */
    349445function inc_restreindre_extras_objet_sur_secteur_dist($objet, $id_objet, $opt, $ids, $recursif=false) {
     
    354450
    355451
     452/**
     453 * Fonction d'autorisation interne à la fonction restreindre_extras()
     454 * spécifique au test d'appartenance à un groupe de mot
     455 *
     456 * Alias de groupemot
     457 *
     458 * @see inc_restreindre_extras_objet_sur_groupemot_dist()
     459 * @param string $objet
     460 *     Objet possédant les extras
     461 * @param int $id_objet
     462 *     Nom des extras a restreindre
     463 * @param array $opt
     464 *     Options des autorisations
     465 * @param mixed $ids
     466 *     Identifiant(s) des groupes de mots sur lesquelles s'appliquent les champs
     467 * @param bool $recursif
     468 *     True pour appliquer aux branches d'un groupe de mot
     469 *     (avec plugin spécifique groupe de mots arborescents)
     470 * @return bool
     471 *     Autorisé ou non
     472 */
    356473function inc_restreindre_extras_objet_sur_groupe_dist($objet, $id_objet, $opt, $ids, $recursif) {
    357474        return inc_restreindre_extras_objet_sur_groupemot_dist($objet, $id_objet, $opt, $ids, $recursif);
     
    359476
    360477/**
    361  *
    362  * Fonction d'autorisation interne a la fonction restreindre_extras()
    363  * specifique au test d'appartenance a une rubrique
    364  *
    365  * @param string $objet      objet possedant les extras
    366  * @param int    $id_objet   nom des extras a restreindre
    367  * @param array  $opt        options des autorisations
    368  * @param mixed  $ids        identifiant(s) des rubriques sur lesquelles s'appliquent les champs
    369  * @param bool   $recursif   application recursive sur les sous rubriques ? ATTENTION, c'est gourmand en requetes SQL :)
    370  *
    371  * @return bool : autorise ou non .
     478 * Fonction d'autorisation interne à la fonction restreindre_extras()
     479 * spécifique au test d'appartenance à un groupe de mot
     480 *
     481 * @param string $objet
     482 *     Objet possédant les extras
     483 * @param int $id_objet
     484 *     Nom des extras a restreindre
     485 * @param array $opt
     486 *     Options des autorisations
     487 * @param mixed $ids
     488 *     Identifiant(s) des groupes de mots sur lesquelles s'appliquent les champs
     489 * @param bool $recursif
     490 *     True pour appliquer aux branches d'un groupe de mot
     491 *     (avec plugin spécifique groupe de mots arborescents)
     492 * @return bool
     493 *     Autorisé ou non
    372494 */
    373495function inc_restreindre_extras_objet_sur_groupemot_dist($objet, $id_objet, $opt, $ids, $recursif) {
  • _plugins_/champs_extras/core/trunk/paquet.xml

    r65577 r65685  
    22        prefix="cextras"
    33        categorie="outil"
    4         version="3.2.0"
     4        version="3.2.1"
    55        etat="stable"
    66        compatibilite="[3.0.0;3.0.*]"
Note: See TracChangeset for help on using the changeset viewer.