Tutoriel de David Shaffer/Les bases du rendu
From OFSET Wiki
Traduction de : Rendering Basics
Contents |
[edit] Le rendu de texte simple : Hello world
Notre premier composant Seaside va simplement écrire "Hello world". Commencons par sous-classer WAComponent :
WAComponent subclass: #HelloWorldComponent
instanceVariableNames: '
classVariableNames:
poolDictionaries:
category: 'SCSeasideTutorial'
Nous allons parler de WAComponent tout le long de ce tutoriel. Pour l'instant, pensons les sous-classes de WAComponent comme des "composants visuels". Lorsque c'est le moment d'afficher un composant, Seaside lui envoie le message renderContentOn: avec un WAHtmlRenderer ("le rendu") comme paramètre. Pensez au rendu comme un canevas sur lequel vous allez pouvoir dessiner votre composant. Il procure une interface quasiment transparente à XHTML tout en facilitant la production de textes, ancres, formes, etc le tout de manière modulaire. Nous voulons seulement produire du texte donc nous utilisons la méthode de rendu text: :
renderContentOn: html html text: 'Hello world'
Super, nous avons un composant mais comment dire à Seaside de l'utiliser ? Pour l'instant, utilisons une méthode de classe en évaluant le code suivant dans un workspace :
HelloWorldComponent registerAsApplication: 'hello'
Ceci indique à Seaside d'enregistrer notre composant avec l'URI de chemin /seaside/hello. Aller voir avec votre navigateur web l'adresse : http://localhost:9090/seaside/hello. Votre navigateur doit maintenant afficher cette salution :
En simplifiant beaucoup : lorsque l'on demande cette URL, Seaside créée une instance de notre classe pour nous et ensuite lui envoie renderContentOn:. L'HTML généré est ensuite retourne au navigateur afin d'être affiché. Vous n'aurez probablement jamais besoin d'envoyer à votre composant le message renderContentOn: puisque le cadre d'application Seaside prend cela en charge pour vous. Lorsque c'est le moment d'afficher votre composant, Seaside lui envoie le message renderContentOn:. Ceci est vraiment similaire aux modèles utilisés dans la plupart des interfaces graphiques lorsqu'on demande à un composant (ou une fenêtre) de s'afficher lui-même lorsque le système de fenêtrage le juge nécessaire. Retenez ceci lorsque vous travaillez avec Seaside, votre méthode de rendu est juste la pour afficher l'état courant de votre composant. Elle ne doit pas s'occuper de la façon de changer son état.
Modifiez la méthode renderContentOn: pour inclure du code html comme : "<h1>hello world</h1>".
renderContentOn: html html text: '<h1>hello world</h1>'
Rafraichissez la page du navigateur et notez que l'effet escompté n'est pas réalisé. Ceci est en fait une bonne chose. La méthode text: s'occupe de convertir tous les caractères qui sont considérés comme spéciaux en HTML de telle façon que vos chaînes de caractères soient correctement affichées. Si vous voulez réellement générer du code HTML directement, vous devez utiliser la méthode html: plutôt que text:. Je vous recommande de ne pas faire comme cela. L'API de génération d'HTML fourni par Seaside est plus simple à utiliser et à modifier que de coder manuellement en HTML.
Alors comment pouvons nous avoir un entête ? Nous pouvons générer les différentes balises d'entêtes (H1, H2, etc) en utilisant heading:level:. Ajoutons aussi un paragraphe :
renderContentOn: html
html heading: 'Hello world' level: 1.
html paragraph: 'Welcome to my Seaside web site. In the future you
will find all sorts of applications here such as: calendars, todo lists,
shopping carts etc'
[edit] Le rendu de listes et de tables
Modifions notre composant pour affichier une liste du contenu du site. Voila le code correspondant :
renderContentOn: html
html heading: 'Hello world' level: 1.
html paragraph: 'Welcome to my Seaside web site. In the future you
will find all sorts of applications here such as:'.
html orderedList:
[html listItem: 'Calendars'.
html listItem: 'Todo lists'.
html listItem: 'Shopping carts'.
html listItem: 'And lots more...'].
Notez que orderedList: prend un bloc en paramètre (en fait, un Renderable). Cela place la balise HTML <OL> et </OL> autour du code HTML généré par le bloc. Chaque listItem: prend une chaîne de caractères (String) (encore un Renderable) et place cette chaîne à l'intérieur de balise <LI> et </LI>. On peut également utiliser un unorderedList:.
Pourquoi ne pas avoir une table de dates attendues de remise :
renderContentOn: html
html heading: 'Hello world' level: 1.
html paragraph: 'Welcome to my Seaside web site. In the future you
will find all sorts of applications here such as:'.
html table:
[html tableRow:
[html tableData: 'Calendars'.
html tableData: '1/1/2006'.
html tableData: 'Track events, holidays etc'].
html tableRow:
[html tableData: 'Todo lists'.
html tableData: '5/1/2006'.
html tableData: 'Keep track of all the things you have to remember to do.'].
html tableRow:
[html tableData: 'Shopping carts'.
html tableData: '8/1/2006'.
html tableData: 'Enable your customers to shop online.']]
Ceci est très similaire à l'exemple sur les listes en terme de la façon dont le texte est balisé.
[edit] Exercises
- Trouvez comme afficher des balises d'entêtes de tables. Modifier le dernier exemple pour inclure un entête pour chaque ligne.
- Jetter un coup d'oeil aux méthodes orderedList:do: et unorderedList:do: de WAAbstractHtmlBuilder'. Pour des exemples, parcourez les méthodes qui utilisent ces sélecteurs. Modifier notre exemple afin d'utiliser une de ces méthodes.
[edit] Objets qui peuvent être rendus
Plusieurs des méthodes de rendus qui génèrent des balises acceptent n'importe quel objet qui peut être affiché, c'est-à-dire un objet qui implément la méthode renderOn:. En réponse aux messages comme orderedList:, on génère une balise de début, on génère l'argument, puis on génère la balise de fin. Dans le cas où vous voulez seulement générer uniquement un texte entre les balises, vous pouvez utiliser une chaîne de caractère comme composant qui peut être rendu. Généralement, vous voulez afficher d'autres objets à l'intérieur des balises (comme les élements d'une liste dans notre exemple orderedList: ci-dessus). Dans ces cas, vous pouvez utiliser un bloc à 0 ou 1 argument comme objet qui peut être rendu. Les deux méthodes qui suivent produisent le même résultat :
renderContentOn: html
html paragraph: 'Hello'.
renderContentOn: html
html paragraph: [html text: 'Hello'].
La première forme est plus courte, mais vous ne pouvez pas générer plus d'HTML à l'intérieur du paragraphe. La deuxième former offre la possibilité de générer de l'HTML supplémentaire à l'intérieur des balises de début et de fin de paragraphe :
renderContentOn: html
html paragraph: [html text: 'Hello'. html space. html bold: 'users'].
Naviguer dans les classes qui implémentent renderOn: pour voir quels sont les objets qui peuvent être affichés.
[edit] Les attributs de balise
Notre exemple avec une table n'est pas très beau dans la plupart des navigateurs web car la table par défaut n'a pas de bordure. Nous savons que la balise HTML TABLE accepte un paramètre appellé border dont la valeur représente la taille de la bordure en pixel. On peut spécifier des attributs de balises en envoyant le message atrributeAt:put: à l'objet qui est rendu. Ce message enregistre tous les attributs et les utilise pour l'affichage de la balise qui suit. Dès qu'il ont été utilisé pour rendre une balise, tous les attributs sont supprimés. Modifions la méthode précédente pour obtenir :
renderContentOn: html
html heading: 'Hello world' level: 1.
html paragraph: 'Welcome to my Seaside web site. In the future you
will find all sorts of applications here such as:'.
html table border: 1; with:
[html tableRow:
[html tableData: 'Calendars'.
html tableData: '1/1/2006'.
html tableData: 'Track events, holidays etc'].
html tableRow:
[html tableData: 'Todo lists'.
html tableData: '5/1/2006'.
html tableData: 'Keep track of all the things you have to remember to do.'].
html tableRow:
[html tableData: 'Shopping carts'.
html tableData: '8/1/2006'.
html tableData: 'Enable your customers to shop online.']]
Veuillez noter que l'attribut de bordure est seulement appliqué sur les balises de tables générées. Mettre trop d'attributs est ennuyeux et obscurcit le code. Il y a plusieurs façons de faire qui permettre de rendre la méthode renderContentOn: plus lisible. Vous les verrez lorsque nous allons progresser vers des exemples plus réalistes, mais normalement cela se ramène à utiliser le plus possible des feuilles de styles CSS.
[edit] Le halo
Si vous avez essayé de voir le code HTML des documents ci-dessus, vous avez vu que cela n'est pas facile à lire car ce n'est pas formatté pour un lecteur humain (pas de passage à ligne, pas d'indentations, etc). Ne nous inquiétons pas, Seaside dispose d'un outil nommé le halo qui peut être utilisé pour afficher le code source HTML bien formatté et qui permet de faire bien plus encore. En bas de la fenêtre de votre navigateur vous devez voir une barre d'outil :
Cliquer sur le lien "Toggle Halos" et observer que le halo apparaît atour de la représentation visuelle de votre composant :
Les liens "R" et "S" signifie respectivement "Render" et "Source". Pour l'instant, vous êtes en train de regarder le résultat rendu par le composant. Pour voir le code HTML de ce composant cliquer sur le lien "S". Les icones sur le côté gauche du halo sont également utile. La première (celle qui ressemble à une clé à molette) ouvre un nivagateur de classe sur votre composant dans le navigateur web. Essayez la. La deuxième (l'oeil) ouvre un inspecteur sur votre composant. De nouveau, essayez la. La troisième (le stylo) ouvre un éditeur de style sur votre composant. Nous allons l'utiliser dans quelques instants.
[edit] Feuilles de styles
Il y a deux façons standards de générer des feuilles de style CSS dans Seaside : au moyen de la méthode style de chaque composant ou en utilisant les librairies de styles. Nous allons d'abord voir la première façon de procéder. Commencons par ajouter une méthode style pour centrer l'entête :
style
^'h1 {text-align: center;}'
Maintenant rafraichissez votre navigateur et vous devez voir "Hello world" centré. (Si votre navigateur ne respecte pas le standard CSS2, vous pouvez ne pas voir le texte centré.) Faite apparaître le halo sur ce composant et cliquez sur le stylo. Veuillez observer que vous pouvez éditer la méthode de style de votre composant ici. Si vous sauvegardez vos modifications, la méthode style du composant sera mise à jour. Ceci peut être utile si vous avez un graphiste qui contrôle la présentation de votre site mais ne connait rien à Smalltalk ou à Squeak. J'utilise personnellement un fichier CSS statique pour le contenu statique et dynamique de mes sites.
Si vous utilisez CSS régulièrement, vous devez être familier avec l'utilisation des balises div (block elements) et span (inline elements) ainsi qu'avec leur attribut class qui permet d'ajouter du style à des parties de document. Voici comment, par exemple, on peut donner une couleur rouge à un message d'erreur :
renderContentOn: html .... existing code (from above) .... html span class: 'error'; with: 'This site does not work yet'
style
^'
h1 {text-align: center;}
span.error {background-color: red;}
'
Il y a aussi les méthodes div class: ; With: pour produire des balise HTML div.
Ce tutoriel n'est pas à propos de XHTML ou de CSS donc je vous laisserais vous débrouiller en ce qui concerne la mise en page d'un composant. J'ai mis quelques références en bas de cette page. Voici quelques astuces :
- utiliser des SPAN et DIV avec des classes CSS ou des ID pour marquer le contenu généré par vos composants. Très souvent les composants sont rendus à l'intérieur d'un DIV dont la classe CSS est le nome de la classe SmallTalk du composant. Cela facilite pour les dévelopeurs de CSS la localisation des éléments HTML qu'ils veulent styliser. Trouvez des conventions qui vous satisfont et tenez-vous y !
- N'essayez pas de "sur-styliser" votre composant dans sa méthode renderContentOn:. Cela rendrait plus difficile la personnalisation de l'affichage de votre composant.
- Utilisez des méthodes de style de composant comme celle ci-dessus seulement quand les éléments de style sont très spécifiques à ce composant. Sinon utilisez de bibliothèques de style (discussion plus loin).
- Essayez d'utiliser des feuilles de style pour structurer la présentation générale de votre document, plutôt que des tables HTML. On trouve de nombreuses bonnes références CSS montrant comment obtenir de bons rendus de pages.
[edit] Autres méthodes de rendu
Il y a plusieurs autres méthodes de rendu, qui produisent plutôt des résultats évidents :
- break -- génère des balises br
- horizontalRule -- génère des balises hr
- div:
- span:
- bold:
- italics:
- emphasis:
- image: -- prend une chaîne de caractère URI comme argument
Parcourez le code pour en savoir plus. Lorsque l'objet qui doit être rendu ne comprend pas un message à 0 ou 1 argument, il génère des balises basés sur le sélecteur du message. Par exemple, il n'y a pas d'implémentation de la balise br mais envoyer à l'objet à rendre le message br va provoquer une génération de la balise associée. Dans le cas de la méthode à un argument, l'argument doit être un objet qui peut être rendu et il sera affiché entre une balise ouvrante et fermante.
