Crea apps con AngularJS

Importante: Chrome dejará de admitir las Apps de Chrome en todas las plataformas. El navegador Chrome y Chrome Web Store seguirán admitiendo extensiones. Lee el anuncio y obtén más información para migrar la app.

Con esta guía, podrás comenzar a compilar Apps de Chrome con el framework de MVC AngularJS. Para ilustrar Angular en acción, haremos referencia a una app real compilada con el framework, Google Drive Uploader. El código fuente está disponible en GitHub.

Acerca de la aplicación

Google Drive Uploader permite a los usuarios ver e interactuar rápidamente con los archivos almacenados en su cuenta de Google Drive, además de subir archivos nuevos con las APIs de arrastrar y soltar HTML. Es un excelente ejemplo de cómo compilar una app que se comunica con una de las APIs de Google; en este caso, la API de Google Drive.

Nota: También puedes compilar apps que se comuniquen con APIs o servicios de terceros que estén habilitados para OAuth2. Consulta Autenticación de Cuentas que no son de Google.

Quien sube un video usa OAuth2 para acceder a los datos del usuario. La API de chrome.identity se encarga de recuperar un token OAuth para el usuario que accedió, por lo que nos encargamos de todo el trabajo. Una vez que tenemos un token de acceso de larga duración, las apps usan la API de Google Drive para acceder a los datos del usuario.

Funciones clave que usa esta app:

• Detección automática de AngularJS para CSP
• Renderiza una lista de archivos recuperados de la API de Google Drive
• API de HTML5 Filesystem para almacenar íconos de archivos sin conexión
• Arrastrar y soltar HTML5 para importar o subir nuevos archivos desde el escritorio
• XHR2 para cargar imágenes, multidominio
• API de chrome.identity para la autorización de OAuth
• Marcos sin Chrome para definir el aspecto de la barra de navegación de la app

Cómo crear el manifiesto

Todas las apps de Chrome requieren un archivo manifest.json que contenga la información que Chrome necesita para iniciar la app. El manifiesto contiene metadatos relevantes y enumera los permisos especiales que necesita la app.

Una versión reducida del manifiesto de quien sube el video tiene el siguiente aspecto:

{
  "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/"
  ]
}

Las secciones más importantes de este manifiesto son las secciones "oauth2" y "permissions".

En la sección “oauth2”, se definen los parámetros que OAuth2 requiere para hacer su magia. Para crear un "client_id", sigue las instrucciones en Obtén tu ID de cliente. Los “permisos” enumeran los permisos de autorización para los que el token de OAuth será válido (por ejemplo, las API a las que la aplicación desea acceder).

La sección "permisos" incluye las URLs a las que la app accederá a través de XHR2. Los prefijos de URL son necesarios para que Chrome sepa qué solicitudes multidominio permitir.

Crea la página del evento

Todas las apps de Chrome requieren una página o secuencia de comandos en segundo plano para iniciar la app y responder a los eventos del sistema.

En la secuencia de comandos background.js, Drive Uploader abre una ventana de 500 x 600 px en la página principal. También especifica una altura y un ancho mínimos para la ventana a fin de que el contenido no quede demasiado comprimido:

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 ventana se crea como una ventana sin bordes (marco: "none"). De forma predeterminada, las ventanas se renderizan con la barra predeterminada de cierre, expansión y minimización del SO:

Quien sube un video usa frame: 'none' para renderizar la ventana como una "cortinilla en blanco" y crea un botón de cierre personalizado en main.html:

Toda el área de navegación está envuelta en

(consulta la siguiente sección). Para ordenar un poco la app, el botón de cierre personalizado se oculta hasta que el usuario interactúe con esta área:

<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>

En app.js, este botón se conectó con window.close().

Cómo diseñar la app con Angular

Angular es un framework de MVC, por lo que debemos definir la app de manera que un modelo, una vista y un controlador queden fuera de ella de forma lógica. Afortunadamente, esto es trivial cuando se usa Angular.

La View es la más fácil, así que comencemos aquí.

Crea la vista

main.html es la "V" en MVC; donde definimos las plantillas HTML en las que se renderizarán los datos. En Angular, las plantillas son bloques simples de HTML con un poco de salsa especial.

En última instancia, queremos mostrar la lista de archivos del usuario. En este caso, una simple

tiene sentido. Los bits de Angular se destacan en negrita:

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

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

Dice exactamente como parece: sella un

• para cada documento de nuestro modelo de datos “documentos”. Cada elemento contiene un ícono de archivo, un vínculo para abrir el archivo en la Web y la fecha de la actualización más reciente.
  Nota: A fin de que la plantilla sea un código HTML válido, usamos atributos data-* para el iterador ngRepeat de Angular, pero no es necesario. Puedes escribir fácilmente el repetidor como <li ng-repeat="doc in docs">.

  A continuación, debemos indicarle a Angular qué controlador supervisará la renderización de esta plantilla. Para eso, usamos la directiva ngController para indicarle a DocsController que reine la plantilla:

  <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>
  

  Ten en cuenta que lo que no se ve aquí es que estamos conectando objetos de escucha de eventos o propiedades para la vinculación de datos. Angular está haciendo ese trabajo pesado por nosotros.

  El último paso es hacer que Angular ilumine nuestras plantillas. La manera típica de hacerlo es incluir la directiva ngApp hasta el final :

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

  Si lo deseas, también puedes limitar el alcance de la aplicación a una parte más pequeña de la página. Solo tenemos un controlador en esta app, pero si vamos a agregar más después, colocar ngApp en el elemento superior hace que toda la página esté lista para Angular.

  El producto final para main.html se ve más o menos de la siguiente manera:

  <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>
  

  Aclaraciones sobre la Política de Seguridad del Contenido

  A diferencia de muchos otros frameworks de JS MVC, la versión 1.1.0 de Angular no requiere modificaciones para funcionar dentro de una CSP estricta. ¡Funciona de inmediato!

  Sin embargo, si usas una versión anterior de Angular entre las versiones 1.0.1 y 1.1.0, deberás indicarle a Angular que se ejecute en un "modo de seguridad de contenido". Para ello, se debe incluir la directiva ngCsp junto con ngApp:

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

  Cómo controlar la autorización

  El modelo de datos no lo genera la app. En su lugar, se propaga desde una API externa (la API de Google Drive). Por lo tanto, se requiere un poco de trabajo para completar los datos de la app.

  Antes de realizar una solicitud a la API, debemos obtener un token de OAuth para la Cuenta de Google del usuario. Para ello, creamos un método a fin de unir la llamada a chrome.identity.getAuthToken() y almacenar la accessToken, que podemos volver a usar en llamadas futuras a la API de 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);
    }
  };
  

  Nota: Pasar la devolución de llamada opcional nos da la flexibilidad de saber cuándo está listo el token de OAuth.
  Nota: Para simplificar un poco la tarea, creamos una biblioteca, gdocs.js, que permite administrar las tareas de la API.

  Una vez que tengamos el token, será el momento de realizar solicitudes a la API de Drive y propagar el modelo.

  Controlador esqueleto

  El "modelo" de quien sube el video es un array simple (llamado "documentos") de objetos que se renderizarán

• en la plantilla:

  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();
    });
  
  }
  

  Ten en cuenta que se llama a gdocs.auth() como parte del constructor de DocsController. Cuando los sistemas internos de Angular crean el controlador, tenemos la seguridad de tener un token de OAuth nuevo esperando al usuario.

  Obteniendo datos

  Plantilla presentada. Control basado en el andamiaje. Hay un token de OAuth en mano. ¿Qué sigue?

  Es hora de definir el método del controlador principal, fetchDocs(). Es la carga de trabajo del controlador, responsable de solicitar los archivos del usuario y de archivar el array de documentos con datos de las respuestas de la 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() usa el servicio $http de Angular para recuperar el feed principal mediante XHR. El token de acceso de OAuth se incluye en el encabezado Authorization junto con otros encabezados y parámetros personalizados.

  successCallback procesa la respuesta de la API y crea un nuevo objeto de documento para cada entrada del feed.

  Si ejecutas fetchDocs() en este momento, todo funciona y aparecerá la lista de archivos:

  

  ¡Bravo!

  Espera...nos faltan esos íconos de archivos prolijos. ¿Para qué me sirve esto? Una verificación rápida de la consola muestra varios errores relacionados con la CSP:

  

  Esto se debe a que estamos tratando de establecer los íconos img.src en URLs externas, lo que infringe la CSP. Por ejemplo: https://ssl.gstatic.com/docs/doclist/images/icon_10_document_list.png. Para solucionar este problema, debemos incorporar estos recursos remotos de forma local en la app.

  Importa recursos de imagen remotos

  Para que la CSP deje de gritarnos, usamos XHR2 para “importar” los íconos de archivo como BLOB y, luego, configuramos img.src en un blob: URL creado por la app.

  Este es el successCallback actualizado con el código XHR agregado:

  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);
        }
      });
    });
  };
  

  Ahora que CSP está conforme de nuevo, obtenemos íconos de archivos atractivos:

  

  Permanecer sin conexión: almacenamiento en caché de recursos externos

  La optimización obvia que debe realizarse: no hacer cientos de solicitudes XHR por cada ícono de archivo en cada llamada a fetchDocs(). Verifica esto en la consola de Herramientas para desarrolladores presionando el botón “Actualizar” varias veces. Cada vez que se recuperan n imágenes:

  

  Modifiquemos successCallback para agregar una capa de almacenamiento en caché. Las adiciones se destacan en negrita:

  $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);
  };
  

  Ten en cuenta que, en la devolución de llamada webkitResolveLocalFileSystemURL(), llamamos a $scope.$apply() cuando se ve la última entrada. Normalmente, no es necesario llamar a $apply(). Angular detecta cambios en los modelos de datos de forma automática. Sin embargo, en nuestro caso, tenemos una capa adicional de devolución de llamada asíncrona que Angular no conoce. Debemos indicarle explícitamente a Angular cuándo se actualizó nuestro modelo.

  En la primera ejecución, los íconos no estarán en el sistema de archivos HTML5 y las llamadas a window.webkitResolveLocalFileSystemURL() generarán la devolución de llamada de error. En ese caso, podemos volver a usar la técnica anterior y recuperar las imágenes. Esta vez, la única diferencia es que cada BLOB se escribe en el sistema de archivos (consulta writeFile()). La consola verifica este comportamiento:

  

  Después de la próxima ejecución (o presionar el botón "Actualizar"), la URL que se pasa a webkitResolveLocalFileSystemURL() existe porque el archivo se almacenó en caché con anterioridad. La app establece la doc.icon en el filesystem: URL del archivo y evita que la XHR costosa para el ícono sea costosa.

  Carga de arrastrar y soltar

  Una app para subir videos se considera publicidad falsa si no puede subir archivos.

  app.js controla esta función mediante la implementación de una pequeña biblioteca en torno a la función arrastrar y soltar de HTML5 llamada DnDFileController. Permite arrastrar archivos desde el escritorio y subirlos a Google Drive.

  Agregar esto al servicio gdocs hace el trabajo:

  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;
  });