Date de publication: le lundi 26 mai 2008 à 11h51
Dernière modification: par Pascal BOYER le mercredi 6 octobre 2010 à 10h34
« Article précédent: A moment in time: the ymcDatatypeDateTime class / Un moment du temps: la classe ymcDatatypeDateTime
» Article suivant: Using the UserInput component for datatypes -- Utiliser le composant Userinput pour les datatypes

21 May 2008 6:14  

As previously mentioned, the connection between eZ Publish and our new datatype is made with the ymcDatatypeDateTimeType class, which extends eZDataType. Configuration of the datatype is then made by overriding certain methods of the parent class.
Comme mentionné précédemment, la connexion entre eZ Publish et notre nouveau datatype est réalisée par la classe ymcDatatypeDateTimeType qui étend eZDataType. La configuration du datatype est alors réalisée en surchargeant certaines méthodes des classes parents.

While eZDataType contains dozens of methods, the methods can be grouped into three main categories for the purpose of our custom datatype: methods dealing with user input for the content class attribute; those dealing with user input for the content object attribute; and other methods. These are outlined below. For more detailed information, be sure to study the code and accompanying comments in our example extension.
Alors que eZDataType contient des dizaines de méthodes, celles-ci peuvent être groupées, pour les besoins de notre datatype personnalisé, en trois catégories principales: les méthodes traitant les saisies des utilisateurs pour l'attribut de classe de contenu, celles traitant les saisies des utilisateurs pour l'attribut de l'objet de contenu et les autres méthodes. Tout ceci est décrit ci-après. Pour de plus amples informations, prenez le temps d'étudier le code et les commentaires qui l'accompagnent  de notre exemple d'extension.

Content class attribute methods / Méthodes des attributs de classe de contenu

Recall the previous screenshot showing the Object Edit Interface for two attributes using the “ymcdatetime” datatype. The screenshot below shows the Class Edit Interface for the content class with the same two attributes.
Souvenez-vous de la précédente capture d'écran illustrant l'interface d'édition des objets dans le cas d'un objet contenant deux attributs basés sur le datatype ymcdatetime. La capture d'écran ci-dessous illustre quant à elle l'interface d'édition des classes dans le cas d'une classe de contenu contenant les deux mêmes attributs:

Class Edit Interface using attributes of our datatype
Interface d'édition des classes dans le cas de la classe contenant des attributs basés sur notre datatype

Most of the form fields are common to all datatypes and are the same for every class attribute. Only the Default value field is controlled by our custom datatype, which allows content managers to select whether a new instance of the datatype should be pre-filled with the current date or left empty.
La plupart des champs de formulaires sont communs à tous les datatypes et sont les mêmes pour tous les attributs de classe (!!!). Seul le champ Valeur par défaut est contrôlé par notre datatype personnalisé qui autorise les gestionnaires de contenus à spécifier si une nouvelle instance du datatype doit être pré-remplie par la date courante ou au contraire laissée vide.

When “Current date” is selected, the input fields of this attribute will be pre-filled with the current date for new objects. When “Empty” is selected, the input fields of this attribute will be blank.
Lorsque la valeur Date courante est sélectionnée, les champs de saisie de cet attribut des nouveaux objets seront pré-remplis avec la date courante. A l'inverse, lorsque la valeur Vide est sélectionnée, les champs de saisie de cet attribut seront vides.

The three methods listed below from the ymcDatatypeDateTimeType class are important for the Class Edit Interface we just described. They are described in the order in which they are called from the eZ Publish core:
Les trois méthodes de la classe ymcDatatypeDateTimeType listées ci-dessous sont importantes pour l'interface d'édition de classe que nous venons de décrire. Elles sont décrites en respectant l'ordre dans lequel elles sont appelées par le cœur de eZ Publish:

• initializeClassAttribute 
  This method can be used to set default values for the configuration of a new class attribute of this datatype. For our datatype we set the value of the dropdown list for the default value to “Empty”.
  Cette méthode peut-être utilisée pour définir des valeurs par défaut pour la configuration d'un nouvel attribut de classe basé sur ce datatype. Dans le cas de notre datatype nous avons défini la valeur Vide comme valeur par défaut de la liste déroulante.
• ValidateClassAttributeHTTPInput 
  Here, we check whether the submitted input is valid. The return value should be either eZInputValidator::STATE_INVALID or eZInputValidator::STATE_ACCEPTED.
  Ici, nous contrôlons que la saisie envoyée soit valide. La valeur de retour doit être soit eZInputValidator::STATE_INVALID soit eZInputValidator::STATE_ACCEPTED.
• FetchClassAttributeHTTPInput 
  Here, we take the submitted input and save it in the provided eZContentClassAttribute parameter so that eZ Publish can store it in the database. Note that this method is also called when we return STATE_INVALID. This might appear unnecessary at first, but makes sense when we have multiple input fields to take care of. If only one input field has invalid data, we still want to keep the input of the valid fields so that content managers do not have to re-enter it.
  Ici, nous récupérons la saisie envoyée et la sauvegardons dans le paramètre eZContentClassAttribute fourni afin que eZ Publish puisse la stocker dans la base de données. Retenez que cette méthode est également appelée lorsque nous retournons STATE_INVALID. Bien que cela puisse sembler à priori inutile, cela prend tout son sens lorsque nous devons traiter plusieurs champs de saisie. En effet, quand un seul champ comporte des données invalides, nous souhaitons tout de même conserver les données des champs valides afin que le gestionnaire de contenus n'ai pas à les re-saisir.

Content object attribute methods / Méthodes des attributs d'objet de contenu

There are three methods for object editing that mirror the functionality described above for class editing. These are initializeObjectAttribute, validateObjectAttributeHTTPInput and fetchObjectAttributeHTTPInput.
Trois méthodes d'édition d'objet ressemblent aux fonctionnalités d'édition de classe décrites ci-dessus: initializeObjectAttribute, validateObjectAttributeHTTPInput et fetchObjectAttributeHTTPInput.

The only difference lies in the initializeObjectAttribute method. It is called not only when a content object is created for the first time, but also whenever a new version is created. Since every edit operation on a content object creates a new draft version, this method is called on every edit.
La seule différence concerne la méthode initializeObjectAttribute qui n'est pas seulement appelée lorsqu'un objet de contenu est créé pour la première fois, mais également lorsqu'une nouvelle version est créée. Depuis que toutes les opérations d'édition d'un objet de contenu créent une nouvelles version de brouillon, cette méthode est appelée lors de chaque édition.

If we create a new version of an object and with it also a new version of our attribute, we need to copy the content of the old version to the new one. This may seem bothersome, but is a necessary step to allow datatypes the option to do more than simply copy their content for new versions. Some content might need to be changed in some way between versions, for example to increase a counter or set a date.
Si nous créons une nouvelle version d'un objet ainsi qu'une nouvelle version de notre attribut, alors nous devons copier le contenu de l'ancienne version dans la nouvelle. Cela peut sembler rébarbatif, mais constitue une étape nécessaire pour permettre aux options des datatypes (???) de faire plus qu'une simple copie de leur contenu vers de nouvelles versions. Entre deux versions, certains contenus doivent être modifiés, pour augmenter, par exemple, un compteur ou définir une date.

The hasObjectAttributeContent method checks whether data exists. If the attribute has the “required” flag set, then eZ Publish will not save the content if there is no content to store in the datatype.
La méthode hasObjectAttributeContent contrôle l'existence de données. Si le drapeau Requis de l'attribut est coché, alors eZ Publish ne sauvegardera pas le contenu s'il n'y a pas de contenu à sauvegarder dans la base de données.

The objectAttributeContent method returns the content of the object. This can be a primitive PHP type like an integer or string, or an object for more complex content structures. In our case, we return an instance of ymcDatatypeDatetime.
La méthode objectAttributeContent renvoie le contenu de l'objet. Cela peut être un type primitive PHP tel qu'un nombre entier, une chaîne de caractères, ou bien un objet pour des structures de contenus plus complexes. Dans notre cas, nous retournons une instance de la classe ymcDatatypeDatetime.

Other methods / Autres méthodes

 Of the remaining methods, the most important one is the constructor. It announces an identification string and a human-readable string to the parent class eZDataType. The identification string is used by eZ Publish to identify datatypes throughout the system and should therefore be chosen with care. It is a good idea to have a unique prefix for all your datatypes. (Please do not use “ymc” as this is used by us!) The second string is used in the interfaces and it is common to use the internationalization features of eZ Publish to present the user with a localized name of the datatype:
 Quant aux méthodes restantes, la plus importante est la méthode constructeur. Elle annonce à la classe parente eZDataType la présence d'une chaîne d'indentification et d'une chaîne de caratères humainement lisible. La chaîne d'indentification étant utilisée par eZ Publish pour identifier les datatypes du système elle doit être choisie avec attention. C'est une bonne idée de choisir un préfixe unique pour tous vos datatypes. S'il vous plait, n'utilisez pas ymc puisque nous l'utilisons déjà ! La seconde chaîne de caractères est utilisée par les interfaces et il est courant d'employer la fonctionnalité d'internationnalisation de eZ Publish pour présenter un nom traduit du datatype à l'utilisateur:

const DATATYPE_STRING = 'ymcdatetime';
 public function __construct()
 {
 parent::__construct( self::DATATYPE_STRING, 'ymcDateTime' );
}

The last five methods return information necessary to sort and search the datatype and a string representation of the datatype that can be used as part of the content object's title. Please refer to the source code of our example datatype for more information.
Les cinq dernières méthodes renvoient l'information nécessaire au tri et à la recherche du datatype ainsi qu'une chaîne de caractères représentant le datatype pouvant être utilisée comme partie du titre de l'objet de contenu. Référez-vous au code source de notre xemple  de datatype pour de plus amples informations.

If you have looked at the source code, you may have seen a rather uncommon code line at the end of the file:
Si vous avez jeté un oeil au code source, peut-être avez-vous remarqué une ligne de code peu commune à la fin du fichier:

eZDataType::register( ymcDatatypeDateTimeType::DATATYPE_STRING, "ymcDatatypeDateTimeType" );

This coding style is from the pre-PHP 5 times, where classes could not be loaded automatically. Therefore, the line must be included at the end of every datatype.
Ce code date du temps de la pré-version de PHP 5, époque où les classes ne pouvant être automatiquement chargées, cette ligne devait donc être incluse à la fin de tous les datatypes.

The first argument is the same datatype identifier as in the constructor and the second argument is the name of the PHP class implementing the datatype. Remember that class names in PHP 5 are case sensitive!
Le premier argument correspond au même identifiant de datatype que dans le constructeur et le second argument est le nom de la classe PHP implémentant le datatype. Souvenez-vous qu'avec PHP5 les noms des classes sont sensibles à la casse.

Commentaires