Créer des applications avec AngularJS

Important:Chrome ne prendra plus en charge les applications Chrome sur toutes les plates-formes. Le navigateur Chrome et le Chrome Web Store continueront de prendre en charge les extensions. Lisez l'annonce et découvrez comment migrer votre application.

Ce guide vous aide à créer des applications Chrome avec le framework MVC AngularJS. Pour illustrer le fonctionnement d'Angular, nous ferons référence à une application réelle créée à l'aide de ce framework : Google Drive Uploader. Le code source est disponible sur GitHub.

À propos de l'application

Le programme de transfert Google Drive permet aux utilisateurs d'afficher rapidement les fichiers stockés dans leur compte Google Drive et d'interagir avec eux. Il permet également d'importer de nouveaux fichiers à l'aide des API HTML de glisser-déposer. Il s'agit d'un excellent exemple de création d'une application qui communique avec l'une des API Google. Dans le cas présent, l'API Google Drive.

Remarque:Vous pouvez également créer des applications qui communiquent avec des API/services tiers compatibles avec OAuth2. Consultez Authentification des comptes autres que Google.

L'utilisateur ayant mis en ligne la vidéo utilise OAuth2 pour accéder aux données de l'utilisateur. L'API chrome.identity gère la récupération d'un jeton OAuth pour l'utilisateur connecté, ce qui nous a permis de faire le gros du travail ! Une fois que nous disposons d'un jeton d'accès de longue durée, les applications accèdent aux données de l'utilisateur via l'API Google Drive.

Principales fonctionnalités utilisées par cette application:

• Détection automatique d'AngularJS pour CSP
• Afficher une liste de fichiers récupérés à partir de l'API Google Drive
• API HTML5 Filesystem pour stocker les icônes de fichiers hors connexion
• Glisser-déposer HTML5 pour importer/importer de nouveaux fichiers à partir du bureau
• XHR2 pour charger des images, interdomaines
• API chrome.identity pour l'autorisation OAuth
• Cadres Chromeless pour définir l'apparence de la barre de navigation de l'application

Créer le fichier manifeste

Toutes les applications Chrome nécessitent un fichier manifest.json contenant les informations dont Chrome a besoin pour lancer l'application. Le fichier manifeste contient les métadonnées pertinentes et répertorie les autorisations spéciales nécessaires à l'exécution de l'application.

Une version simplifiée du fichier manifeste de l'utilisateur ayant mis en ligne la vidéo se présente comme suit:

{
  "name": "Google Drive Uploader",
  "version": "0.0.1",
  "manifest_version": 2,
  "oauth2": {
    "client_id": "665859454684.apps.googleusercontent.com",
    "scopes": [
      "https://www.googleapis.com/auth/drive"
    ]
  },
 ...
  "permissions": [
    "https://docs.google.com/feeds/",
    "https://docs.googleusercontent.com/",
    "https://spreadsheets.google.com/feeds/",
    "https://ssl.gstatic.com/",
    "https://www.googleapis.com/"
  ]
}

Les parties les plus importantes de ce fichier manifeste sont les sections "oauth2" et "permissions".

La section "oauth2" définit les paramètres requis par OAuth2 pour faire ce qu'il faut. Pour créer un "client_id", suivez les instructions de la section Obtenir votre ID client. La section "Champs d'application" liste les champs d'application d'autorisation pour lesquels le jeton OAuth sera valide (par exemple, les API auxquelles l'application souhaite accéder).

La section "Autorisations" inclut les URL auxquelles l'application accède via XHR2. Ces préfixes sont nécessaires pour que Chrome puisse identifier les requêtes interdomaines à autoriser.

Créer la page de l'événement

Toutes les applications Chrome ont besoin d'une page ou d'un script en arrière-plan pour les lancer et répondre aux événements système.

Dans son script background.js, l'outil Drive Uploader ouvre une fenêtre de 500 x 600 pixels vers la page principale. Il spécifie également une hauteur et une largeur minimales pour la fenêtre afin que le contenu ne soit pas trop tronqué:

chrome.app.runtime.onLaunched.addListener(function(launchData) {
  chrome.app.window.create('../main.html', {
    id: "GDriveExample",
    bounds: {
      width: 500,
      height: 600
    },
    minWidth: 500,
    minHeight: 600,
    frame: 'none'
  });
});

La fenêtre est créée sous la forme d'une fenêtre Chromeless (cadre: "none"). Par défaut, les fenêtres s'affichent avec la barre de fermeture, de développement et de réduction par défaut du système d'exploitation:

L'outil de mise en ligne utilise frame: 'none' pour afficher la fenêtre sous la forme d'un écran blanc et crée un bouton de fermeture personnalisé dans main.html:

L'intégralité de la zone de navigation est délimitée

(voir la section suivante). Pour désencombrer l'application, le bouton de fermeture personnalisé est masqué jusqu'à ce que l'utilisateur interagisse avec cette zone:

<style>
nav:hover #close-button {
  opacity: 1;
}

#close-button {
  float: right;
  padding: 0 5px 2px 5px;
  font-weight: bold;
  opacity: 0;
  transition: all 0.3s ease-in-out;
}
</style>

<button class="btn" id="close-button" title="Close">x</button>

Dans app.js, ce bouton est associé à window.close().

Concevoir l'application en mode Angular

Angular est un framework MVC. Nous devons donc définir l'application de manière à ce qu'un modèle, une vue et un contrôleur en sortent logiquement. Heureusement, cela est simple lorsque vous utilisez Angular.

La vue est l'option la plus simple, alors commençons par là.

Créer la vue

Dans MVC, le fichier main.html correspond au "V" dans lequel nous définissons les modèles HTML dans lesquels les données seront affichées. Dans Angular, les modèles sont de simples blocs de code HTML qui ont une certaine particularité.

En fin de compte, nous voulons afficher la liste des fichiers de l'utilisateur. À cet effet, un simple

est pertinente. Les bits angulaires sont mis en évidence en gras:

<ul>
  <li data-ng-repeat="doc in docs">
    <img data-ng-src=""> <a href=""></a>

    <span class="date"></span>
  </li>
</ul>

Il se lit exactement comme il semble: ajouter une

• pour chaque document de notre modèle de données "docs". Chaque élément contient une icône de fichier, un lien pour ouvrir le fichier sur le Web et la date de dernière mise à jour.
  Remarque:Pour que le modèle HTML soit valide, nous utilisons des attributs data-* pour l'itérateur ngRepeat d'Angular, mais ce n'est pas obligatoire. Vous pouvez facilement écrire le répéteur comme <li ng-repeat="doc in docs">.

  Nous devons ensuite indiquer à Angular quel contrôleur supervisera le rendu de ce modèle. Pour ce faire, nous utilisons la directive ngController pour indiquer à DocsController de contrôler le modèle :

  <body data-ng-controller="DocsController">
  <section id="main">
    <ul>
      <li data-ng-repeat="doc in docs">
        <img data-ng-src=""> <a href=""></a> 
        <span class="date"></span>
      </li>
    </ul>
  </section>
  </body>
  

  Gardez à l'esprit que nous ne voyons pas ici les écouteurs ou propriétés d'événements pour la liaison de données. Angular fait le gros du travail pour nous !

  La dernière étape consiste à demander à Angular d'éclairer nos modèles. Généralement, pour ce faire, vous devez inclure l'instruction ngApp jusqu'au niveau suivant :

  <html data-ng-app="gDriveApp">
  

  Si vous le souhaitez, vous pouvez également limiter l'application à une plus petite partie de la page. Cette application ne contient qu'un seul contrôleur. Toutefois, si nous devons en ajouter d'autres par la suite, placer ngApp au niveau de l'élément le plus haut pour que la page entière soit prête pour Angular.

  Le produit final pour main.html se présente comme suit:

  <html data-ng-app="gDriveApp">
  <head>
    …
  
    <base target="_blank">
  </head>
  <body data-ng-controller="DocsController">
  <section id="main">
    <nav>
      <h2>Google Drive Uploader</h2>
      <button class="btn" data-ng-click="fetchDocs()">Refresh</button>
      <button class="btn" id="close-button" title="Close"></button>
    </nav>
    <ul>
      <li data-ng-repeat="doc in docs">
        <img data-ng-src=""> <a href=""></a>  
        <span class="date"></span>
      </li>
    </ul>
  </section>
  

  Remarque sur Content Security Policy

  Contrairement à de nombreux autres frameworks MVC JS, Angular v1.1.0+ ne nécessite aucun ajustement pour fonctionner dans un CSP strict. Il fonctionne sans configuration particulière.

  Toutefois, si vous utilisez une ancienne version d'Angular entre les versions 1.0.1 et 1.1.0, vous devez indiquer à Angular de s'exécuter en "mode Content Security". Pour ce faire, incluez la directive ngCsp à côté de ngApp:

  <html data-ng-app data-ng-csp>
  

  Gérer les autorisations

  Le modèle de données n'est pas généré par l'application elle-même. Au lieu de cela, il est renseigné à partir d'une API externe (l'API Google Drive). Ainsi, un peu de travail est nécessaire pour renseigner les données de l'application.

  Avant de pouvoir envoyer une requête API, nous devons récupérer un jeton OAuth pour le compte Google de l'utilisateur. Pour ce faire, nous avons créé une méthode permettant d'encapsuler l'appel à chrome.identity.getAuthToken() et de stocker le accessToken, que nous pouvons réutiliser pour de futurs appels à l'API Drive.

  GDocs.prototype.auth = function(opt_callback) {
    try {
      chrome.identity.getAuthToken({interactive: false}, function(token) {
        if (token) {
          this.accessToken = token;
          opt_callback && opt_callback();
        }
      }.bind(this));
    } catch(e) {
      console.log(e);
    }
  };
  

  Remarque:La transmission du rappel facultatif nous permet de savoir quand le jeton OAuth est prêt.
  Remarque:Pour simplifier un peu, nous avons créé une bibliothèque, gdocs.js, pour gérer les tâches de l'API.

  Une fois que nous avons le jeton, vous pouvez envoyer des requêtes à l'API Drive et remplir le modèle.

  Contrôleur de squelette

  Le "modèle" du programme de téléchargement est un simple tableau (appelé "documents") d'objets qui seront affichés sous la forme

• dans le modèle:

  var gDriveApp = angular.module('gDriveApp', []);
  
  gDriveApp.factory('gdocs', function() {
    var gdocs = new GDocs();
    return gdocs;
  });
  
  function DocsController($scope, $http, gdocs) {
    $scope.docs = [];
  
    $scope.fetchDocs = function() {
       ...
    };
  
    // Invoke on ctor call. Fetch docs after we have the oauth token.
    gdocs.auth(function() {
      $scope.fetchDocs();
    });
  
  }
  

  Notez que gdocs.auth() est appelé dans le constructeur DocsController. Lorsque les équipes internes d'Angular créent le contrôleur, nous sommes assurés de disposer d'un nouveau jeton OAuth en attente de l'utilisateur.

  Récupération des données en cours

  Modèle présenté. Contrôleur dans un échafaudage Jeton OAuth en main. Il est temps d'agir !

  Il est temps de définir la méthode principale du contrôleur, fetchDocs(). Il s'agit de l'outil de travail du contrôleur, chargé de demander les fichiers de l'utilisateur et de remplir le tableau de documents avec les données provenant des réponses de l'API.

  $scope.fetchDocs = function() {
    $scope.docs = []; // First, clear out any old results
  
    // Response handler that doesn't cache file icons.
    var successCallback = function(resp, status, headers, config) {
      var docs = [];
      var totalEntries = resp.feed.entry.length;
  
      resp.feed.entry.forEach(function(entry, i) {
        var doc = {
          title: entry.title.$t,
          updatedDate: Util.formatDate(entry.updated.$t),
          updatedDateFull: entry.updated.$t,
          icon: gdocs.getLink(entry.link,
                              'http://schemas.google.com/docs/2007#icon').href,
          alternateLink: gdocs.getLink(entry.link, 'alternate').href,
          size: entry.docs$size ? '( ' + entry.docs$size.$t + ' bytes)' : null
        };
  
        $scope.docs.push(doc);
  
        // Only sort when last entry is seen.
        if (totalEntries - 1 == i) {
          $scope.docs.sort(Util.sortByDate);
        }
      });
    };
  
    var config = {
      params: {'alt': 'json'},
      headers: {
        'Authorization': 'Bearer ' + gdocs.accessToken,
        'GData-Version': '3.0'
      }
    };
  
    $http.get(gdocs.DOCLIST_FEED, config).success(successCallback);
  };
  

  fetchDocs() utilise le service $http d'Angular pour récupérer le flux principal via XHR. Le jeton d'accès OAuth est inclus dans l'en-tête Authorization avec d'autres en-têtes et paramètres personnalisés.

  successCallback traite la réponse de l'API et crée un objet doc pour chaque entrée du flux.

  Si vous exécutez fetchDocs() maintenant, tout fonctionne correctement et la liste des fichiers s'affiche:

  

  Bravo !

  Attends, il nous manque ces super icônes de fichiers. What gives? Une analyse rapide de la console montre de nombreuses erreurs liées à CSP:

  

  La raison est que nous essayons de définir les icônes img.src sur des URL externes, ce qui n'est pas conforme à CSP. Exemple : https://ssl.gstatic.com/docs/doclist/images/icon_10_document_list.png. Pour résoudre ce problème, nous devons importer ces éléments distants localement vers l'application.

  Importer des éléments d'image distants

  Pour que CSP cesse de nous crier dessus, nous utilisons XHR2 pour "importer" les icônes de fichier en tant que blobs, puis définir le img.src sur un blob: URL créé par l'application.

  Voici le successCallback mis à jour avec le code XHR ajouté:

  var successCallback = function(resp, status, headers, config) {
    var docs = [];
    var totalEntries = resp.feed.entry.length;
  
    resp.feed.entry.forEach(function(entry, i) {
      var doc = {
        ...
      };
  
      $http.get(doc.icon, {responseType: 'blob'}).success(function(blob) {
        console.log('Fetched icon via XHR');
  
        blob.name = doc.iconFilename; // Add icon filename to blob.
  
        writeFile(blob); // Write is async, but that's ok.
  
        doc.icon = window.URL.createObjectURL(blob);
  
        $scope.docs.push(doc);
  
        // Only sort when last entry is seen.
        if (totalEntries - 1 == i) {
          $scope.docs.sort(Util.sortByDate);
        }
      });
    });
  };
  

  Maintenant que CSP est de nouveau satisfait, nous obtenons de belles icônes de fichier:

  

  Déconnexion: mise en cache des ressources externes

  L'optimisation évidente à effectuer: n'effectuez pas des centaines de requêtes XHR pour chaque icône de fichier à chaque appel de fetchDocs(). Vérifiez cela dans la console des outils pour les développeurs en appuyant plusieurs fois sur le bouton "Actualiser". Chaque fois, n images sont extraites:

  

  Modifions successCallback pour ajouter une couche de mise en cache. Les ajouts sont mis en évidence en gras:

  $scope.fetchDocs = function() {
    ...
  
    // Response handler that caches file icons in the filesystem API.
    var successCallbackWithFsCaching = function(resp, status, headers, config) {
      var docs = [];
      var totalEntries = resp.feed.entry.length;
  
      resp.feed.entry.forEach(function(entry, i) {
        var doc = {
          ...
        };
  
        // 'https://ssl.gstatic.com/doc_icon_128.png' -> 'doc_icon_128.png'
        doc.iconFilename = doc.icon.substring(doc.icon.lastIndexOf('/') + 1);
  
        // If file exists, it we'll get back a FileEntry for the filesystem URL.
        // Otherwise, the error callback will fire and we need to XHR it in and
        // write it to the FS.
        var fsURL = fs.root.toURL() + FOLDERNAME + '/' + doc.iconFilename;
        window.webkitResolveLocalFileSystemURL(fsURL, function(entry) {
          doc.icon = entry.toURL(); // should be === to fsURL, but whatevs.
  
          $scope.docs.push(doc); // add doc to model.
  
          // Only want to sort and call $apply() when we have all entries.
          if (totalEntries - 1 == i) {
            $scope.docs.sort(Util.sortByDate);
            $scope.$apply(function($scope) {}); // Inform angular that we made changes.
          }
  
        }, function(e) {
          // Error: file doesn't exist yet. XHR it in and write it to the FS.
  
          $http.get(doc.icon, {responseType: 'blob'}).success(function(blob) {
            console.log('Fetched icon via XHR');
  
            blob.name = doc.iconFilename; // Add icon filename to blob.
  
            writeFile(blob); // Write is async, but that's ok.
  
            doc.icon = window.URL.createObjectURL(blob);
  
            $scope.docs.push(doc);
  
            // Only sort when last entry is seen.
            if (totalEntries - 1 == i) {
              $scope.docs.sort(Util.sortByDate);
            }
          });
  
        });
      });
    };
  
    var config = {
      ...
    };
  
    $http.get(gdocs.DOCLIST_FEED, config).success(successCallbackWithFsCaching);
  };
  

  Notez que dans le rappel webkitResolveLocalFileSystemURL(), nous appelons $scope.$apply() lorsque la dernière entrée est visible. Normalement, il n'est pas nécessaire d'appeler $apply(). Angular détecte automatiquement les modifications apportées aux modèles de données. Toutefois, dans notre cas, nous disposons d'une couche supplémentaire de rappel asynchrone dont Angular n'a pas connaissance. Nous devons explicitement indiquer à Angular lorsque notre modèle a été mis à jour.

  À la première exécution, les icônes ne se trouveront pas dans le système de fichiers HTML5, et les appels à window.webkitResolveLocalFileSystemURL() entraînent l'appel de son rappel d'erreur. Dans ce cas, nous pouvons réutiliser la technique précédente et récupérer les images. Cette fois-ci, la seule différence réside dans le fait que chaque blob est écrit dans le système de fichiers (voir writeFile()). La console vérifie ce comportement:

  

  Lors de la prochaine exécution (ou en appuyant sur le bouton "Actualiser"), l'URL transmise à webkitResolveLocalFileSystemURL() existe, car le fichier a déjà été mis en cache. L'application définit doc.icon sur le filesystem: URL du fichier et évite d'effectuer le coût XHR coûteux pour l'icône.

  Importation par glisser-déposer

  Une application d'importation constitue de fausses publicités si elle ne permet pas d'importer des fichiers.

  Pour gérer cette fonctionnalité, app.js implémente une petite bibliothèque appelée DnDFileController autour du glisser-déposer HTML5. Elle permet de faire glisser des fichiers depuis le bureau et de les importer dans Google Drive.

  Il suffit de l'ajouter au service gdocs pour effectuer cette tâche:

  gDriveApp.factory('gdocs', function() {
    var gdocs = new GDocs();
  
    var dnd = new DnDFileController('body', function(files) {
      var $scope = angular.element(this).scope();
      Util.toArray(files).forEach(function(file, i) {
        gdocs.upload(file, function() {
          $scope.fetchDocs();
        });
      });
    });
  
    return gdocs;
  });