Principes de marquage

Consultez les directives relatives à l'utilisation des marquages HTML, WML et cHTML dans vos JSP de portlets afin de produire une interface utilisateur homogène, claire et complète.

La page du serveur d'un portail est affichée avec des habillages et des thèmes définis par le concepteur ou l'administrateur du portail. Pour que des portlets s'intègrent au portail d'une entreprise ou au portail personnalisé d'un utilisateur, il faut générer un marquage qui démarre les classes de style génériques des portlets. Il ne faut pas utiliser des balises ou des attributs pour définir des couleurs, des polices ou d'autres éléments visuels.

Les portlets servent à afficher uniquement des fragments de marquage qui sont ensuite assemblés par la structure du portlet pour produire une page. La sortie de portlet doit contenir des fragments de marquage complets, bien structurés et corrects. Ainsi, vous éviterez par exemple que le code HTML du portlet altère le code HTML agrégé du portail. Utilisez un outil de validation, tel que W3C HTML Validation Service, ou un outil fourni avec un éditeur de marquage.

Ces principes sont basés sur les instructions de codage JSP pour les portlets standard.

HTML

Utilisez le langage HTML standard. Pour la spécification HTML officielle, voir W3C.
N'utilisez que des fragments de code HTML. Comme les portlets contribuent au contenu d'une page plus grande, il ne doivent fournir que des fragments de code HTML et ne doivent pas contenir de balise <html>, <head> ou <body>.
Utilisez uniquement des éléments qui apparaîtront correctement dans une cellule de tableau HTML (<td>...</td>). Par exemple, les cadres n'apparaissent pas lorsqu'ils sont insérés dans un tableau.
Contrôlez que les fragments sont syntaxiquement corrects pour éviter des pages déséquilibrées. Soyez attentif aux balises non fermées, non reconnues ou mal imbriquées. Les pages contenant des balises incorrectes produisent des résultats imprévisibles.
Evitez les pages HTML longues et complexes. Les portlets partagent une page avec d'autres portlets. Par conséquent, plus le contenu généré par chacun d'eux est volumineux, plus le navigateur doit traiter de données avant d'afficher les informations.
Utilisez des classes de portlet dans la feuille de style du serveur de portail, Styles.css. Si vous codez directement les polices et les couleurs, le portlet semble mal placé lorsque l'utilisateur modifie les paramètres par défaut de style de la page. Les administrateurs et utilisateurs de portails peuvent modifier l'apparence du portail en modifiant son thème et ses habillages. Les portlets peuvent procéder à des changements de style en utilisant les styles définis dans la feuille de style en cascade des thèmes de portails, Styles.css. Par exemple, au lieu de décorer un élément <input> avec l'attribut style, faites référence à la définition de classe d'entrée du thème : <inputclass="portlet-form-button" type="submit">
Les classes de style des portlets sont accompagnées du commentaire suivant :
```
/* Styles used in portlets
```
Lorsqu'elles sont disponibles, utilisez les classes de style WSRP, précédées du préfixe portlet-. Voir CSS Style Definitions dans la Spécification WSRP 1.0.
Le document approprié indique "One of the goals of an aggregated page is a common look-and-feel across the Portlets contained on that page. This not only affects the decorations around the Portlets, but also their 25 content. Using a common CSS stylesheet for all Portlets, and defining a set of standard styles, provides this common look-and-feel without requiring the Portlets to generate Consumer-specific markup. Portlets SHOULD use the CSS style definitions from this specification in order to participate in a uniform display of their content by various Consumers. For markup types that support CSS stylesheets, Consumers MUST supply a CSS stylesheet to the End-User's agent 30 with definitions for the classes defined in section 10.6 of this specification. This section defines styles for various logical units in the markup."
N'utilisez pas de CSS pour un positionnement absolu. Cela peut provoquer le rejet des fonctions de portail permettant aux utilisateurs et aux administrateurs de placer le contenu sur la page.
Limitez la taille d'affichage du portlet. Les portlets contribuent en partie à agrandir les pages. La taille des pages JSP (en termes d'étendue horizontale et verticale) peut déterminer si le portlet peut facilement s'adapter à une page comprenant plusieurs colonnes et d'autres portlets. Un grand portlet force les autres portlets à quitter l'écran et crée de grandes régions de défilement, entraînant des problèmes de convivialité. Lorsque vous concevez les pages JSP d'un portlet, évitez les éléments de présentation inutiles. Concentrez-vous sur l'affichage des informations pertinentes et demandez-vous si le portlet doit être placé sur des pages avec d'autres portlets. En particulier, contrôlez la taille de l'image, le texte préformaté (balise <pre/>) et les largeurs absolues sur les éléments, tels que les tableaux.
Utilisez des commentaires de style Java au lieu du style HTML. Les commentaires HTML restent dans le contenu affiché, augmentant ainsi la taille des documents et la quantité de données transférée au client. Si vous utilisez des commentaires de style Java sans vos pages JSP, ils sont retirés de la source affichée avec le reste du code Java. Vous devez intégrer ces commentaires à des scriptlets :
```
<% // this is a comment %>
```
Rendez les pages entièrement accessibles. Pour permettre aux utilisateurs de portails handicapés d'utiliser votre portlet, les pages JSP doivent être entièrement adaptées au contrôle par le clavier uniquement et aux autres technologies d'assistance. Suivez les principes généraux suivants :
- Utilisez l'attribut alt avec des images pour définir le texte descriptif du contenu d'image.
- Utilisez des balises <label> pour associer des étiquettes à des commandes d'entrée de formulaires, afin de permettre aux lecteurs des pages d'associer des invites à des entrées.
- N'utilisez pas la couleur sans autre élément pour dénoter l'état ou des informations. Par exemple, l'utilisation du rouge pour mettre en valeur le texte n'aide pas les daltoniens. Utilisez plutôt des caractères gras ou italiques, ou utilisez la couleur avec des modifications graphiques.
- N'utilisez pas la voix ou d'autres sons pour apporter des informations.
Les URI, attributs de noms d'éléments HTML et ressources JavaScript doivent recevoir un codage d'espace-nom. Utilisez <portlet:namespace/> (API de portlet standard) pour des éléments nommés afin d'éviter des conflits de noms avec d'autres portlets sur la page de portail.
Testez l'affichage du portlet avec différents navigateurs. Testez votre portlet lorsque vous redimensionnez la page, afin de vous assurer qu'il fonctionne avec des tailles de navigateur différentes. Testez votre portlet lorsque la police par défaut du navigateur est modifiée. Le portlet ne devrait pas poser de problème même en cas de changement de police.
Ne dessinez pas de bannières dans votre portlet, telles que les barres de titre, car elles sont fournies par l'agrégation du portail.
Minimisez les dépendances par rapport à JavaScript. Comme les implémentations et le comportement de JavaScript diffèrent sensiblement entre les types et versions de navigateurs, plus votre portlet dépend de JavaScript, plus il dépend des navigateurs. De plus, plus une grande partie de la page est affichée à l'aide de JavaScript, plus il est difficile de maintenir et d'étendre les marquages autres que HTML. Il est également plus difficile de coder des ressources JavaScript avec un espace de nom et presque impossible de coder correctement (response.encodeUrl()) des URL créées à l'aide de JavaScript.
N'utilisez pas de fenêtres en incrustation. Les interactions au sein du portail sont basées sur l'état, ce qui signifie que le portail suit votre piste parmi les pages et portlets. L'utilisation du bouton Précédent du navigateur ou la création de fenêtres en incrustation dans des instances de navigateur contenant des portlets peut empêcher le portail de suivre votre piste et de connaître votre état en cours, et entraîner des problèmes. Si vous n'utilisez pas d'invite JavaScript, il n'y a aucun moyen sûr de créer des fenêtres en incrustation sur le portail, à moins que le nouveau lien ne vous mène vers une page externe au portail. L'alternative consiste à placer un lien vers une page externe dans une nouvelle fenêtre de navigateur (à l'aide de l'attribut TARGET sur l'ancrage). L'utilisateur demeure sur le portail dans la fenêtre de navigateur d'origine.
Utilisez les IFRAME avec précaution. Les IFRAME permettent d'inclure facilement un contenu externe à un portlet, mais fragilisent l'ensemble du portlet car l'API de portlet est tunnélisée ou étayée. Les IFRAME ne sont donc à utiliser que dans des cas spéciaux, comme l'utilisation d'applications existantes. Les problèmes potentiels liés à l'utilisation d'un IFRAME sont les suivants :
- L'IFRAME remplit son contenu en fonction d'une URL. L'URL doit pouvoir être atteinte par le navigateur. Le serveur qui est la cible de l'URL doit donc être accessible par le navigateur.
- Tous les niveaux de navigateurs ne prennent pas en charge les IFRAME.
- Si le contenu est plus important que la zone d'IFRAME, activez le défilement vertical et horizontal pour permettre à l'utilisateur de parcourir le contenu. Le contenu comportant lui-même des régions de défilement peut compliquer la manipulation par l'utilisateur des régions de défilement pour l'affichage de l'ensemble du contenu imbriqué, entraînant des problèmes de convivialité.
Utilisez JSTL plutôt que d'inventer des balises courantes. La bibliothèque de balises standard Java (JSTL) définit les conditions, les itérations, les URL, la globalisation et le formatage de nombreuses balises souvent utiles. Pour plus d'informations, accédez à Utilisation de JSTL dans les JSP de portlet

WML

Utilisez le langage WML standard. Pour plus de détails, reportez-vous à la section Open Mobile Alliance.
Lorsque vous concevez un portlet, considérez qu'il peut être ouvert seul ou avec d'autres portlets.
Soyez attentif aux balises non fermées ou non reconnues. Les pages contenant des balises incorrectes produisent des résultats imprévisibles.
Utilisez uniquement des éléments qui peuvent être inclus dans une carte (probablement avec d'autres portlets et éléments) et ne créez pas de cartes séparées.
Ne définissez pas le titre de la carte.
N'utilisez pas de modèles.
N'utilisez pas de WML complexe et long puisque la capacité de la mémoire tampon peut être fixée par l'agent utilisateur, et que les portlets peuvent partager une page avec d'autres.
Evitez d'utiliser un trop grand nombre d'images. Lorsque vous utilisez des images, définissez un nom alt significatif, puisque cette opération est nécessaire pour les unités qui n'affichent pas les images, ou en cas d'échec de l'extraction de l'image. Si possible, définissez localsrc.
N'utilisez pas d'événements intrinsèques (comme oneventforward et oneventbackward) puisqu'ils ne peuvent être ajoutés que par le niveau d'agrégation.
Evitez d'utiliser des temporisateurs.
N'utilisez des événements déclenchés par l'utilisateur qu'en cas de nécessité, et définissez toujours les paramètres des étiquettes et des noms de façon explicite. Préfixez le nom à l'aide de l'identificateur unique de portlet, sans quoi différents portlets peuvent entrer en conflit sur une même page. Utilisez des noms significatifs pour les étiquettes.
Ne créez pas de tableaux ou images WML à largeur fixe dans les portlets.
Evitez les lignes de texte longues et continues sans retour à la ligne automatique, pour prévenir tout défilement superflu.

Compact HTML (cHTML)

Utilisez le langage cHTML standard. Pour toute information sur le langage HTML compatible avec i-mode, voir la page Compact HTML for Small Information Appliances.
Lorsque vous concevez un portlet, considérez qu'il peut être ouvert seul ou avec d'autres portlets.
Soyez attentif aux balises non fermées, non reconnues ou mal imbriquées. Les pages contenant des balises incorrectes produisent des résultats imprévisibles.
Utilisez uniquement des éléments qui peuvent être inclus dans un corps. N'utilisez pas les balises <head> ou <body>.
Evitez le format cHTML complexe et long, puisque les portlets peuvent partager leur page avec d'autres portlets.
Evitez d'utiliser un trop grand nombre d'images et n'utilisez pas les paramètres d'alignement et de positionnement avec des images.
Ne dépassez pas une longueur de 24 symboles pour les numéros de téléphone utilisés comme référence dans la balise <a>.
N'utilisez pas d'URL de plus de 200 octets.