Date de publication: le dimanche 25 mai 2008 à 23h27
Dernière modification: par Pascal BOYER le mercredi 6 octobre 2010 à 10h43
« Article précédent: eZ Publish content model / Modèle de contenu de eZ Publish
» Article suivant: A moment in time: the ymcDatatypeDateTime class / Un moment du temps: la classe ymcDatatypeDateTime
Our custom datatype extends the functionality of eZ Publish and therefore needs to be included in an extension. Refer to Felix Woldt's article An Introduction to Developing eZ Publish Extensions to learn more about different types of extensions. Here we will outline the necessary files and configuration for the extension.
Notre datatype personnalisé étend les fonctionnalités de eZ Publish et nécessite donc d'être inclus à une extension. Référez-vous à l'article de Felix Woldt
An Introduction to Developing eZ Publish Extensions
(Une introduction au développement d'une extension eZ Publish) pour en apprendre d'avantage sur les différents types d'extensions. Nous allons à présent mettre l'accent sur les fichiers et configurations nécessaires à l'extension.
At Young Media Concepts we have one extension called “ymcdatatype” that contains all of our general-purpose datatypes. Each datatype can also be created in a separate extension or combined with a related module in an extension.
Chez Young Media Concepts nous avons une extension nommée ymcdatatype contenant tous nos datatypes à usage général. Chaque datatype peut être créé dans une extension qui lui est propre ou combiné à un module d'une extension.
In any case, the extension containing your datatype needs to be activated in a site.ini.append file, either in settings/override, settings/siteaccess/your_siteaccess or in the settings directory of an already activated extension, like this:
Dans tous les cas, l'extension contenant votre datatype doit être activée dans un fichier site.ini.append situé soit dans le répertoire settings/override, soit dans le répertoire settings/siteaccess/votre_siteaccess soit dans le répertoire settings d'une extension déjà activée, comme ceci:
[ExtensionSettings] ActiveExtensions[]=ymcdatatype
(Note that the setting name is “ActiveAccessExtensions[]” if you are activating the datatype for a specific siteaccess.)
(Retenez que le nom du paramètre sera ActiveAccessExtensions[] si vous activez le datatype pour un siteaccess particulier).
Based on the settings above, eZ Publish knows that there is an extension called “ymcdatatype”, but it does not know about the new datatype yet. To point eZ Publish to the datatype contained in the extension, we place the settings below in a content.ini.append file, which is best placed in the settings directory of the datatype extension:
En se basant sur les paramètres définis ci-dessus, eZ Publish est informé de l'existence d'une extension nommée ymcdatatype mais ignore tout du nouveau datatype. Pour remédier à cette lacune, nous plaçons les paramètres ci-après dans un fichier content.ini.append, ce qui constitue le meilleur emplacement du répertoire settings de l'extension à laquelle est lié le datatype:
[DataTypeSettings] ExtensionDirectories[]=ymcdatatype AvailableDataTypes[]=ymcdatetime
The datatype also requires some templates (to be described next), so the extension also needs to be specified as a design extension in design.ini.append:
Le datatype requérant également quelques templates (décrits plus loin), l'extension doit donc aussi être spécifiée en tant qu'extension de design dans le fichier design.ini.append:
[ExtensionSettings] DesignExtensions[]=ymcdatatype
Template files / Les fichiers templates
Templates are required for class and object attributes of our datatype. In both cases, we need both view and edit templates, making a total of four required templates:
Des templates sont requis pour les attributs de classe et d'objet de notre datatype. Dans les deux cas, nous avons besoin de deux templates de vue et d'édition, ce qui fait un total de 4 templates:
- design/standard/templates/class/datatype/edit/ymcdatetime.tpl
- design/standard/templates/class/datatype/view/ymcdatetime.tpl
- design/standard/templates/content/datatype/edit/ymcdatetime.tpl
- design/standard/templates/content/datatype/view/ymcdatetime.tpl
We will explore the code in these templates a bit more later.
Nous regarderons plus tard le code de ces templates.
PHP files / Les fichiers PHP
Required files / Les fichiers requis
The main code of the datatype consists of two PHP classes in the following files:
Le code principal du datatype est composé de deux classes PHP situées dans les fichiers suivants:
- datatypes/ymcdatetime/ymcdatetime.php: ymcDatatypeDatetime
- datatypes/ymcdatetime/ymcdatetimetype.php: ymcDatatypeDatetimeType
The first file contains the actual content holder. Some simple datatypes like string or number types do not have an extra class to represent their content, but simply return an array or a primitive PHP type as representation of their content. If the content of your datatype has a complex structure or methods associated to the content, you should represent the content by a PHP class of its own.
Le premier fichier contient le titulaire du contenu. Certains datatypes simples, tels que ceux de type chaîne de caractères ou nombre, ne possèdent pas de classe supplémentaire pour représenter leur contenu et retourne simplement un tableau ou un type primitive PHP comme représentation de leur contenu. Si le contenu de votre datatype est d'une structure complexe ou possède des méthodes associées au contenu, alors vous devez représenter ce dernier par une classe PHP qui lui est propre.
In our case, the ymcDatatypeDatetime class contains shortcut methods to retrieve the elements of a DateTime object, such as the day, month, second or timezone, as well as methods for serializing and unserializing the information. The constructor of the class also checks the given input for validity. This way we could shorten the ymcDatatypeDatetimeType class and let the content container decide whether or not to handle the user input.
Dans notre cas, la classe ymcDatatypeDatetime contient des méthodes raccourcis (???) permettant de retrouver les éléments de l'objet DateTime, tels que le jour, le mois, les secondes ou le fuseau horaire, ainsi que des méthodes pour
sérialiser
et
désérialiser
les informations. Le
constructeur
de la classe contrôle également la validité des données saisies. Par ce biais nous pouvons réduire la classe ymcDatatypeDatetimeType et laisser le conteneur de contenu décider de traiter ou non l'entrée saisie par l'utilisateur.
The name and location of the file ymcdatetime.php is not strictly forced, but it is general convention in eZ Publish and many extensions to name it this way. You thus have the main code blocks of your datatype in one place and everybody knows where to search for it.
Le nom et l'emplacement du fichier ymcdatetime.php n'est pas précisément défini mais les conventions de eZ Publish et celles de nombreuses extensions incitent à le nommer ainsi. Les principaux blocs de code de votre datatype sont donc réunis en un seul endroit et tout le monde sait où le chercher.
The second file handles the connection between eZ Publish and our new datatype. The name and path of the second file is important because eZ Publish tries to load a file with this exact name when you register a datatype with the identifier “ymcdatetime”.
Le second fichier gère les connexions entre eZ Publish et notre nouveau datatype. Le nom et le chemin de ce second fichier est important puisque eZ Publish charge un fichier en se basant sur son nom exact lorsque vous enregistrez un datatype dont l'identifiant est y mcdatetime.
We also need to handle the HTTP input forms. This is done with two classes, defined in datatypes/ymcdatetime/classform.php and datatypes/ymcdatetime/objectform.php, which both extend ymcDatatypeForm from interfaces/form.php. Since this datatype has been developed for eZ Publish 4, we can make use of the UserInput component from eZ Components to handle form input. This is explained in detail later.
Nous devons également gérer les formulaire d'entrées HTTP. Pour cela nous disposons de deux classes, définies dans les fichiers datatypes/ymcdatetime/classform.php et datatypes/ymcdatetime/objectform.php, qui toutes deux étendent ymcDatatypeForm du fichier interfaces/form.php. Depuis que ce datatype a été développé pour eZ Publish 4 nous pouvons utiliser le composant UserInput fourni par
eZ Components
pour gérer le formulaire de saisie. Ceci sera expliciter en détail plus loin.
Useful additions / Ajouts utiles
PHP 5 and therefore eZ Publish 4 have two notable features to write more stable and robust code. The first one is the autoloading functionality, which frees you from all those “requires” and “includes”.
PHP5, et donc eZ Publish 4, possède deux fonctionnalités notables pour écrire du code stable et robuste. La première d'entre elles est l'auto-chargement, qui vous libère de tous les requires et includes.
The second feature is the introduction of exceptions. In PHP 4, the only way to report errors from a function is for it to return FALSE or some other value, by convention indicating an error. However, this is a sub-optimal solution – how do we know which problem actually occurred and what if FALSE should also be a valid return value?
La seconde est l'introduction des exceptions. Avec PHP4, la seule manière qu'une fonction a de signaler des erreurs est de retourner la valeur FALSE ou toute autre valeur qui par convention indique une erreur. Cependant, cela ne constitue pas une solution optimale - comment connaissons-nous la nature du problème qui survient et que se passe t-il si la valeur FALSE doit être également une valeur retournée valide ?
In every extension, we have an exceptions directory containing an exception class for, hopefully, each type of error that can occur. One such error in our datatype is invalid user input, which is indicated by a ymcDatatypeInvalidParamsException exception, defined in invalid_params.php.
Nous avons, dans toutes les extensions, un répertoire exception contenant une classe exception pour, espérons-le, chaque type d'erreur pouvant survenir. Une telle erreur dans notre datatype serait une saisie utilisateur invalide, indiquée/notifiée par une exception ymcDatatypeInvalidParamsException, définie dans le fichier invalid_params.php.
Input validation in PHP 5 should be done using the filter extension. This extension comes with many configurable filters to either block invalid data or sanitize it with certain rules. If you need to add extra filters, you can provide a callback function to the filter extension.
Avec PHP5, la validation des saisies doit être réalisée avec
l'extension Filter
fournissant de nombreux filtres configurables permettant de bloquer les données invalides ou de les assainir grâce à l'emploi de certaines règles. Si vous devez ajouter de nouveaux filtres, vous pouvez fournir une fonction de rappel à l'extension Filter.
In our case, we need special filters for integer numbers with leading zeros. If somebody enters the month as “09” instead of “9”, it should still be valid for September, even if a leading zero in PHP usually indicates an octal number and “09” is not a valid octal number.
Dans notre cas, nous avons besoin de filtres spéciaux pour les nombres entiers commençant par des zéros. En effet, si quelqu'un saisit le mois au format 09 au lieu de 9, cela doit être considéré comme une saisie valide pour le mois de Septembre quand bien même un zéro en tête indique normalement, en PHP, un nombre octal tout en sachant que 09 n'est pas un nombre octal valide.
We put our filter callbacks in classes inside the filter_callbacks directory. For this datatype, we only need the ymcDatatypeFilterIntLeadingZero class, which is defined in filter_callbacks/int_leading_zero.php.
Nous mettons nos filtres de rappel dans des classes situées dans le répertoire filter_callbacks. Dans le cas de notre datatype nous n'avons besoin que de la classe ymcDatatypeFilterIntLeadingZero définie dans le fichier filter_callbacks/int_leading_zero.php.