====== Pxxo_Widget_Input ======

Les widgets qui dérivent de ''Pxxo_Widget_Input'' sont des champs de formulaires (Text, Textarea, Captcha ...).

''Pxxo_Widget_Input'' est un widget particulier, c'est une classe abstraite, il ne peut pas être instancié directement. Il propose  une interface générique qui devra être respectée par tous les widgets qui en dérivent (Text,Textarea,Password...). Nous obtenons ainsi une série de widgets homogènes qui permet alors au [[:fr:doc:pxxo_widget_form|widget Form]] de construire des formulaires complets constitués de ces widgets.


















===== Liste des champs disponibles =====
  * [[:fr:doc:pxxo_widget_input_text|Text]] : un champ texte très simple
  * [[:fr:doc:pxxo_widget_input_textmultiple|Textmultiple]] : le même que le champ [[:fr:doc:pxxo_widget_input_text|Text]] mais permet de saisir plusieurs textes (sans connaître leur nombre à l'avance)
  * [[:fr:doc:pxxo_widget_input_textarea|Textarea]]
  * [[:fr:doc:pxxo_widget_input_password|Password]]
  * [[:fr:doc:pxxo_widget_input_mail|Mail]]
  * [[:fr:doc:pxxo_widget_input_hidden|Hidden]]
  * [[:fr:doc:pxxo_widget_input_calendar|Calendar]]
  * [[:fr:doc:pxxo_widget_input_radio|Radio]]
  * [[:fr:doc:pxxo_widget_input_select|Select]]
  * [[:fr:doc:pxxo_widget_input_file|File]]
  * FIXME Html (ou plutôt Widget pour permettre d'insérer des widgets entiers)
  * [[:fr:doc:pxxo_widget_input_tagging|Tagging]]
  * [[:fr:doc:pxxo_widget_input_star|Star]]
  * [[:fr:doc:pxxo_widget_input_csrf|Csrf]]
  * FIXME Wiki
  * FIXME Captcha
  * [[:fr:doc:pxxo_widget_input_livesearch|Livesearch]]
  * [[:fr:doc:pxxo_widget_input_livesearch_suggest|Livesearch_Suggest]]
  * [[:fr:doc:pxxo_widget_input_wysiwyg|Wysiwyg]]
  * [[:fr:doc:pxxo_widget_input_checkbox|Checkbox]]
  * [[:fr:doc:pxxo_widget_input_duallist|Duallist]]
  * [[:fr:doc:pxxo_widget_input_editlist|Editlist]]
  * [[:fr:doc:pxxo_widget_input_Basket|Basket]]
  * [[:fr:doc:pxxo_widget_input_query|Query]]
  * [[:fr:doc:pxxo_widget_input_color|Color]]

__Remarque :__ Tous ces widgets dérivent de la classe abstraite ''Pxxo_Widget_Input''. Pour en développer un nouveau, veuillez consulter [[:fr:doc:pxxo_widget_input#procedure_pour_developper_un_widget_input|la documentation développeur]].

















===== Paramètres =====

Tous ces paramètres sont communs à tous les types de champs (Text, Textarea, Password, ...) :
^ Nom ^ Type ^ Valeur par défaut ^ Description ^
| id | String | null | L'identifiant du champ. Indiquer une valeur permet de retrouver plus facilement ses petits lorsque l'on récupère les résultats du formulaire (facultatif : si aucun identifiant n'est indiqué, un entier généré automatiquement sera utilisé en guise d'identifiant) |
| type | String | null | Le type du champ (obligatoire si le paramètre 'class' n'est pas indiqué) |
| value | Mixed | null | La valeur initiale du champ (son format dépend du type du champ considéré). |
| label | String | "" | Le texte descriptif du champ. Il sera en général affiché sur sa gauche. **ATTENTION** : uniquement valable si l'input est utilisé par le Widget Form. |
| size | Mixed | null | La taille du champ (son format dépend du type du champ considéré, certains champs ignorent ce paramètre). |
| required | Bool | false | Permet d'indiquer qu'un champ est obligatoire |
| disabled | Bool | false | Permet d'indiquer qu'un champ est désactivé (grisé) |
| readonly | Bool | false | Permet d'indiquer qu'un champ est en lecture seule (très semblable à ''disabled'' mais le texte reste sélectionnable) |
| validate_callback | [[http://fr2.php.net/manual/fr/language.pseudo-types.php#language.types.callback|callback]] | null | Permet d'indiquer une callback qui se chargera de valider le champ lors de sa soumission. Son premier paramètre est un tableau contenant les paramètres du champ (la clé "result" sera particulièrement utile). Son second paramètre (facultatif) est une référence vers l'instance du formulaire parent. Les éventuelles erreurs doivent être retournées par la callback sous la forme d'un tableau de chaînes de caractères. |
| class | String | null | Le nom de la classe de l'input (obligatoire si 'type' n'est pas indiqué). Ce paramètre est utilisé pour instancier un champ personnalisé (spécifique pour votre application). (cf exemple ci-dessous) |


FIXME : expliquer le champ result (important pour les callbacks du form) ...


===== Exemples =====

Un exemple d'intégration de champs Text avec validation personnalisée dans un formulaire :
<code php>
require_once "Pxxo/Widget/Form.php";
$params = array();
$params['inputs'][] = array('id'       => 'id_disabled',
                            'label'    => 'Un input text disabled',
                            'type'     => 'text',
                            'value'    => 'valeur disabled',
                            'size'     => 50,
                            'required' => true,
                            'disabled' => true,
                            );
$params['inputs'][] = array('id'       => 'id_readonly',
                            'label'    => 'Un input text en lecture seule',
                            'type'     => 'text',
                            'value'    => 'valeur readonly',
                            'size'     => 50,
                            'required' => true,
                            'readonly' => true,
                            );
$params['inputs'][] = array('id'       => 'id_text_numeric',
                            'label'    => 'Un input avec validation personnalisée',
                            'type'     => 'text',
                            'validate_callback' => 'numerictext_validate_callback',
                            );
$o = new Pxxo_Widget_Form($params);

function numerictext_validate_callback($input)
{
    $errors = array();
    if (!is_numeric($input['result']))
        $errors[] = 'Ce champ doit impérativement être un nombre';
    if (is_numeric($input['result']) && $input['result'] <= 100)
        $errors[] = 'Ce nombre doit être supérieur à 100';
    if (is_numeric($input['result']) && $input['result'] <= 10)
        $errors[] = 'Ce nombre doit être supérieur à 10';
    return $errors;
}
</code>









===== Procédure pour développer un widget Input =====

Cette procédure explique comment créer un nouveau widget Input.
  - Votre widget doit dériver de ''Pxxo_Widget_Input'' : <code php>class Pxxo_Widget_Input_Text extends Pxxo_Widget_Input</code>
  - Il doit ensuite suivre certaines règles (interface) que propose ''Pxxo_Widget_Input'' :
    * La variable **''$value''** doit être utilisé pour indiquer les valeurs initiales à charger dans le champ à son affichage initiale. C'est ce paramètre que l'utilisateur du widget (le développeur) utilisera pour initialiser le widget.
    * La variable **''$result''** sera rempli avec les valeurs soumisent du champ. Si l'utilisateur n'a rien modifié, sa valeur sera logiquement identique à celle de ''$value''.
    * La variable **''$displayed_value''** doit être utilisée par votre template pour initialiser les données de votre champ. Sa valeur sera soit le contenu de ''$value'', soit le contenu de ''$result'' si le formulaire a été soumit. La méthode ''print_attribut'' peut-être utilisée dans le cas où la valeur est affichée en tant qu'attribut, exemple :<code php>
<?php $Self->print_attribut('value', $displayed_value); ?>
</code>
    * La méthode **''hook_validate()''** peut-être surchargée pour valider plus finement le champ. La méthode renvoie un tableau vide si le champ est valide et un tableau d'erreurs (chaîne de caractères) au cas où le champ n'est pas valide.
    * La méthode **''hook_assign_submitted_value()''** peut-être surchargée pour assigner l'attribut ''$result'' avec les données soumisent de votre champ. Cette opération est utile lorsque les données du champ ne sont pas directement récupérables de cette façon :<code php>$this->result = $this->getInputVar($this->get_name_attribute());</code>
    * La méthode **''hook_assign_displayed_value_from_result()''** peut-être surchargée pour altérer la valeur de ''$displayed_value'' une fois que les données soumisent ont été récupéré. Par exemple lorsqu'un mot de passe est soumis on ne désire pas l'afficher après soumission du formulaire pour des raisons de sécurité.
    * La méthode **''hook_assign_displayed_value_from_init_value()''** peut-être surchargée pour altérer la valeur de ''$displayed_value'' lorsque le formulaire s'affiche pour la première fois (avant d'être soumis). En général pas besoin de surcharger cette méthode.
    * La méthode **''hook_assign_modified_attribute()''** peut être surchargée pour calculer et assigner la valeur de l'attribut ''modified''. Cet attribut doit vaut ''true'' lorsque la valeur soumise (''$result'') est différente de la valeur initiale fournit par le développeur (''$value''), il vaut ''false'' sinon.
    * La méthode **''hook_on_pre_submit()''** peut être surchargée. Elle sera exécutée par le formulaire au tout début de la procédure de soumission. L'input peut ainsi réaliser des opérations préliminaires juste avant de passer à la validation.
    * La méthode **''hook_on_post_form_submit()''** peut être surchargée. Elle sera exécutée par le formulaire à la fin de la procédure de soumission si tout s'est bien passé (toutes les validations sont sans erreurs). L'input peut ainsi réaliser des opérations post-opératoires dans le cas où tout s'est bien passé.
    * La méthode **''hook_get_onsubmit_javascript()''** peut être surchargée. Elle doit retourner du code javascript qui sera inséré par le formulaire dans son attribut "onsubmit".


Voici un exemple de création d'un champ spécifique :
<code php>
require_once "Pxxo/Widget/Form.php";
require_once "Pxxo/Widget/Input.php";


class my_customized_input extends Pxxo_Widget_Input
{
    /**
     * @var     array paramètres spécifique pour ce type champ
     * @access	private
     */
    var $_params = array('maxlength');
    /**
     * @var     taille maximun du texte à saisir
     * @access	public
     */
    var $maxlength = 100;
    function __construct($params = array())
    {
        parent::__construct($params, __FILE__);
    }    
    function index()
    {
        parent::index();
        $this->setTemplateRaw('index',
                              sprintf('<input type="text" %s %s %s %s %s %s />',
                                      $this->get_common_attributs(),
                                      $this->get_attribut('value', $this->value),
                                      $this->get_attribut('size', $this->size),
                                      $this->get_attribut('disabled', $this->disabled === true ? 'disabled' : null),
                                      $this->get_attribut('readonly', $this->readonly === true ? 'readonly' : null),
                                      $this->get_attribut('maxlength', $this->maxlength)
                                      )
                              );
    }

    function hook_validate($submitted_value)
    {
        $errors = parent::hook_validate($submitted_value);
        if (mb_strlen($submitted_value,'UTF8') > $this->maxlength)
            $errors[] = sprintf('Le texte ne doit pas dépasser %d caractères',$this->maxlength);
        return $errors;
    }    
}



$params = array();
$params['inputs'] = array();
$params['inputs'][] = array('id'       => 'id_de_mon_test2',
                            'label'    => 'Exemple d\'input personnalise',
                            'class'    => 'my_customized_input',
                            'size'     => 50,
                            'required' => true,
                            );
$o = new Pxxo_Widget_Form($params);
$o->addDecorator('Pxxo_Widget_Decorator_Core');
$o->main();
$o->dump();
</code>