Dotclear


Ignore:
Timestamp:
04/26/13 16:23:16 (12 years ago)
Author:
Dsls <dsls@…>
Branch:
twig
Message:

Commented code, small tuning

File:
1 edited

Legend:

Unmodified
Added
Removed

  • inc/admin/class.dc.form.php

    r1154 r1156  
    1313 
    1414/** 
    15 * dcFormNode 
     15* dcFormNode Twig Node for Form handling 
    1616* 
    1717* @uses     Twig_Node 
    … …  
    5757class dcFormTokenParser extends Twig_TokenParser 
    5858{ 
     59    /** 
     60     * parse - parses form tag 
     61     * General syntax is : 
     62     *  {% form 'formname' %} 
     63     *  ... {{ form_field (...)}} 
     64     *  {% endform %} 
     65     * Specific attributes can be passed to the form, enabling to set 
     66     * attributes to the form template : 
     67     * {% form 'formname' with {'id':'myform'} %} 
     68     * @param mixed \Twig_Token Description. 
     69     * 
     70     * @access public 
     71     * 
     72     * @return mixed Value. 
     73     */ 
    5974     public function parse(Twig_Token $token) 
    6075     { 
    … …  
    6378          $name = $this->parser->getExpressionParser()->parseExpression(); 
    6479          $attr = null; 
     80          /* parse optional context */ 
    6581          if ($stream->test(Twig_Token::NAME_TYPE, 'with')) { 
    6682               $stream->next(); 
    … …  
    7086          $body = $this->parser->subparse(array($this,'decideBlockEnd'),true); 
    7187          $stream->expect(Twig_Token::BLOCK_END_TYPE); 
    72            
     88 
    7389          return new dcFormNode($name,$body,$attr,$token->getLine(),$this->getTag()); 
    7490     } 
    75       
     91 
    7692     public function decideBlockEnd(Twig_Token $token) 
    7793     { 
    7894          return $token->test('endform'); 
    7995     } 
    80       
     96 
    8197     public function getTag() 
    8298     { 
    … …  
    97113     protected $currentForm; 
    98114     protected $blocks; 
    99       
     115 
    100116     public function __construct($core) 
    101117     { 
    … …  
    106122          $this->currentForm = null; 
    107123     } 
    108       
     124 
    109125     public function initRuntime(Twig_Environment $environment) 
    110126     { 
    … …  
    116132          } 
    117133     } 
    118       
     134 
    119135     public function addTemplate($tpl) { 
    120136          $this->tpl[]=$tpl; 
    … …  
    129145          return array('dc_form' => $this); 
    130146     } 
    131       
     147 
    132148     public function getFunctions() 
    133149     { 
    … …  
    160176          ); 
    161177     } 
    162       
     178 
     179    /** 
     180     * isChoiceGroup - binding for twig function "_form_is_choice_group" 
     181     *                        returns whether a choice is a group or not 
     182     * @param mixed $choice the choice. 
     183     * 
     184     * @access public 
     185     * 
     186     * @return boolean true is choice is a group (optgroup). 
     187     */ 
    163188     public function isChoiceGroup($choice) 
    164189     { 
    165190          return is_array($choice); 
    166191     } 
    167       
     192 
     193    /** 
     194     * isChoiceSelected - binding for twig function "_form_is_choice_selected" 
     195     *                        returns whether current choice matches a value or not 
     196     * @param mixed $choice the choixe. 
     197     * @param mixed $value  the value to check matching. 
     198     * 
     199     * @access public 
     200     * 
     201     * @return boolean if choice is matching the value. 
     202     */ 
    168203     public function isChoiceSelected($choice,$value) 
    169204     { 
    170205          return $choice == $value; 
    171206     } 
    172       
     207 
     208    /** 
     209     * getTokenParsers returns token parsers 
     210     * 
     211     * @access public 
     212     * 
     213     * @return mixed Value. 
     214     */ 
    173215     public function getTokenParsers() 
    174216     { 
    175217          return array(new dcFormTokenParser()); 
    176218     } 
    177       
     219 
     220    /** 
     221     * hasWidget - binding for twig "haswidget" function 
     222     *    returns whether a widget is defined or not 
     223     *  
     224     * @param mixed $name the widget name. 
     225     * 
     226     * @access public 
     227     * 
     228     * @return boolean true if the widget exists. 
     229     */ 
    178230     public function hasWidget($name) { 
    179231          return isset($this->blocks[$name]); 
    180232     } 
     233 
     234    /** 
     235     * renderWidget - binding for 'widget' twig function 
     236     * behaves exactly like "block" function, except that a context 
     237     * can be passed to the function 
     238     *  
     239     * @param mixed $name the widget (block) name to render. 
     240     * @param mixed $attr Description the context for this block. 
     241     * 
     242     * 
     243     * @return mixed Value. 
     244     */ 
    181245     public function renderWidget($name,$attr) { 
    182246          if (!isset($this->blocks[$name])) 
    … …  
    189253     } 
    190254 
     255    /** 
     256     * getCurrentForm - returns current form if called within a {% form %} tag 
     257     * 
     258     * @access public 
     259     * 
     260     * @return string the current form. 
     261     */ 
    191262     public function getCurrentForm() { 
    192263          return $this->currentForm; 
    193264     } 
    194265 
     266    /** 
     267     * renderField - binding for 'form_field' twig function; renders a field 
     268     * 
     269     * @param mixed $name       field name as defined on php side. 
     270     * @param array $attributes html attributes for field (ex : class, ...). 
     271     * @param array $extra      extra attributes that may be template specific. 
     272     * 
     273     * @access public 
     274     * 
     275     * @return mixed Value. 
     276     */ 
    195277     public function renderField($name,$attributes=array(),$extra=array()) 
    196278     { 
    … …  
    213295     } 
    214296 
     297    /** 
     298     * renderHiddenWidgets -- renders all form hidden fields 
     299     * 
     300     * @access public 
     301     * 
     302     * @return mixed Value. 
     303     */ 
    215304     public function renderHiddenWidgets() 
    216305     { 
    … …  
    225314     } 
    226315 
     316    /** 
     317     * addForm -- registers a new form 
     318     * 
     319     * @param mixed \dcForm Description. 
     320     * 
     321     * @access public 
     322     * 
     323     * @return mixed Value. 
     324     */ 
    227325     public function addForm(dcForm $form) 
    228326     { 
    … …  
    230328     } 
    231329 
     330    /** 
     331     * beginForm -- displays form beginning 
     332     *  
     333     * @param mixed $name form name. 
     334     * @param array $attr extra attributes. 
     335     * 
     336     * @access public 
     337     * 
     338     * @return mixed Value. 
     339     */ 
    232340     public function beginForm($name,$attr=array()) 
    233341     { 
    … …  
    243351          } 
    244352     } 
    245       
     353 
     354    /** 
     355     * endForm -- displays form ending 
     356     *  
     357     * @access public 
     358     * 
     359     * @return mixed Value. 
     360     */ 
    246361     public function endForm() 
    247362     { 
    … …  
    263378class dcForm 
    264379{ 
     380     /** @var string form id */ 
    265381     protected $id; 
     382     /** @var string form name */ 
    266383     protected $name; 
     384     /** @var dcCore dcCore instance */ 
    267385     protected $core; 
     386     /** @var string form action */ 
    268387     protected $action; 
     388     /** @var array(dcField) list of form fields */ 
    269389     protected $fields; 
     390     /** @var string form method (GET/POST) */ 
    270391     protected $method; 
     392     /** @var array(dcField) list of submit fields */ 
    271393     protected $submitfields; 
     394     /** @var array(dcField) list of hidden fields */ 
    272395     protected $hiddenfields; 
     396     /** @var array(dcField) list of form errors */ 
    273397     protected $errors; 
    274       
    275      public function addTemplate($t) { 
    276           $this->core->tpl->getExtension('dc_form')->addTemplate($t); 
    277      } 
    278  
    279     /** 
    280      * addNonce -- adds dc nonce to form fields 
    281      *  
    282      * @access protected 
    283      * 
    284      * @return nothing 
    285      */ 
    286      protected function addNonce() 
    287      { 
    288           $this->addField( 
    289                new dcFieldHidden(array('xd_check'), 
    290                $this->core->getNonce()) 
    291           ); 
    292      } 
    293       
    294  
    295     /** 
    296      * Defines Name & ID from field 
    297      *  
    298      * @param mixed $nid either an array (name, id) or a string (name only, id will be set to null). 
    299      * 
    300      * @access protected 
    301      * 
    302      * @return nothing. 
    303      */ 
    304      protected function setNID($nid) 
    305      { 
    306           if (is_array($nid)) { 
    307                $this->name = $nid[0]; 
    308                $this->id = !empty($nid[1]) ? $nid[1] : null; 
    309           } 
    310           else { 
    311                $this->id = null; 
    312                $this->name = $nid; 
    313           } 
    314      } 
    315       
    316      public function getContext() { 
    317           return array(); 
    318      } 
    319398 
    320399    /** 
    … …  
    322401     *  
    323402     * @param mixed  $core   dotclear core 
    324      * @param mixed  $name   form name 
     403     * @param mixed  $name   form name - can be an array (name,id) 
    325404     * @param mixed  $action form action 
    326405     * @param string $method form method ('GET' or 'POST') 
    … …  
    345424          } 
    346425     } 
    347       
     426 
     427    /** 
     428     * addTemplate - Adds a template file to enrich form fields 
     429     *  
     430     * @param string $t the template file. 
     431     * 
     432     * @access public 
     433     */ 
     434     public function addTemplate($t) { 
     435          $this->core->tpl->getExtension('dc_form')->addTemplate($t); 
     436     } 
     437 
     438    /** 
     439     * addNonce -- adds dc nonce to form fields 
     440     * 
     441     * @access protected 
     442     * 
     443     * @return nothing 
     444     */ 
     445     protected function addNonce() 
     446     { 
     447          $this->addField( 
     448               new dcFieldHidden(array('xd_check'), 
     449               $this->core->getNonce()) 
     450          ); 
     451     } 
     452 
     453    /** 
     454     * Defines Name & ID from field 
     455     * 
     456     * @param mixed $nid either an array (name, id) or a string 
     457     *                   (name only, id will be set to null). 
     458     * 
     459     * @access protected 
     460     * 
     461     * @return nothing. 
     462     */ 
     463     protected function setNID($nid) 
     464     { 
     465          if (is_array($nid)) { 
     466               $this->name = $nid[0]; 
     467               $this->id = !empty($nid[1]) ? $nid[1] : null; 
     468          } 
     469          else { 
     470               $this->id = null; 
     471               $this->name = $nid; 
     472          } 
     473     } 
     474 
     475    /** 
     476     * getContext - returns form context (to fill-in twig context for instance), 
     477     *                   if any 
     478     * 
     479     * @access public 
     480     * 
     481     * @return array the form context. 
     482     */ 
     483     public function getContext() { 
     484          return array(); 
     485     } 
     486 
    348487 
    349488    /** 
    350489     * Returns form name 
    351      *  
     490     * 
    352491     * @access public 
    353492     * 
    … …  
    358497          return $this->name; 
    359498     } 
    360       
     499 
     500    /** 
     501     * getErrors - returns form errors 
     502     * 
     503     * @access public 
     504     * 
     505     * @return array the list of errors. 
     506     */ 
    361507     public function getErrors() 
    362508     { 
    363509          return $this->errors; 
    364510     } 
    365       
     511 
     512    /** 
     513     * addField - adds a new field to form 
     514     * 
     515     * @param mixed \dcField the field to add. 
     516     * 
     517     * @access public 
     518     * 
     519     * @return dcForm the form instance (therefore addField can be chained) 
     520     */ 
    366521     public function addField(dcField $f) 
    367522     { 
    … …  
    373528          } 
    374529          $this->fields[$f->getName()] = $f; 
    375            
     530 
    376531          return $this; 
    377532     } 
    378       
     533 
     534    /** 
     535     * removeField - removes a field 
     536     * 
     537     * @param mixed \dcField the field to remove. 
     538     * 
     539     * @access public 
     540     * 
     541     * @return dcForm the form instance (therefore addField can be chained) 
     542     */ 
    379543     public function removeField(dcField $f) { 
    380544          $n = $f->getName(); 
    … …  
    382546               unset($this->fields[$n]); 
    383547          } 
    384  
    385      } 
     548          return $this; 
     549     } 
     550 
     551 
     552    /** 
     553     * renameField - renames a field 
     554     * 
     555     * @param mixed $field   the field to rename. 
     556     * @param mixed $newname new field name 
     557     * 
     558     * @access public 
     559     * 
     560     * 
     561     * @return dcForm the form instance (therefore addField can be chained) 
     562     */ 
    386563     public function renameField($field,$newname) { 
    387564          $oldname = $field->getName(); 
    … …  
    391568               $this->fields[$newname] = $field; 
    392569          } 
    393      } 
     570          return $this; 
     571     } 
     572 
     573    /** 
     574     * begin - begins a form. Should be not be called directly, it is handled 
     575     *              by the Twig Form extension. 
     576     * 
     577     * @param array $attr form extra attributes, if any. 
     578     * 
     579     * @access public 
     580     * 
     581     * @return mixed Value. 
     582     */ 
    394583     public function begin($attr=array()) 
    395584     { 
    … …  
    403592               $attr); 
    404593     } 
    405       
     594 
     595    /** 
     596     * end - ends a form. Should be not be called directly, it is handled 
     597     *              by the Twig Form extension. 
     598     * 
     599     * @access public 
     600     * 
     601     * @return mixed Value. 
     602     */ 
    406603     public function end() 
    407604     { 
    408           echo '</form>'; 
    409      } 
    410       
     605          $this->core->tpl->getExtension('dc_form')->renderWidget( 
     606               'endform'); 
     607     } 
     608 
     609    /** 
     610     * __isset - magic method isset, checks whether a field exists 
     611     *                   example : if (isset($form->field1)) 
     612     * 
     613     * @param mixed $name field name to check. 
     614     * 
     615     * @access public 
     616     * 
     617     * @return boolean true if the field exists. 
     618     */ 
    411619     public function __isset($name) 
    412620     { 
    413621          return isset($this->fields[$name]); 
    414622     } 
    415       
     623 
     624    /** 
     625     * __get -- magic method, retrieves a field from a form 
     626     *              example : $f = $form->field1 
     627     * 
     628     * @param mixed $name Description. 
     629     * 
     630     * @access public 
     631     * 
     632     * @return mixed Value. 
     633     */ 
    416634     public function __get($name) 
    417635     { 
    … …  
    420638     } 
    421639 
     640    /** 
     641     * __set -- magic method, sets a value for a given form field 
     642     *              example : $form->field1 = 'my value'; 
     643     * 
     644     * @param mixed $name  the field name. 
     645     * @param mixed $value the field value. 
     646     * 
     647     * @access public 
     648     */ 
    422649     public function __set($name,$value) 
    423650     { 
    … …  
    427654     } 
    428655 
    429      public function isSubmitted() 
     656/*   public function isSubmitted() 
    430657     { 
    431658          $from = $this->method == 'POST' ? $_POST : $_GET; 
    432659     } 
    433  
     660*/ 
     661 
     662    /** 
     663     * setupFields - initializes form & fields from $_GET or $_POST 
     664     *  
     665     * @access protected 
     666     */ 
    434667     protected function setupFields() { 
    435668          $from = $this->method == 'POST' ? $_POST : $_GET; 
    … …  
    439672     } 
    440673 
     674    /** 
     675     * handleActions - handle appropriate actions, according to submitted fields 
     676     *  
     677     * @param mixed $submitted the fields that have been submitted. 
     678     * 
     679     * @access protected 
     680     */ 
    441681     protected function handleActions($submitted) { 
    442682          foreach ($submitted as $f) { 
    … …  
    448688     } 
    449689 
     690    /** 
     691     * getSubmittedFields - retrieves fields that have been submitted, if any 
     692     * 
     693     * @access protected 
     694     * 
     695     * @return array the list of submitted fields. 
     696     */ 
    450697     protected function getSubmittedFields() { 
    451698          $s = array(); 
    … …  
    458705     } 
    459706 
     707    /** 
     708     * setup - sets up the form, given the parameters given to the page 
     709     *              should be called after fields have been defined. 
     710     * 
     711     * @access public 
     712     * 
     713     * @return mixed Value. 
     714     */ 
    460715     public function setup() 
    461716     { 
    … …  
    465720     } 
    466721 
     722    /** 
     723     * check - checks if the form is valid, errors are filled in, in case of 
     724     *              incorrect fields 
     725     * 
     726     * @access public 
     727     */ 
    467728     public function check() 
    468729     { 
    … …  
    476737          } 
    477738     } 
    478       
     739 
     740    /** 
     741     * getHiddenFields - returns the list of hidden fields 
     742     * 
     743     * @access public 
     744     * 
     745     * @return array the list of hidden fields. 
     746     */ 
    479747     public function getHiddenFields() 
    480748     { 
    … …  
    488756abstract class dcField implements Countable 
    489757{ 
     758     /** @var string field options */ 
    490759     protected $options; 
     760     /** @var string field name */ 
    491761     protected $name; 
     762     /** @var string field values */ 
    492763     protected $values; 
     764     /** @var string field id */ 
    493765     protected $id; 
     766     /** @var boolean true if field can contain multiple values */ 
    494767     protected $multiple; 
     768     /** @var boolean true if the field has been defined */ 
    495769     protected $defined; 
    496       
    497      protected function setNID($nid) 
    498      { 
    499           if (is_array($nid)) { 
    500                $this->name = $nid[0]; 
    501                $this->id = !empty($nid[1]) ? $nid[1] : null; 
    502           } 
    503           else { 
    504                $this->id = $this->name = $nid; 
    505           } 
    506      } 
    507       
     770 
     771    /** 
     772     * __construct - constructor 
     773     * 
     774     * @param string $name   Name or array(name,id) for field. 
     775     * @param array $values  field values. 
     776     * @param array $options options 
     777     * 
     778     * Currently globally available options are : 
     779     *  * multiple : true/false. Enable multiple values for field 
     780     * @access public 
     781     * 
     782     * @return mixed Value. 
     783     */ 
    508784     public function __construct($name,$values,$options=array()) 
    509785     { 
    … …  
    518794 
    519795     } 
    520       
     796 
     797    /** 
     798     * setNID - defines fiels name & id 
     799     * 
     800     * @param mixed $nid field name (string) or an array containing  name (1st) 
     801     *                   and id (2nd field). 
     802     * 
     803     * @access protected 
     804     */ 
     805     protected function setNID($nid) 
     806     { 
     807          if (is_array($nid)) { 
     808               $this->name = $nid[0]; 
     809               $this->id = !empty($nid[1]) ? $nid[1] : null; 
     810          } 
     811          else { 
     812               $this->id = $this->name = $nid; 
     813          } 
     814     } 
     815 
     816    /** 
     817     * setValue - sets field value 
     818     * 
     819     * @param mixed $value  field value. 
     820     * @param int   $offset value offset to define (default 0). 
     821     * 
     822     * @access public 
     823     */ 
    521824     public function setValue($value,$offset=0) { 
    522825          $this->values[$offset] = $value; 
    523826     } 
    524827 
     828    /** 
     829     * setValues - set field values 
     830     * 
     831     * @param mixed $values the array of values. If not an array, the parameter 
     832     *                      will be converted to an array containing the value 
     833     * 
     834     * @access public 
     835     */ 
    525836     public function setValues($values) { 
    526837          if (is_array($values)) { 
    … …  
    532843     } 
    533844 
     845    /** 
     846     * getValues - return field values 
     847     * 
     848     * @access public 
     849     * 
     850     * @return mixed the array of values. 
     851     */ 
    534852     public function getValues() { 
    535853          return $this->values; 
    536854     } 
    537855 
     856    /** 
     857     * getValue - retrieves a field value 
     858     * 
     859     * @param int $offset value offset (by default 1st value is returned). 
     860     * 
     861     * @access public 
     862     * 
     863     * @return mixed the field value. 
     864     */ 
    538865     public function getValue($offset=0) { 
    539866          if (isset($this->values[$offset])) { 
    … …  
    542869     } 
    543870 
     871    /** 
     872     * addValue -- Adds a value to the field values. 
     873     *  
     874     * @param mixed $value Description. 
     875     * 
     876     * @access public 
     877     * 
     878     * @return mixed Value. 
     879     */ 
    544880     public function addValue($value) { 
    545881          $this->values[] = $value; 
    … …  
    551887     } 
    552888 
     889    /** 
     890     * count -- returns the number of field values 
     891     *  
     892     * @access public 
     893     * 
     894     * @return integer the number of values. 
     895     */ 
    553896     public function count() { 
    554897          return count($this->values); 
    … …  
    562905     abstract public function getWidgetBlock(); 
    563906      
     907 
     908    /** 
     909     * getAttributes - retrieve field attributes that will be given to the 
     910     *                   twig widget 
     911     * 
     912     * @param array $options extra options given to the widget 
     913     * 
     914     * @access public 
     915     * 
     916     * @return array the attributes. 
     917     */ 
    564918     public function getAttributes($options) 
    565919     { 
    … …  
    581935          return $attr; 
    582936     } 
    583       
     937 
     938    /** 
     939     * getDefaultValue - returns field default value 
     940     *  
     941     * @access public 
     942     * 
     943     * @return mixed the field default value. 
     944     */ 
    584945     public function getDefaultValue() { 
    585946          return ''; 
    586947     } 
    587948 
     949    /** 
     950     * getName - returns field name 
     951     *  
     952     * @access public 
     953     * 
     954     * @return string the field name. 
     955     */ 
    588956     public function getName() 
    589957     { 
    … …  
    591959     } 
    592960 
     961    /** 
     962     * setName - defines field name and/or field id 
     963     *  
     964     * @param mixed $name the field name or an array containing name and id. 
     965     * 
     966     * @access public 
     967     */ 
    593968     public function setName($name) { 
    594969          $this->setNID($name); 
    595970     } 
    596971 
     972    /** 
     973     * check - checks whether the field is valid or not - raises an exception  
     974     *              if not valid 
     975     * @access public 
     976     */ 
    597977     public function check() 
    598978     { 
    … …  
    604984          } 
    605985     } 
    606       
     986 
     987    /** 
     988     * parseValues - parses field value from context (GET or POST) 
     989     *                   and returns parsed value(s) 
     990     *                   NOTE : the field is not updated with this method 
     991     *                   use setup() to also update the field. 
     992     * @param mixed $from the context (usually $_GET or $_POST). 
     993     * 
     994     * @access public 
     995     * 
     996     * @return array the list of values (empty array if no value). 
     997     */ 
    607998     public function parseValues($from) { 
    608999          if (isset($from[$this->name])) { 
    … …  
    6161007     } 
    6171008 
     1009    /** 
     1010     * setup - sets up the field from conetxt (GET or $POST) 
     1011     * 
     1012     * @param mixed $from the context (usually $_GET or $_POST). 
     1013     * 
     1014     * @access public 
     1015     * 
     1016     * @return mixed Value. 
     1017     */ 
    6181018     public function setup($from) 
    6191019     { 
    … …  
    6241024          } 
    6251025     } 
    626       
     1026 
     1027    /** 
     1028     * isDefined - returns whether the field is defined or not 
     1029     *                   (a field is defined if some values are set after setup()) 
     1030     * @access public 
     1031     * 
     1032     * @return mixed Value. 
     1033     */ 
    6271034     public function isDefined() 
    6281035     { 
    … …  
    7321139{ 
    7331140     protected $combo; 
    734       
     1141 
    7351142     public function __construct($name,$value,$combo,$options=array()) 
    7361143     { 
    … …  
    7381145          parent::__construct($name,$value,$options); 
    7391146     } 
    740       
     1147 
    7411148     public function getWidgetBlock() 
    7421149     { 
Note: See TracChangeset for help on using the changeset viewer.

Sites map