Icônes - TecostNetwork/Network GitHub Wiki

Avant de commencer, il faut savoir que les icônes ont un sens et une forme. Lorsqu'on utilise une icône, il ne faut pas juste prendre celle qui a la bonne image, mais également le bon nom. Un logiciel évolue au fil du temps et nous devrons tôt ou tard changer les icônes. Il est donc important qu'elles soient nommées correctement. Si une image correspond à votre besoin mais que le nom n'a rien à voir, il est préférable de créer une nouvelle icône avec la même image par exemple (voir la section "Ajouter une icône" plus bas.

Pour l'usage et la création d'icônes, on devrait toujours pouvoir : 

• Changer une image sans devoir renommer l'icône.
• Changer une image sans devoir vérifier partout où elle s'affiche si on veut bien ce changement.

La liste de toutes les icônes du système se trouve dans la fonctionnalité "Liste des icônes" (ViewAllIcons.xhtml) de la catégorie "Développeur".

On peut cliquer sur chaque icône pour ouvrir un détail montrant celle-ci dans différents usages (colorée, bouton, bouton désactivé, taille x4...)

Les icônes sont toutes déclarées dans le fichier Icons.java sous la forme de constantes du type IconDeclaration. Le nom de la constante définit le nom de l'icône.

public final static IconDeclaration userinfoactionsBell = new IconDeclaration(GENERIC, FA_LIGHT, "fa-bell");
public final static IconDeclaration userinfoactionsHelp = new IconDeclaration(GENERIC, FA_LIGHT, "fa-question");
public final static IconDeclaration userinfoactionsKey = new IconDeclaration(GENERIC, FA_LIGHT, "fa-key");
public final static IconDeclaration userinfoactionsLogoutColor = new IconDeclaration(GENERIC, FA_LIGHT, "fa-sign-out");

Pour accéder à une icône depuis une page xhtml, il y a plusieurs possibilités dépendant du cas : 

• Si on souhaite accéder à une icône spécifique ${icons.myIconName}
• Si le contrôleur ou un bean nous fournit l'icône via un getter ${myEntity.status.icon}

On utilise ces icônes sur les attributs icon des différents composants : 

<t:icon id="myStaticIcon" icon="${icons.warning}"/>
<p:commandButton id="myButton" icon="${icons.edit}"/>
<t:icon id="myDynamicIcon" icon="${myEntity.status.icon}"/>
<t:icon id="myDynamicIcon" icon="${myController.myIcon}"/>

Les expressions vues ci-dessus référencent directement un IconDeclaration. La valeur produite par l'expression sera automatiquement récupérée via IconDeclaration.toString(). Les contrôleurs ou autres beans peuvent donc directement retourner l'icône.

public class MyController extends Controller {
   public IconDeclaration getMyIcon() {
      if (somethingIsTrue) {
        return Icons.warning;
      } else {
        return Icons.error;
      }
   }
}

Pour une énumération ayant des icônes associées aux différentes valeurs, il faut implémenter l'interface IHasImage et renseigner les icônes de chaque valeur : 

public enum RequestStatusType implements IHasImage, IRootTranslationOnly {
   PENDING(Icons.requestStatusPending),
   ACCEPTED(Icons.requestStatusAccepted),
   REJECTED(Icons.requestStatusRejected);

   private IconDeclaration icon;

   private RequestStatusType(IconDeclaration icon) {
      this.icon = icon;
   }

   @Override
   public IconDeclaration getIcon() {
      return icon;
   }
}

Bonnes pratiques

Avant d'ajouter une icône, regarder s'il y en a une qui ne pourrait pas déjà convenir. Si une icône existe mais n'a pas un nom qui correspond à notre cas, on peut créer une nouvelle icône basée sur la même image. On distingue les icônes (image ayant une signification) de leur forme (ou image). Pour ceci, il est tout à fait convenable de créer des "alias" d'icônes. Par exemple, les icônes "left", "previous" sont deux icônes avec une signification différente, mais peuvent être représentées par la même image d'une flèche gauche. il faut raisonner de la manière suivante : 

• Si on trouve une icône avec le même sens que ce dont on a besoin : utiliser celle-ci.
• Sinon si on trouve une icône avec la même image mais un sens différent : faire une nouvelle déclaration avec la même image.
• Sinon si on ne trouve rien : on peut ajouter une nouvelle icône.

Lorsqu'on ajoute une icône ou qu'on crée un alias, il faut faire attention au contexte.

• Si l'icône est générique (ex : "edit", "left", "send", "error"...) on peut lui mettre le même nom.
• Si l'icône est destinée à un objet spécifique (par exemple les status des demandes de prestations), il est préférable de les nommer selon ce contexte (ex : "healthRequestPending", "healthRequestAccepted"...).

Bons exemples : 👍

Les 4 premières icônes ont toutes la même image, mais ont des sens différents. La dernière a un sens et une image différentes : 

Icons.disabled	Utilisée pour signifier qu'un élément est inactif
Icons.disable	Utilisée pour l'action de désactiver un élément
Icons.dataInvalid	Utilisée pour indiquer qu'une donnée est incorrecte
Icons.dataIncomplete	Utilisée pour indiquer qu'une donnée n'est pas complète
Icons.warning	Utilisée pour indiquer à l'utilisateur qu'il doit faire attention à quelque chose

Si plus tard on a besoin de changer les images de certaines icônes, on peut le faire sans problème. Les images changent mais le sens reste le même : 

Icons.disabled	Utilisée pour signifier qu'un élément est inactif
Icons.disable	Utilisée pour l'action de désactiver un élément
Icons.dataInvalid	Utilisée pour indiquer qu'une donnée est incorrecte
Icons.dataIncomplete	Utilisée pour indiquer qu'une donnée n'est pas complète
Icons.warning	Utilisée pour indiquer à l'utilisateur qu'il doit faire attention à quelque chose

Mauvais exemples : 👎

Icons.warning	Utilisée pour indiquer qu'une donnée n'est pas complète. En effet warning est un terme trop générique, ce qui laisserait quelqu'un d'autre l'utiliser dans un autre contexte. Quand on voudra changer cette icône, on risque d'avoir des surprises.
Icons.crossCircle	Utilisée on ne sait pas trop pourquoi... ici l'icône ne donne aucune information sur son sens, mais uniquement sur sa forme. On devrait normalement pouvoir changer l'image sans changer le nom, ce qui n'est clairement pas le cas ici. Dans le cas où il s'agit de dire qu'une donnée est invalide, il est préférable d'utiliser un nom tel que "dataInvalid".

Les icônes proviennent en principe de FontAwesome. 

• Chercher une image qui convient sur https://fontawesome.com/icons?d=gallery
• Noter le nom, ex : "fa-pencil"
• Dans Icons.java, ajouter une nouvelle constante IconDeclaration avec le nom de l'icône.
  • on indique également le groupe auquel elle fait partie, ce qui permet de les grouper dans la liste des icônes.
  • on indique également le style (light, solid...) mais il convient d'utiliser toujours le même pour plus d'homogénéité. On peut varier le style si une icône représente par exemple un disque plein en solid et un cercle vide en light.
  • on peut indiquer une couleur, par contre il ne faut le faire "parce qu'on trouve plus joli", et il faut savoir que les icônes sont colorées automatiquement lorsqu'elles se trouvent dans un bouton. On peut colorer une icône si elle représente un statut et que la couleur apporte du sens (ex : rouge pour erreur, orange pour warning, rouge pour refusé, orange pour accepté...)

public final static IconDeclaration edit = new IconDeclaration(GENERIC, FA_LIGHT, "fa-edit");
public final static IconDeclaration enable = new IconDeclaration(GENERIC, FA_LIGHT, "fa-check-circle");

Lorsque aucune icône ne convient sur FontAwesome (mais vraiment vraiment), il est possible d'ajouter nos propres icônes à un Kit FontAwesome (attention il y a un kit par projet).

• Se rendre sur https://fontawesome.com/kits en se connectant avec le compte commun.
• Aller dans le kit du projet.

• Ajouter les SVG des icônes que vous avez trouvées (attention, il faut respecter certaines normes, mais un message d'erreur vous dira si le fichier n'est pas compatible)
• Attention aussi à bien nommer votre icône, car c'est ce nom qui sera ensuite utilisé pour la référencer via "fa-votreIconeAvecUnSuperNom".

• Lancer le DevTool UpdateFontAwesomeIconsKit.java. Celui-ci va télécharger les règles CSS pour les icônes et le fichier de font, et mettre à jour ceux du projet automatiquement.
• Faire un refresh du projet web.
• Ajouter votre icône dans Icons.java (avec le style FA_CUSTOM).

public final static IconDeclaration edit = new IconDeclaration(GENERIC, FA_CUSTOM, "fa-process");