I. Préparation

Avant de commencer ce tutoriel, vous aurez besoin de ce qui suit :

Pour consulter la source, exécutez les commandes suivantes (ou utilisez un outil approprié pour Git GUI) :

 
Sélectionnez
git clone git@github.com:alexyoung/dailyjs-backbone-tutorial.git
cd dailyjs-backbone-tutorial
git reset --hard c1d5a2e7cc

II. L'API Google Tasks

En résumé : le but de cette série de tutoriels est de créer une application Backbone.js monopage qui utilise le JavaScript côté client pour communiquer avec les API Google d'authentification et de liste des tâches.

Google donne accès à nos listes de tâches par le biais de deux API :

Lors du chargement du JavaScript de Google, le navigateur reçoit un accès global à divers objets et méthodes. Dans le tutoriel précédent, j'ai inclus un appel à gapi.client.load qui charge l'API des tâches :

 
Sélectionnez
gapi.client.load('tasks', 'v1', function() { /* Loaded */ };

Cela se trouve dans app/js/gapi.js. Le défi avant de générer l'interface consiste à mettre en œuvre une nouvelle méthode Backbone.sync qui utilise gapi pour communiquer avec les API Tasks et Tasklists.

III. Structure de Backbone.sync

J'ai déjà parlé de la structure globale du Backbone.sync dans la partie 2Tutoriel Backbone.js : les APIs Google et RequireJS. Le modèle que j'utiliserai dans ce tutoriel est assez générique, donc vous pouvez utiliser la même approche pour communiquer avec autre chose que l'API de Google.

La méthode sync elle-même prend trois arguments, le premier d'entre eux est la method (créer, mettre à jour, supprimer et lire). Nous avons besoin de lier la méthode à quelque chose que les API de Google comprennent.

Voici ce que nous avons jusqu'à présent :

 
Sélectionnez
Backbone.sync = function(method, model, options) {
  options || (options = {};

  switch (method) {
    case 'create' :
    break ;

    case 'update' :
    break ;

    case 'delete' :
    break ;

    case 'read' :
    break ;
  }
} ;

Et ici nous avons les correspondances entre l'API Google et les méthodes Backbone :

 
Sélectionnez
API Google Tasks | Méthode Backbone.sync | Description
------------------------------------------------------
    insert       |         create        | Créer une nouvelle tâche.
    update       |         update        | Mettre à jour une tâche existante.
    delete       |         delete        | Supprimer une tâche.
     list        |          read         | Obtenir une liste de tâches.

Même si l'API de Google ne ressemble pas à l'API RESTful 3 Rails conçue par Backbone.js, il y a des similitudes.

IV. Faire des requêtes avec gapi

L'objet gapi fait des requêtes à l'aide de ce modèle :

  • appeler l'une des méthodes gapi.client.tasks avec le contenu de la requête pour obtenir un objet request ;
  • appeler request.execute avec un callback pour envoyer la requête ;
  • le callback reçoit un objet response, tout comme une requête Ajax standard.

Voici à quoi ça ressemble en réalité :

 
Sélectionnez
var requestContent = {}
  , request
  , gapiResource ;

gapiResource = 'tasks' ;
requestContent['tasklist'] = tasklistId ; // En supposant que nous en avons un
requestContent['resource'] = model.toJSON() ;

// 'insert' pour créer une nouvelle tâche
request = gapi.client.tasks[gapiResource].insert(requestContent) ;

// Envoyer la requête à l'API
request.execute(function(res) {
  // Gérer la réponse
};

En regardant cela, il est clair que nous avons besoin de deux modèles : Task et TaskList. Il faut également deux collections correspondantes : Task et TaskList.

Les modèles et les collections Backbone ont des URL qui sont utilisées pour faire des requêtes vers l'API. De même, les API Google ont des URL : task et tasklist. En utilisant le modèle d'URL Backbone.sync peut déterminer quelle ressource de l'API est requise pour une requête donnée.

V. Les modèles

Créez un nouveau répertoire appelé app/js/models et ajoutez le fichier task.js :

 
Sélectionnez
define(function() {
  var Task = Backbone.Model.extend({
    url: 'tasks'
  });

  return Task ;
};

Créez également le fichier app/js/models/tasklist.js :

 
Sélectionnez
define(function() {
  var TaskList = Backbone.Model.extend({
    url: 'tasklists'
  });

  return TaskList ;
};

VI. Les collections

Créez un nouveau répertoire nommé app/js/collections et ajoutez le fichier tasklists.js :

 
Sélectionnez
define(['models/tasklist'], function(TaskList) {
  var TaskLists = Backbone.Collection.extend({
    model: TaskList
  , url: 'tasklists'
  });

  return TaskLists ;
};

Nous allons utiliser la collection TaskList par la suite pour charger vos listes de tâches.

VII. Faire des requêtes vers l'API

Ouvrez le fichier app/js/gapi.js et ajoutez une nouvelle ligne après la ligne 36 :

 
Sélectionnez
app.views.auth.$el.hide() ;
$('#signed-in-container').show() ;
self.trigger('ready';

Cet événement ready sert pour signifier que l'authentification a réussi et que l'API Tasks est prête à l'emploi. Ensuite, ajoutez les deux lignes suivantes à Backbone.sync, à l'intérieur du cas du read dans le switch :

 
Sélectionnez
case 'read':
  var request = gapi.client.tasks[model.url].list(options.data) ;
  Backbone.gapiRequest(request, method, model, options);
break ;

Ce code crée une demande et donc Backbone.gapiRequest va s'exécuter et déléguer la réponse.

Voici l'implémentation la plus basique de Backbone.gapiRequest :

 
Sélectionnez
Backbone.gapiRequest = function(request, method, model, options) {
  var result;
  request.execute(function(res) {
    if (res.error) {
      if (options.error) options.error(res) ;
    } else if (options.success) {
      result = res.items ;
      options.success(result, true, request) ;
    }
  };
} ;

Tout ce qu'elle fait est d'exécuter request.execute qui est fourni par Google et de lier ensuite le résultat pour être compatible avec l'API Backbone en exécutant les callback success et error.

Juste pour vous indiquer que quelque chose se passe réellement, ouvrez app/js/app.js et faites-lui charger la collection TaskLists en changeant le define appelé au début :

 
Sélectionnez
define([
  'gapi'
, 'views/app'
, 'views/auth'
, 'collections/tasklists'
],

function(ApiManager, AppView, AuthView, TaskLists) {

Maintenant, ajoutez ceci à la méthode connectGapi :

 
Sélectionnez
this.apiManager.on('ready', function() {
  self.collections.lists.fetch({ data : { userId: '@me' }, success : function(res) {
    _.each(res.models, function(model) {
      console.log(model.get('title'));
    };
  }});
};

Ce code utilise la méthode each de Underscore pour effectuer une itération sur chaque « modèle » retourné par Backbone.sync qui est appelée par la collection TaskList.

Lancez le serveur avec npm start et visitez la page http://localhost:8080. Si vous l'exécutez dans un navigateur qui prend en charge la console, vous devriez voir vos listes de tâches.

Image non disponible

Si cela fonctionne alors, vous n'êtes pas loin de la création d'une application Backbone.js qui communique avec une API Google. Les mêmes concepts peuvent être appliqués aux autres API JavaScript de Google.

VIII. Résumé

Le code source de ce tutoriel se trouve ici : alexyoung / dailyjs-backbone-tutorial en version fcd653ec6.

IX. Remerciements

Cet article a été publié avec l'aimable autorisation de Alex Young. L'article original peut être lu sur le site DailyJSDailyJS : Backbone.js Tutorial: Backbone.syncBackbone.js Tutorial: Backbone.sync.
Je remercie également ClaudeLELOUP pour sa relecture attentive et assidue.