Fonctionnalités de la librairie jsFF

jsFF est une librairie javascript modulaire basée sur prototype et scriptaculous regroupant de nombreux modules dont certains sont toujours actifs, et d'autres ne seront chargés dynamiquement (et automatiquement) selon que la page y fera appel ou non.
Son principal but est de faciliter la création de pages Web hautement dynamiques, sans avoir à réinventer la roue ou devoir passer nombre d'heures dans l'apprentissage ou les tests de nouveaux modules ou librairies, son caractère modulaire permettant d'intégrer de nouvelles fonctionnalités au fur et à mesure des besoins.

A - La mise en oeuvre et les options de jsFF

Les modules sont automatiquement activés dè lors que vous aurez inclus le code suivant dans la section <head> de votre page :

	<script type="text/javascript" src="chemin/prototype.js"></script>
	<script type="text/javascript" src="chemin/jsFF.js"></script>
Dès le chargement de la page, jsFF lance la fonction createUI(), si elle existe dans la page, afin d'initialiser les composants. Il faut donc la créer, toujours dans la section <head> de votre page :
function createUI()
{
	jsFF.message(jsFF._e('Starting creating the controls in window.createUI()'));
	... initialiser les contrôles ici ...
	jsFF.message(jsFF._e('The controls are all created from window.createUI() !'));
}

Par défaut, l'option de débogage de jsFF est activée.
Ce comportement peut être modifié en affectant la valeur false à la propriété debugging de la librairie, avant que la fonction createUI() ne soit appelée, donc toujours dans la section <head>, ajoutez le code suivant :

jsFF.debugging = false;
...
function createUI()
{
	jsFF.message(jsFF._e('Starting creating the controls in window.createUI()'));
	...
	jsFF.message(jsFF._e('The controls are all created from window.createUI() !'));
}

La librairie supporte également un module d'internationalisation qui permet de gérer les traductions des messages générés dynamiquement côté client.
Par défaut, jsFF est paramétrée pour la langue française encodée en UTF-8, mais à l'instar de la fonctionnalité de débuggage, ce paramètre peut également être ajusté lors de l'initialisation de la page, en spécifiant, avant l'inclusion du script jsFF, le bout de script suivant :

				<script type="text/javascript">JSFF_LOCALE = 'es_UTF8';</script>
				<script type="text/javascript" src="chemin/jsFF.js"></script>
Le paramètre locale doit correspondre au nom du fichier de langue, en omettant le .js final. Par ex : la locale 'fr_UTF8 chargera le fichier fr_UTF8.js.
Les fichiers de langues sont situés dans le répertoire src/ de la distribution, mais les seules traductions actuellement existantes sont :
  • - le français encodé ISO-8859-15 (src/fr.js).
  • - le français encodé UTF-8 (fichier src/fr_UTF8.js).

B - Les fonctions utilitaires

Les deux principales fonctions utilitaires servent à l'internationalisation : la première (sprintf(...)) est l'équivalent javascript de la fonction C printf(...) qui fournit un moyen pratique de formatage des chaines de caractères, l'autre permet tout simplement de traduire des chaines de caractères.
D'autres fonctions permettent de générer des messsages à destination de la fenêtre de déboggage de jsFF.

  • sprintf(...)

    La fonction sprintf provient du site webtoolkit.info, et fournie sous licence CREATIVE COMMONS 2. Exemple d'utilisation de sprintf(...) :
    var s = sprintf("Je me nomme %s, et j'ai écrit plus de %d ouvrages, dont <strong>'%s'</strong> et <strong>'%s'</strong>.", 
    		"Victor Hugo", 50, "Les Misérables", "La légende des siècles");
    affectera à la variable s la chaine : "Je me nomme Victor Hugo, et j'ai écrit plus de 50 ouvrages, dont 'les Misérables' et 'La légende des siècles'.

    La première variable passée à sprintf(...) est la chaine à formatter, dans laquelle les termes à remplacer sont indiqués sous la forme %format, les variables suivantes étant les valeurs utilisées pour le formattage. Les types % admissibles étant :

    • - %% : pour insérer le caractère littéral %.
    • - %b : pour insérer un nombre entier au format binaire.
    • - %c : pour insérer un caractère identifié par son code ASCII.
    • - %d : pour insérer un nombre entier au format décimal.
    • - %f : pour insérer un nombre décimal au format décimal.
    • - %o : pour insérer un nombre entier au format octal.
    • - %s : pour insérer une chaine de caractères.
    • - %x : pour insérer un nombre entier au format hexadécimal (lettres minuscules).
    • - %X : pour insérer un nombre entier au format hexadécimal (lettres majuscules).

    • des modificateurs de format sont également disponibles :

    • - + : force l'insertion des symboles de signe (+ ou -) devant un nombre (par défaut, seul le signe - est indiqué).
    • - - : justifie à gauche une variable.
    • - [0-9] : spécifie la largeur minimale d'une variable.
    • - .[0-9] : spécifie le nombre de décimales après la virgule pour un nombre ou la taille maximale d'une chaine de caractères.
    • Exemple : sprintf('%.2f', 100.5641) retournera 100.56

  • jsFF._e(...)

    La fonction jsFF.e("mon message") permet de générer la traduction dans la locale couramment définie pour jsFF sous la condition expresse que cette chaine figure dans le fichier de langue correspondant. Lorsque le message à traduire comporte des parties variables, il faut alors utiliser la fonction sprintf(...) afin de pouvoir ne fournir qu'une chaine unique dans le fichier de langue.
    Exemple d'utilisation de jsFF._e(...) :
    var s = sprintf(jsFF._e("my name is %s"), 'Victor Hugo');
    retournera "Je me nomme Victor Hugo" si la locale est fixée à fr , et que la traduction de la chaine "my name is %s" figure bien dans le fichier de langue po/fr.js.
  • jsFF.Browser()

    jsFF.Browser() est une fonction permettant de reconnaitre le navigateur client. Elle retourne un tableau javascript comportant les champs suivants :
    • nver : le n° de version majeur du navigateur.
    • ver : ne n° de version du navigateur.
    • agent : l'identification javascript du navigateur (userAgent).
    • dom : VRAI si le navigateur supporte les accès au DOM.
    • opera : VRAI si navigateur OPERA.
    • ie[345678] : VRAI si le navigateur est Internet Explorer Version 3, 4, 5, 6, 7 ou 8.
    • ie : VRAI si le navigateur est Internet Explorer.
    • ns4 : VRAI le navigateur est Netscape 4.
    • ns6 : VRAI si le navigateur est > Netscape 6 ou FireFox.
    • hotjava : VRAI si le navigateur est HotJava.
    • operaOld : VRAI si le navigateur est Opera version < 7.
    • opera7 : VRAI si le navigateur est Opera version 7.
    • safari : VRAI si le navigateur est Safari.
    tester...
  • jsFF.getAccessPath()

    Cette fonction retourne l'URL d'accaès vers la librairie jsFF.tester...
  • jsFF.getClientSize()

    Cette fonction retourne la taille de la zone client du navigateur.tester...
  • jsFF.message(...), jsFF.notice(...), jsFF.error(...)

    Ces fonctions se basent sur la librairie Prototype UI publiée sous une licence permissive de type MIT qui permet de gérer du fenêtrage en javascript.
    Elles permettent d'envoyer des messages de log, d'avertissement ou d'erreur dans la fenêtre de débuggage de jsFF.
    Les messages s'affichent de couleur verte, les avertissements apparaissent en jaune, et les erreurs en rouge.
    tester...
  • jsFF.alert(message[, options])

    La fonction jsFF.alert(...) affiche la chaine de caractères passé en argument dans un dialogue modal centré à l'écran. tester...
  • jsFF.info(message, delai[, options])

    La fonction jsFF.info(...) affiche la chaine de caractères passé en argument dans un dialogue modal centré à l'écran, puis la referme après le délai (exprimé en millisecondes) écoulé. tester...
  • jsFF.confirm(message[, options])

    La fonction jsFF.confirm(...) affiche la chaine de caractères passé en argument dans un dialogue modal centré à l'écran.
    Les options possibles sont les suivantes :
    • okLabel : le libellé du bouton qui retournera VRAI.
    • cancelLabel : le libellé du bouton qui retournera FAUX.
    • id : l'identificateur du dialogue devant être généré.
    • cancel : fonction qui sera exécutée sur sélection du bouton d'annulation.
    • ok : fonction qui sera exécutée sur sélection du bouton de confirmation.
    • width : La largeur du dialogue à l'écran (centré horizontalement si omis).
    • height : La hauteur du dialogue à l'écran (automatiquement ajusté si omis).
    • buttonClass : La classe CSS des boutons (si omis, la classe par défaut jsFF.alertCSS sera utilisée.
    tester...

C - Les modules de base

  • composants de dialogues et fenêtrage

    • Dialogue de login :

      tester

      jsFF propose un dialogue de login permettant de faire valider le couple login/mot de passe par une URL déterminée; : qui devra retourner une variable status fixée à true ou false.

      Le seul paramétre attendu par la fonction est un objet options comportant les propriétés suivantes :

      • title : le libellé du titre du dialogue.
      • msg : le libellé du message d'invite qui sera affiché en haut de la boite de dialogue.
      • msgErr : le libellé du message qui sera affiché en cas d'erreur de login.
      • libLogin : le libellé qui sera affiché devant la zone de saisie du nom d'utilisateur ('nom d'utilisateur' par défaut).
      • libPassword : le libellé qui sera affiché devant la zone de saisie mot de passe ('Mot de passe' par défaut).
      • url : l'URL vers laquelle sera transmis le nom d'utilisateur et le mot de passe saisis (paramétres POST login et passwd).
      • crypt : le type d'encryptage utilisé pour la transmission du mot de passe. Les valeurs admissibles sont none, sha1, md4, md5: (paramétre POST crypt).

      Le dialogue affichera un message d'erreur et une courte animation tant que l'URL appelée ne retourne une valeur status=true.

      Par contre, en cas d'authentification positive, la page courante sera redirigée vers l'URL pointée par status.url si elle est fournie par le code d'authentification, ou rechargée dans le cas contraire.

  • composant calendrier : datePicker

    Ce composant permet de transformer une simple zone de saisie texte (<input type="text" ...>) en un calendrier qui s'active lorque qu'il obtient le focus.
    Le résultat obtenu est alors le suivant :
     recréer le calendrier...
    Dès lors qu'un appel à la fonction
    jsFF.addDatePicker('date1', {FromYear:2009, UpToYear:2019});
    aura été effectué. (Voir la doc.)
  • composant de validation

    La validation s'effectue en ajoutant des classes particuliès sur les composants à valider et en invoquant dans la fonction initiale (createUI) la méthode

    jsFF.setValidation('formulaire');
    qui servira à intercepter l'évênement submit afin de procéder aux vérifications. (Voir la doc.)

D - Les modules additionnels

  • - Séparateurs : SplitPanel

    TODO
  • - Composant de pagination : Paginator

    TODO
  • - Composant menu 'à la Mac OS X' : IconDock

    TODO
  • - Composant de téléchargement : SWFUpload

    TODO
  • - diaporama : fadeSlideShow

    Ce composant permet de créer des diaporamas pouvant, au besoin, afficher un titre, un commentaire et rediriger vers une URL pour chacune des images présentées.
    (Voir la doc.)
  • - boutons 3D (boutons radio ou cases à cocher) : 3dButtons

    Ce composant permet de transformer des boutons radio ou cases à cocher en remplaçant leur interface habituelle par des images changeant selon l'état du contrôle sous-jacent. Les contrôles eux-mêmes étant simplement cachés et conservés afin de permettre de transmettre les valeurs dans les formulaires.
    Le résultat obtenu est alors le suivant :
    Composez votre menu :
    Salami
    champignons
    anchois
    Dès lors qu'un appel à la fonction
    jsFF.add3dButtons('choix_menu');
    aura été effectué. (Voir la doc.)