NAV
javascript html

Introduction

Bienvenue dans la documentation de Backbone-Goomeo, la library tout en un pour Backbone comprenant entre autre :

Vous trouverez dans cette documentation toutes les infos pour utiliser ce projet au sein du votre.

Prérequis

Attention : Cette library a été conçue pour être utilisée au sein d’un projet pour du Front et compilé avec Browserify.

Vous devez impérativement avoir NodeJS >= 0.12 pour pouvoir utiliser cette library.

Compatibilité

Normalement tous les composants Riot et le code Javascript sont compatible sous ie9+. Toutefois, plusieurs animations CSS et la police d’icône ne fonctionneront pas dessus.

Installation

npm install --save backbone-goomeo

Browserify

Pour la compilation du projet, nous utilisons le package Browserify qui permet de coder son projet en utilisant la norme CommonJS en lieu et place de la norme AMD.

CommonJS

La norme CommonJS permet de structurer son code en fichiers et d’appeler les dépendances comme nous le ferions sous NodeJS :

'use strict';

// appel des dépendances et les stocker dans des var
var $ = require('jquery');

// appel de dépendances sans les stocker dans des variables (ex: pour étendre jquery)
require('jquery.form2js');

// objet/fonction/variable retourné par l'appel de ce fichier par la commande require()
module.exports = function () {
  console.log('a');
};

Limitations

La seule limitation avec Browserify, c’est que votre code ainsi structuré n’est pas utilisable directement dans le navigateur. Vous devrez impérativement builder votre code afin de générer un fichier javascript valide.

Configuration

Il est possible de dire certaines choses à Browserify pour simplifier l’utilisation des ressources externes, mettre certaines variables en global sur notre code, …

Librairies externes

Il est possible que dans les librairies installées par NPM, il y en aie plusieurs qui ne soient pas prévues pour fonctionner sous CommonJS. Heureusement, il est possible de palier à ceci dans le fichier package.json afin d’indiquer à Browserify de convertir les fichiers suivants :

Browser files

{
  "browser": {
    "jQuery": "./node_modules/jquery/dist/jquery.min.js",
    "jquery.form2js": "./node_modules/form2js/src/jquery.toObject.js"
  }
}

Ici nous indiquons aux fichiers jquery.min,js et jquery.toObject.js d’être convertis en fichiers CommonJS valide et d’être appelé avec la fonction require() via le mot clé jQuery et jQuery.form2js.

Variables globales

Dans le projet nous utilisons qu’une variable globale : jquery. Effectivement, si l’on veut require('jQuery'), on va tout le temps récupérer l’objet jQuery de base et non l’objet étendu par tous les modules. Pour palier à ça, nous plaçons jQuery en variable globale afin d’avoir toujours le jQuery étendu au lieu de celui de base.

Pour cela, nous passons par un shim de browserify configuré comme ceci :

Shims :

{
  "browserify-shim": {
    "jquery": "global:jQuery"
  }
}

Ici on dit que la variable globale jQuery sera chargée automatiquement dans nos script avec l’appel require('jquery').

Bien entendu, il faut que dans votre code vous ayez ceci :

variables globales :

// définition de la variable globale jQuery
global.jQuery = require('jQuery');

Alias

Les alias servent à simplifier l’accès à différents répertoires du projet. Par exemple, si vous êtes dans un sous répertoire au cinquième niveau et que vous voulez récupérer un template, vous devrez préfixer votre require de plusieurs ../ ce qui peut vite devenir embêtant.

Voici la liste des alias disponibles :

Alias Correspond à
collections /js/collections
components /js/components
libs /js/libs
models /js/models
modules /js/modules
tpl /js/tpl

Si vous voulez ajouter un template facilement, vous le pouvez grâce au package.json de la façon suivante :

{
  "aliasify": {
    "aliases": {
      "tpl": "./js/tpl",
      "models": "./js/models",
      "components": "./js/components",
      "libs": "./js/libs",
      "modules": "./js/modules",
      "collections": "./js/collections"
    }
  }
}

Jquery

Le projet utilise toujours une couche de jQuery pour simplifier la manipulation du DOM ou pour le bon fonctionnement de Backbone.

Appel

Si vous avez besoin d’utiliser jQuery, vous avez plusieurs façons de le faire selon l’endroit où vous êtes :

Extensions

Il est parfois utile et nécéssaire d’étendre jQuery avec de nouvelles fonctions/modules. Pour cela, plusieurs solutions sont possibles.

Si vous voulez éttendre jQuery à tout le projet, peu importe l’application lancée derrière, vous devrez injecter les dépendances dans le fichier js/init.js. Là vous trouverez une fonction qui s’appelle extendjQuery et vous aurez juste à ajouter votre module par un simple appel à require('monmodule') :

{
  extendjQuery : function extendjQuery() {
    $.support.cors = true;

    // form2js pour $('form').toObject();
    require('form2js');
    require('jquery.form2js');
  }
}

Exceptions

Attention : Il est fortement probable que certains modules jQuery ne soient pas pensés pour fonctionner avec CommonJS.

Si c’est le cas, vous devrez renseigner certaines choses dans le fichier package.json à la rubrique browser :

{
    "browser" : {
         "jQuery"         : "./node_modules/jquery/dist/jquery.min.js",
         "jquery.form2js" : "./node_modules/form2js/src/jquery.toObject.js"
    }
}

Ceci va permettre à browserify de convertir le code du fichier en code compatible CommonJS et de créer un alias pour le récupérer via la commande require().

Logger

Le logger sert à réaliser du log de différents levels au sein de l’application.

Ces logs sont disponibles en 5 niveaux :

level code fonction description
0 TRACE trace() Permet d’afficher toute sorte d’informations
1 DEBUG debug() Permet de logger des informations dites de debug
2 INFO info() Permet d’afficher des messages d’information
3 WARN warn() Permet d’afficher des messages d’erreurs non bloquantes
4 ERROR error() Permet d’afficher des messages d’erreurs critiques ou bloquantes

Pour utiliser facilement ces noiveaux de log et savoir lesquels afficher en fonction de notre environnement, nous utilisons la library loglevel ainsi que son extension loglevel-message-prefix pour avoir un préfixe d’erreur propre.

Initialisation

Si vous voulez créer votre propre logger, voici la marche à suivre :

var log                     = require('loglevel'),
    loglevelMessagePrefix   = require('loglevel-message-prefix');

var logger = log.getLogger('unnompourlerendreunique');

loglevelMessagePrefix(this._logger, {
    staticPrefixes : [ 'unnompourlerendreunique' ]
});

// ensuite vous pouvez utiliser logger comme vous voulez
logger.info('test info');

Vues Backbone

Les vues Backbone du projet ne devront pas étendre Backbone.View. En effet, nous avons créer une classe de base afin d’ajouter un nombre de fonctions utiles permettant d’améliorer le développement.

La classe de base se trouve dans /js/libs/backbone/views/base.js. Si vous voulez éttendre cette vue pour avoir d’autres vues de base réutilisables, vous devrez les créer dans le répertoire /js/libs/backbone/views

Organisation

Toute la partie javascript sera rangée dans le répertoire js et toute la partie HTML sera rangée dans le répertoire tpl.

Chaque groupe fonctionnel de vues doit se retrouver dans un répertoire désignant ce même groupe. Par exemple, toutes les vues composant le module LNS se retrouvent dans un sous répertoire lns. De même, la vue maîtresse de ce groupe devra s’appeler index.

Les parties vues et templates doivent suivre la même règle et les mêmes nommages. Par exemple, le template de la vue /modules/events/lns/index.js se retrouvera comme ceci : /tpl/events/lns/index.html

js
├── collections                  # Répertoire de toutes les collections
│   └── todo                     # collections propres au module todo
│       └── tasks.js             # Collection tasks
├── models                       # Répertoire de tous les models
│   └── todo                     # models propres au module todo
│       └── task.js              # model task
├── modules                      # Partie vues Javascript
│   └── todo                     # vues propres au module todo
│       ├── forms                # répertoire des formulaires
│       │   └── form.js          # vue du formulaire
|       ├── item.js              # vue pour une tâche
│       └── index.js             # page d'accueuil du module todo
└── tpl                          # templates
    └── todo                     # vues propres au module todo
        ├── forms                # répertoire des formulaires
        │   └── form.html        # template du formulaire
        └── index.html           # template de la page d'accueuil

Création d’une sous vue

Dans les anciens projets, nous avions pour habitude de créer toutes les sous vues par le viewManager. Mais la tâche était redondante sur le fait qu’il fallait ajouter manuellement la vue au tableau subviews afin que toutes les vues soient détruites quand la principale l’était.

Dorénavant, vous devrez passer par la méthode this.createSubView(). La fonction s’utilise de la même façon à la différence que vous n’avez plus besoin de rajouter la sous-vue au tableau de subviews. Elle le fait pour vous.

// avant
var subView = vm.create('nomdevotrevue', votreView, {
    key : 'foo'
});
this.subviews.push(subView);

// après
var subView = this.createSubView('nomdevotrevue', votreView, {
    key : 'foo'
});

Le nom de votre vue sera composée comme ceci :

fichier : /js/modules/events/maps/index.js
vue     : events:maps:index

Ouverture/fermeture d’un slidePanel.

ouverture :

this.panels.open({
    view    : this.createSubView('todo:form', formView, {
        model : this.model
    }),
    options : {
        title : 'Test'
    }
});

fermeture :

this.panels.close();

Un slidePanel est un panneau latéral souvent utilisé pour afficher des formulaires ou des donnés complémentaires. Vous avez la possibilité d’en ouvrir et d’en fermet facilement au sein de votre vue backbone gràce à this.panels.

Cet objet vous donne accès aux fonction open() et close du panelManager.

Si vous voulez plus d’informations. rendez-vous sur la documentation du panelManager.

Montage de tags Riot

Pour de plus amples informations concernant les tags, comment les créer, rangement, …, Veuillez vous rendre sur la documentation dédiée.

De base, riot regarde le DOM de toute la page web pour créer nos tags et ne garde donc pas la notion de DOM limitée à notre vue courante Backbone. Afin de palier au problème, si vous voulez monter des tags dans votre vue Backbone, vous le pouvez grâce à la fonction mountTags(params).

this.mountTags({
    tag : 'jumbotron'
});

Attention : Vu que Riot fait la recherche sur le el de votre vue, pensez à ajouter le contenu au DOM avant l’appel de cette fonction. De même, pensez à précharger votre tag dans votre vue comme ceci :

var _           = require('underscore'),
    View        = require('libs/backbone/views/base'),
    tpl         = require('tpl/index.html');

// préchargement des tags ici
require('components/examples/jumbotron.tag');

module.exports = View.extend({
});

Événements

De Vue

Les événements de vue sont renseignés dans les vues via l’attribut events. Ces événements sont des événements jQuery sur le $el de la vue uniquement (et de ses sous vues).

L’objet events se sépare en deux parties :

Le contexte des fonctions appelées par events (la variable this), correspond à votre vue.

Events de vue

{
  events : {
    'submit form'  : 'validAction',
    'click a#toto' : 'redirectAction'
  },
  validAction : function (evt) {
    // action du formulaire
  },
  redirectAction : function (evt) {
    // action de redirection
  }
}

Globaux

Les événements globaux permettent d’effectuer des actions entre vos différentes vues. Par exemple, si une de vos vue finit l’envoie d’un formulaire, elle peut déclencher l’événement d’envoie avec la réponse en paramètre.

Toutes les vues qui écoutent sur ce même événement vont exécuter en même temps la fonction rattachée.

La liste des événements globaux sur lequel une vue écoute est renseignée dans l’attribut globalEvents et se présente comme les événements de vue :

Le contexte des fonctions appelées par events (la variable this), correspond à votre vue.

Events globaux :

{
  globalEvents : {
      'submitForm' : 'submitAction',
      'addElement' : 'addElementAction'
  },
  submitAction : function submitAction() {
      console.log('submitAction');
  },
  addElementAction : function addElementAction(element) {
    console.log(element);
  }
}

Pour envoyer un événement global, vous devrez faire comme ceci :

this.global.trigger('submitForm');
this.global.trigger('addElement' {
  name : 'foo'
});

Tag -> View

Nos vues Backbone peuvent directement capturer des événements Riot (si bien entendu ils en déclenchent) simplement de la même façon que les événements de vue et les événements globaux. Bien entendu, vous ne pouvez écouter sur une vue que les événements des tags qu’elle contient.

La liste des événements de Tags de vue est renseignée dans l’attribut tagEvents et elle est séparée en deux niveaux. Au premier niveau on trouve un objet avec pour chaque field le nom du tag et, pour chaque tag, les événements correspondant à evenement + selecteur CSS :

Events de tags :

{
  tagEvents : {
    jumbotron : {
      'click #testId' : 'clickAction'
    }
  },
  clickAction : function clickAction(tag) {
      tag.unmount();
      console.log(this);
  },
}

Dans l’exemple ci dessus, lorsque l’on reçois l’événement click d’un tag jumbotron ayant l’ID testId, alors on effectue l’action clickAction.

Les callback de ces événements ont au moins un paramètre qui correspond à l’objet du Tag concerné par l’événement. Le contexte des fonctions (la variable this), correspond à votre vue.

Sockets

Nos vues Backbone peuvent aussi directement capturer les événements des sockets qui lui sont rattachés, et ce, de la même façon que les autres événements. Bien entendu, vous ne pouvez écouter que sur les sockets qui sont rattachés à votre vue.

La liste des événements sockets est renseignée das l’attribut socketEvents et elle est séparée en deux niveaux. Au premier niveau on trouve un objet avec, pour chaque field le nom du socket et, por chaque socket, les événements correspondants et leur action rattachée.

Attention : pour le socket par défaut (celui sans non si vous avez qu’un seul socket), ses événements sont à renseigner dans le field default.

{
  socketEvents : {
    default : {
        'test-result'   : 'socketCallbackAction',
    }
  },
  socketCallbackAction : function socketCallbackAction(params) {
      this.getLogger().debug(params);
  }
}

Les callback de ces événements ont au moins un paramètre qui correspond à ce que socket.io vous retourne (s’il vous retourne quelque-chose). Le contexte des fonctions (la variable this), correspond à votre vue.

Stickit

Nos vues backbone étendent toutes la bibliothèque Stickit développé par le New York Times. Sa documentation complète afin de rentrer plus en détail dans son fonctionnement se trouve ici

Instanciation

Pour utiliser Stickit, vous avez plusieurs choix possibles entre : Le renseignement directement dans les propriétés de la vue ou en appel direct dans le code comme expliqué dans leur documentation.

À savoir : Dans nos vues, vous n’aurrez pas besoin de faire l’appel à la fonction this.stickit() à la fin de votre render. Il est fait automatiquement par nos vues juste après l’instanciation des tags Riot. De plus, vous n’êtes pas limités, dans les propriétés de la vue, au binding du model principal.

Modèle Principal

Pour le modèle principal (renseigné par this.model), les Bindings sont renseignés dans le field bindings comme ceci :

{
    bindings : {
        '#author': 'author'
    }
}

Ici, si le field authors de mon modèle est modifié, alors l’élément de ma vue avec l’identifiant #authors est mis à jour avec la nouvelle valeur.

Modèles complémentaires

Pour les modèles complémentaires (renseignés dans this.models), les Bindings sont renseignés dans le field <nomdumodel>Bindings. Ce qui nous donne :

{
    userBindings : {
        '#name' : 'name'
    },
    moduleBindings : {
        '#lock' : 'islocked'
    }
    initialize : function (options) {
        this.models.user    = options.user;
        this.models.module  = options.module;
    }
}

Ici, les bindins du modèle user sont renseignés dans le field userBindings et les bindings du modèle module sont renseignés dans le field moduleBindings.

Render

appel pour l’affichage

$('body').html(view.render().$el);

déclaration de la fonction

render : function (done) {
    this.$el.html(this.template(tpl, {
        model : this.model
    }));

    done();
}

La fonction render renseignée dans la vue est maintenant asynchrone. En effet, au lieu de faire un return this, vous devrez exécuter le callback passé en paramètre.

Par contre, quand vous appellerez la méthode render dans un router ou pour l’affichage d’une sous vue, rien ne change. En effet lors de l’appel, plusieurs fonctions sont automatiquement appelées :

Et pour finir, chargement de backbone.stickit sur tous les models de la vue, montage des tags de base Riot et lancement de l’événement DOMContentLoaded

Sockets

Il est possible de rattacher des connexions sockets aux vues Backbone comme ceci :

{
    socket : '0.0.0.0:8080', // default socket
    sockets : {
        importer : 'importer.socketexample.io'
    }
}

Si la connexion existe déjà, on récupère l’existante sinon on la créée. Vous pourrez directement communiquer en socket des façons suivantes :

this.socket.emit('test', {
    name : 'Laurent'
}, (result) => {
    this.getLogger().debug(result);
});
this.sockets.importer.emit('test', {
    name : 'Laurent'
});

Le rattachement d’événements se fait comme vu plus haut sur la gestion des événements Socket.

Riot

Riot.JS est un petit framework permettantde crér des tags à la manière de Reat.JS afin de réutiliser très facilement des composants complexes.

La documentation complète (et en français) se trouve ici

Organisation

Les tags de Riot sont rangés dans le répertoire js/components et sont rangés par rapport aux modules les utilisant (ou common pour les composants communs).

Structuration

<tag-name>
  <!-- contenu HTML du tag -->

  <script>
    // script rattaché aux tags
  </script>
</tag-name>

Les tags sont définis dans le noeud tag-name qui sera à remplacer par le nom de votre tag (par exemble : colorpicker, datepicker, …) et il est divisé à l’intérieur en deux grandes parties :

Attention : Les alias de Browserify pour le require ne marchent pas du tout ici.

Composants de base

Vous trouverez ici la liste complète ainsi que le fonctionnement de tous les composants de base RiotJS.

Chips

Génère un composant chips définit par materialize. Est aussi utilisé si vous voulez créer des tags.

<chips content="Chip d'exemple"></chips>

this.mountTags({
    tag : 'chips'
});
option description default
content Contenu de la chip. Si le libellé est un code de traduction, il sera automatiquement traduit -
img url d’image de la chip affiché en cerclé à gauche -
close Si présent, affiche une croix à droite pour pouvoir supprimer la chip -

Voici la liste des événements que vous pouvez capturer dans votre vue :

événement description
close Appelé lors du clic sur le bouton close de la chip

Empty

Génère une empty view avec icône + texte. Utilisé pour les vues liste si aucun élément disponible

<empty material="true" data-icon="list" data-message="tasksEmpty"></empty>

this.mountTags({
    tag : 'empty'
});
option description default
material Si renseigné, on passe par les icônes material -
dataIcon nom de l’icône (ou sa classe si non material) -
dataMessage Message affiché. Si le libellé est un code de traduction, il sera automatiquement traduit -

Raw

Génère une vue contenant du code HTML. Ce composant est surtout utilisé pour gérer le rendu html d’une variable dans un autre composant RiotJS personnalisé.

<raw content="contenuHtmlouPas" />

this.mountTags({
    tag : 'raw'
});
option description default
content Contenu de l’objet Raw. Si il contient de l’HTML, sera affiché avec le bon formattage. -

I18n

Permet de traduire un texte, mot, phrase dans la langue courante à partir d’un mot clé. Le système de traduction passe par la classe i18n du projet utilisant en arrière plan la library globalize.

À noter que le tag se trouve moins personnalisable que la fonction de traduction fournie par la classe i18n. Si vous voulez plus de choix, veuillez ne pas utiliser le tag.

<i18n word="welcome" />

this.mountTags({
    tag : 'i18n'
});
option description default
word mot clé à traduire par rapport à vos fichiers json de globalize -
locale Permet de traduire dans une autre locale que la locale courante -
var- Variables à insérer dans la traduction comme par exemple une quantité, un nom, une heure, … -

Pour les variables, vous devrez les passer comme ceci si par exemple votre phrase à traduire a besoin de la variable quantity :

<i18n word="cartItem" var-quantity="2" />

Composants loaders

Les composants loaders permettent d’afficher un loader à l’écran. Barre de progression, spinner, barre de loading indéterminé, …

Spinner

<spinner
    size="button"
    color="spinner-grey-only"
    ></spinner>

this.mountTags({
    tag : 'spinner'
});
option description default
size Taille du spinner parmi button, small et big small
color Couleur du spinner parmi spinner-green-only, spinner-red-only, spinner-blue-only, spinner-yellow-only et spinner-grey-only spinner-green-only

Progress

Génère une progressBar faisant, selon les cas, soit une progression standard, soit une progression indéterminée.

<material-progress></material-progress>

this.mountTags({
    tag : 'material-progress'
});
option description default
isdeterminate Si présent, alors la progressBar est de type déterminé -
progress Permet de dire à combien de % se situe la progressBar. Ne marche que si isdeterminate est renseigné 0

Voici les événements que vous pouvez lancer depuis le javascript gràce à la fonction trigger :

événement description
progress Permet de changer le pourcentage de la progressBar

Composants formulaire

Tous les composants de formulaires utilisent l’apparence Material UI définie par materialize-css.
De base, si vous utilisez ces composants Riot dans une vue Backbone étendant backbone-goomeo/js/libs/backbone/views/base.form, alors vous aurez automatiquement de chargés les composants material-input et material-textarea

Input

<material-input
    col="s6"
    data-id="name"
    data-name="name"
    parsley-required="true"
    ></material-input>

this.mountTags({
    tag : 'material-input'
});

Input de base généré avec le label associé.

option description default
col Si renseigné, permet de définir la colonne associée au grid système -
data-id Identifiant de l’input -
data-name Nom de l’input -
type Type de l’input text
disabled Si renseigné, disable l’input -
icon nom de l’icon du material design afin de le rajouté en préfixe -
value valeur de l’input -
is-active ajoute la classe active au label associé -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit name
no-label Si renseigné, l’input n’aura pas de label -

Textarea

<material-textarea
    col="s6"
    data-id="name"
    data-name="name"
    parsley-required="true"
    ></material-textarea>

this.mountTags({
    tag : 'material-textarea'
});

Textarea de base généré avec le label associé.

option description default
col Si renseigné, permet de définir la colonne associée au grid système -
data-id Identifiant de l’input -
data-name Nom de l’input -
disabled Si renseigné, disable l’input -
icon nom de l’icon du material design afin de le rajouté en préfixe -
value valeur de l’input -
is-active ajoute la classe active au label associé -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit name
no-label Si renseigné, l’input n’aura pas de label -

Checkbox

<material-checkbox
    data-id="name"
    data-name="name"
    parsley-required="true"
    label="Choix 1"
    ></material-checkbox>

this.mountTags({
    tag : 'material-checkbox'
});

Checkbox de base généré avec le label associé.

option description default
data-id Identifiant de l’input -
data-name Nom de l’input -
disabled Si renseigné, disable l’input -
value valeur de l’input -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit -
isfilled Si présent rajoute la classe filled-in à la checkbox -
checked Si présent, rajoute l’attribut checked à la checkbox -

Radio

<material-radio
    data-id="name"
    data-name="name"
    parsley-required="true"
    label="Choix 1"
    ></material-radio>

this.mountTags({
    tag : 'material-radio'
});

Radio de base généré avec le label associé.

option description default
data-id Identifiant de l’input -
data-name Nom de l’input -
disabled Si renseigné, disable l’input -
value valeur de l’input -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit -
isgap Si présent rajoute la classe with-gap à la radio -
checked Si présent, rajoute l’attribut checked à la radio -

Select

<material-select
    col="s6"
    data-id="name"
    data-name="name"
    parsley-required="true"
    default="Choose item please"
    ></material-select>

this.mountTags({
    tag : 'material-select',
    options : {
        items : [
            { value : 1, name : "Choice One" },
            { value : 2, name : "Choice Two" }
        ]
    }
});

Select de base avec les éléments passés en Javascript

option description default
col Si renseigné, permet de définir la colonne associée au grid système -
data-id Identifiant de l’input -
data-name Nom de l’input -
disabled Si renseigné, disable l’input -
multiple Si présent, le select est un multiselect -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit choice
default Option par défaut des selects affichée en première position sans aucune valeur associée -
no-label Si renseigné, l’input n’aura pas de label -
items Tableau d’éléments [ ]
items[ ].name libellé d’un élément -
items[ ].value valeur d’un élément -
items[ ].selected Si présent, alors lélément est sélectionné -

Switch

<material-switch
    data-id="name"
    data-name="name"
    on="Label de droite"
    off="Label de gauche"
    ></material-checkbox>

this.mountTags({
    tag : 'material-switch'
});

Switch de base.

option description default
data-id Identifiant de l’input -
data-name Nom de l’input -
disabled Si renseigné, disable l’input -
value valeur de l’input -
checked Si présent, rajoute l’attribut checked à l’input -
on libellé du label positionné à droite (switch checked). Si le libellé est un code de traduction, il sera automatiquement traduit on
off libellé du label positionné à gauche (switch non checked). Si le libellé est un code de traduction, il sera automatiquement traduit off

Colorpicker

Génère un colorpicker avec le label de base. Pour le colorpicker, on utilise la library jquery Spectrum qui permet d’avoir un colorpicker complet et léger.

<colorpicker
    col="s6"
    data-id="color"
    data-name="color"
    parsley-required="true"
    ></colorpicker>

this.mountTags({
    tag : 'colorpicker'
});
option description default
col Si renseigné, permet de définir la colonne associée au grid système -
data-id Identifiant de l’input -
data-name Nom de l’input -
color couleur renseignée de base -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit color
no-label Si renseigné, l’input n’aura pas de label -
spectrum Configuration spectrum. Merci de voir la documentation de Spectrum -

Voici la configuration de base de spectrum :

option description valeur
showInitial Permet d’afficher la couleur de base en entrant dans le colorpicker et la nouvelle couleur true
showInput Affiche l’input de couleur afin de rentrer le code rgba, hex, hex8, … true
preferredFormat Format d’affichage de la réponse dans l’input hex

Voici la liste des événements que vous pouvez capturer dans votre vue :

événement description
change.spectrum appelé quand la couleur de spectrum a été validée
show.spectrum appelé lors de l’affichage du composant spectrum
hide.spectrum appelé lors du masquage du composant spectrum
beforeShow.spectrum appelé après l’affichage de spectrum
dragstart.spectrum appelé quand on bouge le curseur de couleur dans spectrum
dragstop.spectrum appelé quand on relache le curseur de couleur dans spectrum

Datepicker

Génère un datepicker avec le label de base. Pour le datepicker, on utilise la library jquery pickadate modifiée par l’équire de materialize-css.
Cette library permet d’avoir un datepicker entièrement configurable.

<material-datepicker
    col="s6"
    data-id="date"
    data-name="date"
    parsley-required="true"
    icon="event"
    ></material-datepicker>

this.mountTags({
    tag : 'material-datepicker'
});
option description default
col Si renseigné, permet de définir la colonne associée au grid système -
data-id Identifiant de l’input -
data-name Nom de l’input -
value date renseignée de base -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit date
no-label Si renseigné, l’input n’aura pas de label -
icon nom de l’icon du material design afin de le rajouté en préfixe -
disabled Si renseigné, disable l’input -
datepicker Configuration du datepicker. Merci de voir la documentation de pickadate -

Voici la configuration de base de datepicker :

option description valeur
container Emplacement de la fenêtre du datepicker dans le DOM html. Doit être un sélecteur CSS valide. body

Voici la liste des événements que vous pouvez capturer dans votre vue :

événement description
datepicker:open Appelé lors de l’ouverture du datepicker
datepicker:close Appelé lors de la fermeture du datepicker
datepicker:render Appelé lors de l’affichage du datepicker
datepicker:start Appelé lors de l’initialisation du datepicker
datepicker:stop Appelé lors de la destruction du datepicker
datepicker:set Appelé lors du passage d’une valeur

Slider

Génère un slider basé sur l’input HTML5 range.

<material-slider
    data-id="date"
    data-name="date"
    parsley-required="true"
    ></material-slider>

this.mountTags({
    tag : 'material-slider'
});
option description default
data-id Identifiant de l’input -
data-name Nom de l’input -
value date renseignée de base -
disabled Si renseigné, disable l’input -
min Valeur minimale du slider 0
max Valeur maximale du slider 100

NoUiSlider

Génère un slider plus complet en utilisant la library noUiSlider.

<material-nouislider></material-nouislider>

this.mountTags({
    tag : 'material-nouislider',
    options : {
        slider : {
            start: [0, 100],
            connect: true,
            step: 1,
            range: {
                'min': 0,
                'max': 100
            }
        }
    }
});
option description default
slider Options de noUiSlider. Merci de voir la documentation de nouislider -

Voici la configuration de base de nouislider :

option description default
start Valeurs de départ du slider [0, 100]
step De combien en combien bouge la valeur du slide 1
range Valeur min/max du slider { min : 0, max : 100 }
format Transformation de la valeur du slider. Par défaut, on supprime les décipales des valeurs du slider { to : function, from : function }

Voici la liste des événements que vous pouvez capturer dans votre vue :

événement description
nouislider:update Appelée quand la valeur du slider change. Retourne un tableau des valeurs (left et right) ainsi que le curseur qui bouge (si c’est celui de gauche ou droite).
nouislider:slide Appelée quand on fait bouger le slider
nouislider:set Appelée quand on modifie une valeur manuellement du slider via la méthode set()
nouislider:change Appelé quand la valeur du slide a changée
nouislider:start Appelée lors de la construction du slider
nouislider:end Appelée lors de la destruction du slider
nouislider:hover Appelé lors du survol de la souris. Passe en paramètre la valeur du slider à cet endroit.

Voici les fonctions accéssibles depuis le tag côté javascript :

fonction description
get Permet de récupérer la valeur du slider. Merci de voir la documentation de nouislider
set Permet de modifier la valeur du slider. Merci de voir la documentation de nouislider

Pending

Génère un bouton gérant un état de loading dans le style de Ladda-Button. Ce composant est utilisé pour mettre en attente l’utilisateur lors de la validation du formulaire, …

<btn-pending data-id="validate"></btn-pending>

this.mountTags({
    tag : 'btn-pending'
});
option description default
color Couleur du bouton d’après celles de materialoze-css green
type Type de bouton submit
data-id ID du bouton submit
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit validate

Voici les événements que vous pouvez lancer depuis le javascript gràce à la fonction trigger :

événement description
start Met le bouton dans l’état de loading. Dans ce cas le bouton est disabled et n’est plus clickable
stop Met le bouton dans son fonctionnement normal. Le bouton est clickable.

Rating

Génère un élément rating permettant de donner son avis entre une et x étoiles.

<rating></rating>

this.mountTags({
    tag : 'rating'
});
option description default
col Si renseigné, permet de définir la colonne associée au grid système -
data-id Identifiant de l’input -
data-name Nom de l’input -
value valeur renseignée de base -
num Nombre d’étoiles voulues 5
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit rating
no-label Si renseigné, l’input n’aura pas de label -
no-star-label Si renseigné, n’affiche pas le numéro des étoiles -

Voici la liste des événements que vous pouvez capturer dans votre vue :

événement description
change Appelée lorsque vous changez la valeur du rating. Retourne la nouvelle valeur

Survey

Génère un élément survey permettant de donner sune note de 1 à 10. 1 étant la pire note et 10 la mieux .

<survey></survey>

this.mountTags({
    tag : 'survey'
});
option description default
col Si renseigné, permet de définir la colonne associée au grid système -
data-id Identifiant de l’input -
data-name Nom de l’input -
value valeur renseignée de base -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit rating
no-label Si renseigné, l’input n’aura pas de label -

Voici la liste des événements que vous pouvez capturer dans votre vue :

événement description
change Appelée lorsque vous changez la valeur du rating. Retourne la nouvelle valeur

Lang Input

Génère plusieurs input en fonction des langues passées en paramètre. Ces input permettent de remplir un champ traduit au sein de votre projet.

Format du champ traduit

{
  "fr" : "Titre francais",
  "en" : "titre en"
}

<material-input-lang
    id="name"
    name="name"
    col="m6"
    ></material-input-lang>

this.mountTags({
    tag : 'material-input-lang',
    options : {
        langs : [ 'fr', 'en' ]
    }
});
option description default
col Si renseigné, permet de définir la colonne associée au grid système -
data-id Identifiant de l’input -
data-name Nom de l’input -
value valeur renseignée de base -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit name
disabled Si renseigné alors tous les input du composant sont désactivés. -
is-active Si renseigné, les label ont la classe active de renseigné. -

Lang Textarea

Génère plusieurs textarea en fonction des langues passées en paramètre. Ces textarea permettent de remplir un champ traduit au sein de votre projet.

Format du champ traduit

{
  "fr" : "Titre francais",
  "en" : "titre en"
}

<material-textarea-lang
    id="name"
    name="name"
    col="m6"
    ></material-textarea-lang>

this.mountTags({
    tag : 'material-textarea-lang',
    options : {
        langs : [ 'fr', 'en' ]
    }
});
option description default
col Si renseigné, permet de définir la colonne associée au grid système -
data-id Identifiant de l’input -
data-name Nom de l’input -
value valeur renseignée de base -
label libellé du label. Si le libellé est un code de traduction, il sera automatiquement traduit name
disabled Si renseigné alors tous les input du composant sont désactivés. -
is-active Si renseigné, les label ont la classe active de renseigné. -

Modals

Voici la collection de toutes les modals disponibles au sein de la library.

La plupart des modals sont des vues Backbone afin de simplifier la gestion des événements et la personnalisation de chacune d’elles.

Delete

Modale utilisée pour la suppression d’éléments. Vous pouvez choisir entre une suppression 1 et 2 facteurs. La suppression à 2 facteurs demandant de remplir un input avant suppression.

var deleteModal = require('backbone-goomeo/js/modules/common/modals/delete');

// ...
this.modal.open({
  view : this.createSubView('modal:delete', deleteModal, {
      hasDoubleVerif      : true,
      validateCallback    : function () {
          this.model.destroy();
          this.toasts.success({ message : 'Tâche supprimée avec succès.' });
          this.dispose();
      }.bind(this)
  })
});
// ...
parametre type description default
message String Message du dialog. Si le libellé est un code de traduction, il sera automatiquement traduit deleteMessage
title String Titre du dialog. Si le libellé est un code de traduction, il sera automatiquement traduit deleteTitle
accept String Texte du bouton de validation. Si le libellé est un code de traduction, il sera automatiquement traduit delete
cancel String Texte du bouton d’annulation. Si le libellé est un code de traduction, il sera automatiquement traduit cancel
icon String Classe d’îcone pour l’afficher à gauche du texte de la modal delete
labelDoubleVerif String Label utilisé sir la bouble vérification est activée deleteDoubleVerif
hasDoubleVerif Boolean True : Double vérification activée. Il y a un input avec KO. Pour que la modale soit confirmée il faut le remplacer par OK. false
validateCallback Function Fonction appelée lors de la confirmation de la modale -
cancelCallback Function Fonction appelée lors de l’annulation de la modale -

API - EventManager

L’eventManager est l’objet de centralisation de tous les événements globaux. Cette classe étend uniquement Backbone.Events.

API - ViewManager

Le view Manager est la classe utilisée pour gérer la création de nouvelles vues et la suppression des vues existantes.

create(name, view, [options])

Créer une nouvelle vue Backbone et l’ajoute à la collection des vues.

parametre description default
name Nom de la vue. Fait office d’ID et doit être unique -
view Vue Backbone non instanciée -
options Options à passer à la vue lors de l’instanciation. Ce sont ceux que vous retrouverez dans la fonction initialize -

get(name)

Récupère une vue à partir de son nom. Si la vue n’existe pas, retourne false

parametre description default
name le nom de la vue -

disposeAll([without])

Supprime toutes les vues sauf celles passées en paramètre

parametre description default
without Tableau de noms de vues à ne pas supprimer -

dispose(name)

upprime la vue passée en paramètre, ses événements ainsi que toutes ses sous-vues et leurs événements

parametre description default
name le nom de la vue -

exist(name)

Test si la vue passé en paramètre existe.

parametre description default
name le nom de la vue -

API - PanelManager

Le panel manager gère la gestion du panneau latéral servant à contenir un formulaire ou des informations complémentaires.

Ce pannel se situe du côté droite de l’écran et, selon la résulution de lécran et la taille désirée, vous pouvez avoir un panneau couvrant entre 30 et 100% de l’écran.

Tailles disponibles

Voici les classes disponibles ainsi que la taille qu’elles représentent :

classe taille
low 30%
medium 50%
low-high 70%
medium-high 80%
high 90%
max 100%

open(params)

Fonction appelée pour ouvrir un slidePannel

parametre description default
params Function params -
params.sizeClass Taille du panneau. Utilisez les classes notée au dessus medium
params.view Vue Backbone instanciée. N’est pas obligatoire -
params.html Contenu HTML à mettre dans le slidePanel. Se met à la place du param view -
params.closeOnClickOutside true : Le panel se ferme quand on clic en dehors. false

close

Ferme le slidePanel

API - ModalManager

le modalManager gère la création et la fermeture de toutes les modales crées au sein du projet.

open(params)

Permet de crér une modale à partir d’HTML ou d’une vue backbone.

Atention : Popur marcher en html vous devez avoir la structure totale d’une modal.
Pour les vue, la classe de votre vue doit être celle de base de la modal.

parametre description default
params.html code html de votre modal -
params.view Vue backbone instanciée -
params.options Options de la fonction modal fournie par materialize-css -

close(params)

parametre description default
params.name Nom de la vue backbone associée pour qu’elle soit détruite -
params.options Options de la fonction modal fournie par materialize-css -

API - TemplatesManager

Classe servant à compiler les templates et à récupérer directement ceux qui l’ont été.

compile(template)

Compile le template passé en paramètre et retourne la fonction généré par _.template().
Si le template passé a déjà été compilé, retourne directement le résultat de _.template stocké en mémoire.

parametre description default
template Contenu du template à compiler -

remove(template)

Supprime le template passé en paramètre de la mémoire du templateManager pour permettre une nouvelle compilation de zéro au prochain appel de compile()

parametre description default
template Contenu du template à supprimer -

API - View : Base

La vue Base permet de rajouter plusieurs fonctions à Backbone.JS parmis :

createSubView(name, view, options)

Permet de créer une sous vue et de la rattacher directement à cette vue-ci.

params type description default
name string Nom de la vue. Attention si le nom existe déjà, l’ancienne vue est supprimée -
view Backbone.View Vue Backbone non initialisée -
[options] object Options passées à la vue Backbone et que vous pouvez retrouver dans la fonction initialize -

template(template, params)

Permet de compiler un template en fonction des paramètres passés et retourne un string du template compilé.

params type description default
template string Template à compiler. -
params object Paramètres du template -

De base, les templates faits à partir d’ici ont les paramètres suivants :

dispose()

Supprime la vue et tout ce qui s’y rapporte en événements et en tags

mountTags(params)

Permet de monter des tags RIOT dans notre vue et de rattacher tous les événements renseignés

params type description default
params object Function params -
params.tag string nom du tag à monter -
[params.selector] string Selecteur CSS valide (ex : ‘div#monid > span’) -
[params.domNode] domNode Node DOM qui sera remplacée par le tag à charger -
[params.options] object Options du tag -

Retourne un tableau de tags Riot.

unmountAllTags()

Supprime tous les tags Riot de notre Vue

waitingRender(callback)

Fonction appelée avant beforeRender pour afficher du contenu pendant l’exécution de cette fonction (chargement, une emptyView, …). Fonction asynchrone. Pensez à appeler le callback à la fin de votre fonction

beforeRender(callback)

Fonction appelée juste avant l’appel de Render. Fonction asynchrone. Pensez à appeler le callback à la fin de votre fonction

render(callback)

Fonction appelée pour afficher le rendu final de votre vue. Fonction asynchrone. Pensez à appeler le callback à la fin de votre fonction

afterRender(callback)

Fonction appelée juste après l’appel de Render. Fonction asynchrone. Pensez à appeler le callback à la fin de votre fonction

prerequireAction()

Fonction appelée juste après Initialize et servant à charger des données externes (données de models, collections, …)

global

Objet permettant de gérer tous les événements globaux de votre vue. Cet objet est composé des mêmes fonctions que Backbone.Events.

panels

Objet permettant de manipuler le slidePanel au travers du PanelManager. Utilise les fonctions open et close.

Objet permettant de manipuler les modals au travers du ModalManager. Utilise les fonctions open et close.

toasts.show(params)

Permet d’afficher un élément Toast à partir des paramètres d’entrée.

params type description default
params object Function params -
params.message string ou jqueryObject Message du toast, l’HTML est accepté mais devra impérativement être un objet jQuery -
[params.duration] number Temps d’affichage du toast en milliseconde 3000
[params.style] string Classe de personnalisation pour le toast. De base seul la classe rounded est disponible mais vous pouvez créer les votres. -
[params.callback] function Fonction appelée après l’affichage du toast -

toasts.success(params)

Permet d’afficher un élément Toast à partir des paramètres d’entrée pour les messages de succès (avec l’icône à gauche)

params type description default
params object Function params -
params.message string Message du toast, l’HTML est accepté mais devra impérativement être un objet jQuery -
[params.duration] number Temps d’affichage du toast en milliseconde 3000
[params.style] string Classe de personnalisation pour le toast. De base seul la classe rounded est disponible mais vous pouvez créer les votres. -
[params.callback] function Fonction appelée après l’affichage du toast -

toasts.error(params)

Permet d’afficher un élément Toast à partir des paramètres d’entrée pour les messages d’erreur (avec l’icône à gauche)

params type description default
params object Function params -
params.message string Message du toast, l’HTML est accepté mais devra impérativement être un objet jQuery -
[params.duration] number Temps d’affichage du toast en milliseconde 3000
[params.style] string Classe de personnalisation pour le toast. De base seul la classe rounded est disponible mais vous pouvez créer les votres. -
[params.callback] function Fonction appelée après l’affichage du toast -

toasts.info(params)

Permet d’afficher un élément Toast à partir des paramètres d’entrée pour les messages d’information (avec l’icône à gauche)

params type description default
params object Function params -
params.message string Message du toast, l’HTML est accepté mais devra impérativement être un objet jQuery -
[params.duration] number Temps d’affichage du toast en milliseconde 3000
[params.style] string Classe de personnalisation pour le toast. De base seul la classe rounded est disponible mais vous pouvez créer les votres. -
[params.callback] function Fonction appelée après l’affichage du toast -

toasts.warn(params)

Permet d’afficher un élément Toast à partir des paramètres d’entrée pour les messages de warning (avec l’icône à gauche)

params type description default
params object Function params -
params.message string Message du toast, l’HTML est accepté mais devra impérativement être un objet jQuery -
[params.duration] number Temps d’affichage du toast en milliseconde 3000
[params.style] string Classe de personnalisation pour le toast. De base seul la classe rounded est disponible mais vous pouvez créer les votres. -
[params.callback] function Fonction appelée après l’affichage du toast -

getLogger()

Permet de récupérer le logger rattaché à la vue courante. à utiliser à la place et comme l’objet console.

API - Router

getLogger()

Permet de récupérer le logger rattaché au routeur courant. à utiliser à la place et comme l’objet console.

javascript html