Date de publication: le lundi 26 mai 2008 à 18h44
Dernière modification: par Pascal BOYER le mercredi 6 octobre 2010 à 10h30
« Article précédent: Extending eZDataType -- Etendre la classe eZDataType
» Article suivant: View and edit templates -- Templates de vue et d'édition

21 May 2008 6:14  

The filter extension gives you a powerful API to block or sanitize submitted input. The UserInput component builds an object-oriented API on top of the extension. This helps us to put the form parsing code in a separate class and thereby makes the rest of the code much more readable.
L'extension Filter vous offre une puissante API pour bloquer ou nettoyer les entrées soumises. Le composant  UserInput   construit une API orientée objet au sommet de l'extension. Ceci facilite la mise en place de code de traitement du formulaire dans une classe séparée rendant le reste du code beaucoup plus lisible.

Forms are objects too! / Les formulaires sont aussi des objets !

Do you also dislike PHP code where form parsing and business logic are mixed together? Why not give forms the appreciation they deserve and put them in their own PHP classes? All code that is necessary to answer the question “Can we process this data?” should be put in a form class. Code that answers the question “What went wrong with the input?” should be put in the form class too, resulting in elegant controllers in your MVC.
Détestez-vous le code PHP où l'analyse des formulaires et l'analyse logique sont mêlées ? Pourquoi ne pas réserver aux formulaires le sort qu'ils méritent et les mettre dans leurs propres classes PHP ? Le code nécessaire pour répondre à la question « Pouvons-nous traiter cette donnée ?» doit être placé dans une classe formulaire. Le code répondant à la question « Quel problème est arrivé avec l'entrée saisie ?» doit également être placé dans une classe de formulaire, obtenant ainsi d'élégants contrôleurs dans votre MVC.

The UserInput component helps by providing a predefined structure to declare the input you are expecting. Consider the following screenshot of a more complicated datatype:
Le composant UserInput vous aide à déclarer l'entrée que vous attendez en fournissant une structure pré-définie. Considérez la capture d'écran suivante illustrant un datatype plus compliqué:

The indicated input fields were used as an example to write a valid form definition for the UserInput component:
Les champs de saisie indiqués (par une flèche rouge) ont été utilisés comme exemple pour écrire une définition de formulaire valide pour le composant UserInput:

$formDef = array(
'isnodeplacement_value' => new ezcInputFormDefinitionElement(
 ezcInputFormDefinitionElement::OPTIONAL, 'boolean' ),
 'option_name_array' => new ezcInputFormDefinitionElement(
 ezcInputFormDefinitionElement::OPTIONAL, 'string', NULL, FILTER_REQUIRE_ARRAY ),
 'move_option_up' => new ezcInputFormDefinitionElement(
 ezcInputFormDefinitionElement::OPTIONAL, 'string', NULL, FILTER_REQUIRE_ARRAY ),
 'newoption_button' => new ezcInputFormDefinitionElement(
 ezcInputFormDefinitionElement::OPTIONAL, 'string' ));

Such an array can then be placed in a class representing the form object. One major benefit of this approach is that all possible input variables are defined in one place.
Un tel tableau peut être placé dans une classe représentant l'objet formulaire. Le bénéfice majeur de cette approche est que toutes les variables d'entrée possibles sont définies en seul endroit.

Another method I put in my form objects is isValid(). Since you have all the validation logic in the form class, you could even check the validity of a form in one line:
J'ai mis en place une autre méthode dans mes objets formulaire: isValid(). Puisque vous avez toutes les procédures (???) de validation dans la classe formulaire, vous pouvez même, en une ligne, contrôler la validité d'un formulaire:

if( MyFormClass::getInstance()->isValid() ) ....

Now let's see how this approach can be applied for our datatype.
Regardons à présent comment cette approche peut être appliquée à notre datatype.

UserInput and the ymcDateTime datatype / UserInput et le datatype ymcDateTime 

If you had a simple website with one form containing fields like “firstname”, “surname” and “email” then you can easily put these field names in the array keys of the form definition. The form declaration method described in the previous section is a bit more difficult to deal with when it comes to datatypes.
Si vous disposez d'un simple site web pourvu d'un formulaire contenant des champs tels que prénom, nom de famille et e-mail alors vous pouvez facilement mettre les noms de ces champs dans les clefs d'un tableau de la définition du formulaire. La méthode de déclaration du formulaire décrite dans la précédente section est quelque peu plus compliquée à mettre en œuvre avec des datatypes.

Remember that a content class in eZ Publish is not represented by a simple form hard-coded in your PHP script. In fact, the form of a content class (or object) is dynamically created based on the included datatypes. Recall that our example content class contains two attributes of the same datatype. If you were to hard-code the field names, there would be no way to determine whether an input field named “day” belonged to the “from” or the “to” attribute.
Souvenez-vous qu'une classe de contenu de eZ Publish n'est pas représentée par un simple formulaire codé en dur dans votre script PHP. En fait, le formulaire d'une classe de contenu (ou d'un objet) est dynamiquement créé à partir des datatypes inclus. Rappelons que notre exemple de classe de contenu contient deux attributs basés sur le même datatype. Si vous codiez en dur les noms des champs, il n'y aurait alors aucun moyen de déterminer si un champ de saisie nommé jour appartient ou non à l'attribut « de» ou « à».

You need to add another piece of information to the input field names to indicate the attribute to which an input field belongs. This information is provided by a suffix consisting of the field name and the ID of the attribute to which it belongs. To be completely safe, another string is prefixed to the field name, indicating that it belongs to an attribute of a content class and further specifying the datatype. Therefore, your final field name could be “ContentClass_mydatatype_myfield_123”.
Vous devez ajouter une information supplémentaire aux noms des champs de saisie afin d'indiquer l'attribut auquel appartient le champ de saisie. Cette information est fournie par un suffixe composé du nom du champ et de l'ID de l'attribut auquel il appartient. Pour être tout à fait sûr, une autre chaîne de caractères est préfixée du nom du champ (???) indiquant qu'il appartient à un attribut d'une classe de contenu et donnant plus de précisions sur le datatype (???). Au final, le nom de votre champ peut être ContentClass_mydatatype_myfield_123.

Normally, for every field name you want to access, you would need to write code similar to this:
Normalement, pour chaque nom de champ auquel vous souhaitez accéder, vous devez écrire un code similaire à celui-ci:

$dataName = $http->postVariable( $base . "_mydatatype_myfield_" . $contentObjectAttribute->attribute( "id" ) );

The abstract ymcDatatypeForm class makes this a lot more readable by building the real field name in the background. Let's look at the fetchClassAttributeHTTPInput method in ymcDatatypeDateTimeType for a better understanding. Remember that this method should read the input from the Default Value dropdown list from the Class Edit Interface and store it in the attribute:
La classe abstraite ymcDatatypeForm rend ceci beaucoup plus lisible en construisant le vrai nom du champ en arrière plan. Examinons, pour une meilleure compréhension, la méthode fetchClassAttributeHTTPInput de la classe ymcDatatypeDateTimeType. Souvenez-vous que cette méthode doit lire l'entrée à partir de la liste déroulante Default Value (Valeur par défaut) de l'interface d'édition de classe puis la stocker dans un attribut:

public function fetchClassAttributeHTTPInput( $http, $base, $attribute )
 {
 $form = ymcDatatypeForm::getInstance(
 'ymcDatatypeDateTimeClassForm',
 $attribute->attribute( 'id' )
 );

 This gives us a singleton instance of the class ymcDatatypeDateTimeClassForm for the specified ID. Next is the input validation code, which consists of one simple statement:
 Cela nous donne, pour un ID spécifié, une unique instance  de la classe ymcDatatypeDateTimeClassForm. Ce qui suit est le code de validation de l'entrée saisie composé d'un simple état:

if( !$form->isValid() )
 {
 return;
 }

 If the input is valid, we can continue to the last line of code:
 Si l'entrée est valide, nous pouvons poursuivre avec la dernière ligne du code:

$attribute->setAttribute(
 self::CLASSATTRIBUTE_DEFAULT,
 $form->default
 );
}

Note that I did not have to write “ContentClassAttribute_default_123” to access the field “default”. The mapping to the concrete field name has been done in the background by the ymcDatatypeForm class.
Notez que je n'ai pas eu à écrire ContentClassAttribute_default_123 pour accéder au champ default. Le mappage vers le nom concret du champ est réalisé en arrière plan par la classe ymcDatatypeForm.

For more detailed information, please refer to the source code of the ymcDatatypeForm class, to the documentation of the UserInput component and to the documentation of the PHP filter extension.
Pour des informations plus détaillées, référez-vous au code source  de la classe ymcDatatypeForm, à la documentation du composant UserInput  ainsi qu'à celle de l'extension PHP Filter .

Commentaires