Diplomado Internacional de Desarrollo e Implementacin de Aplicaciones utilizando el Cloud de Google

Curso Google Apps- Script

VERSIN 1.0 Material elaborado para uso exclusivo de los alumnos de la USMP Virtual

ndice
Mdulo I: Programando en Google Apps Script Introduccin
1.1 1.1.1 1.1.2 1.1.3 1.1.4 1.1.5 1.1.6 1.1.7 1.2 1.2.1 1.2.2 1.2.3 1.2.4 1.2.5 1.2.6 1.2.7 1.2.8 1.3 Enfoque terico Definicin... Caractersticas.. Publico objetivo Funcionalidad Requerimientos para comenzar con Apps Script Interaccin con otras aplicaciones de Google.. Otros servicios. Gua de usuario. Reconocimiento de entornos de ejecucin. Desarrollo de Scripts.. Programacin de tareas comunes.. Eventos.. Gui interfaz grfica de usuario... Gui Builder Modelo de Seguridad.. Solucin de problemas y depuracin de Scripts. Aplicacin de Apps Script.. 1 1 2 2 3 5 5 6 7 7 18 29 34 37 49 51 55 57

Mdulo I Programando en Google Apps Script Introduccin

1.1 Enfoque Terico
1.1.1 Definicin Google Apps Script es un lenguaje de programacin JavaScript basado en nube, que ofrece maneras fciles de automatizar las tareas y procesos en las organizaciones, complementando los productos de Google y servicios de terceros. Dicha secuencia de comando permite crear scripts (pequeos programas) para realizar mltiples funciones y expandir la integracin con Google Apps. Permite a los usuarios tener un nivel de control sobre los productos de Google, mediante secuencias de comandos JavaScript que se puede escribir y compartir. A diferencia de navegador basado en JavaScript, los guiones que escribe se ejecutan directamente en los servidores de Google con el fin de proporcionar acceso directo a los productos bajo su control. Qu es un script Un script es una serie de instrucciones que se escribe en un lenguaje de programacin para realizar una tarea determinada. El guion solo se ejecuta bajo las circunstancias que usted defina. La secuencia de comandos de la API de Google Apps ofrece un conjunto de objetos. Puede utilizar estos objetos y sus mtodos asociados para acceder a Google Docs y hojas de clculo, Gmail, Google Finance, y otras aplicaciones de Google. Usted podr leer ms acerca de los objetos y mtodos de uso de la API de Google Apps de secuencias de comandos. Para ejecutar un script, primero debe agregar el guion de una hoja de clculo de Google o Google Site utilizando el Editor de Script. Usted puede agregar secuencias de comandos como quiera de una hoja de clculo en particular como desee, y luego ejecutar de acuerdo a su criterio e inters. Las secuencias de comandos, normalmente, se ejecutarn con los datos en la hoja de clculo, pero no se limitan al uso de datos en la hoja de clculo. Puede recuperar informacin de una amplia gama de aplicaciones y servicios de Google como de fuentes externas, incluyendo las pginas web y las fuentes XML.

Google Apps Script

Google Apps Script proporciona una robusta API (Interfaz de Programacin de Aplicaciones) de los objetos y mtodos que se utilizan en las secuencias de comandos para tareas, tales como la visualizacin de un cuadro de dilogo, la creacin de una agenda de eventos, la creacin de una pgina en un Google Site, y muchas otras actividades. 1.1.2 Caractersticas Capacidad para automatizar los procesos repetitivos de negocios (por ejemplo, las aprobaciones de gastos, seguimiento del tiempo de la hoja, la gestin de entradas, preparacin de pedidos, y mucho ms). Enlace con los productos de Google y servicios de terceros (por ejemplo, enviar correos electrnicos personalizados y una invitacin de calendario a una lista de una base de datos MySQL) Crear funciones personalizadas de hoja de clculo. Construir y recoger las entradas del usuario a travs de interfaces grficas y mens (por ejemplo, una empresa podra alimentar una aplicacin interna para la compra de suministros de oficina, donde los usuarios pueden comprar a travs de una interfaz de men personalizado) Creacin y ejecucin de comandos JavaScript en los servidores de Google para realizar procedimientos como: Personalizar una hoja de clculo con los botones o los mens. Crear un presupuesto. Seguimiento de precios de las acciones en el tiempo. Seguimiento de los pagos de cuotas de un club. Manipular los datos en formato XML. Creacin de pginas en un Google Site. Enviar correo electrnico basado en la informacin en una hoja de clculo. Puede manipular cualquier tipo de datos con un script, incluidos los financieros numricos, y la cadena (de texto), y datos representados como un documento XML.

1.1.3 Pblico objetivo a) No Programadores Se dispone de informacin detallada, paseos virtuales de fragmentos de cdigo y muchos programas cortos en versin libre. Usted encontrar el aprendizaje de secuencias de comandos de Google Apps Script, de modo ms sencillo, si est familiarizado con las macros de hojas de clculo y las frmulas, estructuras de programacin como los bucles, sentencias condicionales y sentencias switch. Teniendo estas premisas que no son nada complejas, se podr entender con facilidad los recursos y programas ya realizados que pueden ser implementados por el usuario realizando manipulacin de datos.
Google Apps Script 2

Si desea obtener ms informacin acerca de JavaScript, podr disponer de muchos libros impresos y tutoriales difundidos en la Web. Por ejemplo, el tutorial en <http://www.w3schools.com/js/default.asp> est escrito teniendo como pblico objetivo, principiantes en JavaScript.

b) Programadores Si usted tiene conocimientos de algn JavaScript y/o lenguaje de programacin orientado a objetos, se podr adaptar fcilmente y sus ideas fluirn naturalmente. Para ello, se sugiere tener en cuenta leer los apartados de eventos, interfaces de usuario, seguridad y solucin de problemas, que son temas contemplados en el presente documento. Asimismo, se sugiere revisar el apartado del API de servicios Google Apps Script que proporciona los objetos y mtodos que estn integradas en Google Apps Script.

1.1.4 Funcionalidad Google Apps Script se puede ejecutar tanto en entornos como:

Google Docs La interaccin dentro de Google Docs hace referencia al uso de la secuencia de comandos Apps Script para hojas de clculo (Spreadsheets). Si estamos familiarizados como se mencionada anteriormente con macros y funciones de hojas de clculo, podremos realizar personalizaciones con mejores niveles de rendimiento utilizando Spreadsheets. Para acceder al entorno de secuencia de comandos, podemos ver la siguiente imagen, as se tendr una referencia ms clara.

Google Apps Script

Para obtener un mejor rendimiento en la realizacin de automatizacin de procesos, el procedimiento adecuado sera utilizar Google Forms como entorno para elaborar formularios, luego el procedimiento de personalizar las funcionalidades dentro del SpreedSheet que genera el formulario. Google Sites Finalmente, despus de crear el formulario y el Spreedsheet para una automatizacin de proceso, podemos difundir nuestro aplicativo dentro de un Google Site o un entorno web. Si utilizamos Google Sites, podremos incrustarlo utilizando un gadget que se encuentra en el men principal, insertando el formulario y, finalmente, la hoja de clculo personalizada. Google Sites tambin presenta su propio gestor de ejecucin de las funciones de Google Apps Script utilizando el Editor de Script. Sin embargo, solo se puede ejecutar secuencias de comandos de Google Apps Script, si accede al servicio a travs de una cuenta de Google (Ests logeado a tu cuenta mientras navegas el sitio). Cuando ejecute una secuencia de comandos de Google Apps Script, la accin se registra como procedente de su cuenta. Por ejemplo, si hace clic en un enlace que ejecuta una secuencia de comandos para enviar un correo electrnico, el mensaje se enviar desde su direccin de correo electrnico. Si la secuencia de comandos de Google Apps Script, requiere acceso a la informacin de su cuenta. Por ejemplo, para enviar un correo electrnico o crear una invitacin del calendario, deber autorizar dicho acceso. - Autorice el acceso a los datos de su cuenta, nicamente, a secuencias de comandos de Google Apps Script de sitios y personas de confianza. Si tiene dudas sobre cmo se utilizar su informacin, haga clic en "Cancelar" en el cuadro de dilogo en que se solicita su autorizacin. - Si, por el contrario, quiere que la secuencia de comandos pueda acceder a su cuenta, haga clic en "Autorizar". A continuacin, haga clic en el enlace otra vez para ejecutar la secuencia de comandos.

Google Apps Script

Google Sites recordar que ha autorizado el acceso a su cuenta a esta secuencia de comandos de Google Apps Script y solo le volver a solicitar autorizacin, si la secuencia debe acceder a la nueva informacin. Entornos y aplicativos web Las secuencias de comandos Apps Script pueden ser incrustados, tambin, en otros entornos o aplicativos web embebiendo el cdigo que puede generar. Para ello, es necesario obtener el cdigo y, luego, insertarlo en nuestro aplicativo o entorno web para visualizar su respetiva funcionalidad. 1.1.5 Requerimientos para comenzar con Apps Script Reconocimiento de lenguajes y entornos - Conocimiento del lenguaje JavaScript. - Se sugiere estar familiarizado con Google Docs (Spreadsheets, Forms), Google Sites y desarrollo en entornos web. - Los puntos anteriormente definidos, son solo sugerencias mas no requisitos obligatorios. Los manuales e informacin que se puede encontrar navegando en los diversos entornos web como en www.code.google.com, hacen nfasis a que no se presenta requerimientos a nivel avanzado en programacin para poder comenzar con Apps Script. Requerimientos de ejecucin - Cuenta de Google: La cuenta puede ser una cuenta de gratuita, en la que la direccin de correo electrnico est en el dominio gmail.com, o una cuenta de Google Apps, en la que la direccin de correo electrnico est en el dominio yourdomain.com. Por ejemplo, si su empresa (example.com) utiliza Google Apps, su direccin de correo electrnico es yourusername@example.com - Navegador web. Un navegador web compatible. Estos incluyen Google Chrome, Mozilla Firefox y Safari. 1.1.6 Interaccin con otras aplicaciones de Google Google Apps Script incluye objetos y mtodos para el control de datos en las siguientes aplicaciones:

Google Apps Script

1.1.7 Otros servicios Google Apps Script tambin incluye los siguientes servicios: - UiApp services, que permiten a los scripts crear una pantalla interactiva con los elementos de la interfaz del usuario. Esto es experimental. - JDBC services (Java Database Connectivity), que permiten a los scripts interactuar con los sistemas de bases de datos relacional. Esto es experimental. - DocsList services, que permiten a los scripts crear carpetas, subcarpetas y archivos en la lista de documentos de Google Docs. Esto es experimental. - Base services, que permiten el acceso a los scripts de usuario, la sesin y la informacin del navegador. - SOAP services (Simple Object Access Protocol), que dan a los scripts, acceso a los servicios web. Utilizar los servicios SOAP para el intercambio de datos o comunicarse con las aplicaciones web corporativas habilitadas para los servicios. - XML services (eXtensible Markup Language), que permiten a los scripts extraer datos de documentos XML y luego manipular dichos datos. - Language services, que permiten a los scripts obtener traducciones de textos de un idioma a otro. - Mail services, que permiten a los scripts enviar correos electrnicos. - UrlFetch services, que permiten a los scripts comunicarse con otros hosts en la Internet y obtener recursos de los servidores.

Google Apps Script

- Utilities services, que permiten a los scripts codificar y decodificar las cadenas de texto y las fechas en formatos. - Properties services, que permiten almacenar las propiedades en un script para cada usuario. Esto es experimental. - Contacts services, que permiten a los scripts, crear, eliminar y actualizar la informacin de contacto de los individuos como para grupos en Google Contacts.

1.2 Gua de usuario

1.2.1 Reconocimiento de entorno Para analizar cada entorno donde podremos utilizar las secuencias de comandos Google Apps Script, analizaremos cmo aprender a crear y reutilizar dichos scripts, mediante los siguientes entornos: a) Galera de secuencia de comandos La forma ms rpida y fcil de usar Google Apps Script es utilizar la galera de secuencia de comandos existentes. Estos scripts son aportados por los miembros del equipo de Google Apps. Para instalar y ejecutar un script desde la galera, cumpla los siguientes pasos: i. Acceda a Google Docs utilizando su cuenta. ii. Cree una hoja de clculo.

iii. D un nombre a la hoja de clculo de manera que se guarda automticamente.

Google Apps Script

iv. Nos ubicamos en la seccin Insertar > Secuencia de Comandos. De este modo, veremos la galera de secuencias de comandos que contienen los scripts, los cuales se pueden instalar y ejecutar.

v. En este paso, podremos visualizar la galera general que contiene diversas categoras de scripts listos para instalar.

Google Apps Script

vi. Para instalar un script, solo debemos dar clic en Instalar. Luego, aparece un mensaje, el cual indica que el script se ha instalado correctamente.

xxxxxxxx

Nota: Antes de instalar un aplicativo, siempre se debe autorizar al script para que utilice los datos de nuestra cuenta. Este punto fue detallado en la seccin de requerimientos de ejecucin en la seccin del enfoque terico. Finalmente, para ver el estado de nuestro script, podemos ver, en la galera, el mensaje de instalacin:

Google Apps Script

vii. Finalmente, le damos clic a Cerrar y nuestro script quedar instalado. Para las gestiones de administracin de nuestros scripts, podremos utilizar el Administrador de secuencia de Comandos. Para acceder a dicho entorno, vamos a la seccin: Herramientas > Administrador de secuencia de comandos.

Finalmente, podremos obtener la vista del administrador, lo cual nos ayudar a listar y a visualizar toda la seccin de los scripts que contiene nuestro spreadsheet.

Google Apps Script

10

Para ejecutar cualquier sentencia de los comandos que tenemos dentro de la administracin, podemos utilizar los botones ubicados en la parte inferior de la pantalla, tales como: Ejecutar, Editar, Nuevo, Cerrar. b) Acceder a codificar un nuevo Apps Script en un SpreadSheet. Tomando como ejemplo la misma hoja que hemos creado recientemente, vamos a ubicar la seccin Herramientas > Editor de secuencia de comandos y veremos el cdigo que se ha generado, producto de la instalacin del script creado anteriormente.

Dentro de la seccin del editor de comandos, vamos a evaluar la barra horizontal de opciones que muestra las siguientes caractersticas. Entre los ms importantes tenemos:

Google Apps Script

11

Seccin Archivo

Nota: Al igual que podemos compartir un documento, la seccin de comandos tambin se puede compartir con la finalidad que se pueda trabajar de forma colaborativa. La secuencia de Compilar una interfaz de usuario, nos permitir la posibilidad de generar aplicativos utilizando interfaz grfica. El entorno de creacin de aplicativos bajo esta modalidad presenta el siguiente esquema:

Google Apps Script

12

Seccin Compartir

Al igual que podemos compartir un documento, la seccin de comandos tambin se puede compartir con la finalidad de que otros usuarios con cuentas Google, puedan acceder y modificar nuestra seccin de comandos. De esta forma, se puede realizar el trabajo colaborativo para la generacin de scripts. Adicional a dicha funcionalidad, tambin podemos publicar nuestro proyecto o tambin realizar una publicacin en modalidad de servicio. Seccin Triggers

La secuencia de Triggers o activadores, cumple los mismos parmetros desde el enfoque de programacin en base de datos. Podemos ejecutar una determinada funcin ante un evento o programacin, en una hora especfica, de acuerdo a la solucin que podamos plantear.

Google Apps Script

13

Seccin Ayuda

La seccin de ayuda nos permitir, en caso de no tener conocimiento en el manejo de la seccin de Apps Script, el acceso a informacin y referencias generales para comenzar la secuencia de comandos para personalizar Spreadsheets. c) Acceso a secuencia de comandos desde Google Sites La secuencia de creacin y edicin dentro de una secuencia de comandos Apps Script, se da despus de haber creado una pgina web dentro de Google Sites. Para ello, vamos a ubicar la siguiente pestaa posterior a haber creado un sitio prueba.

Seccin: Ms Acciones > Administrar Sitio. La pantalla principal que nos mostrar, har referencia a la seccin de administracin general de un Google Site. Para lo cual, ubicaremos la seccin Secuencia de Comandos de Apps.

Google Apps Script

14

En este entorno, podremos aadir nuevas secuencias con la finalidad de insertarlo dentro de un site. La pantalla de creacin de la sintaxis de nuestra sentencia es la misma como si utilizaramos un Spreadsheet, para lo cual cuando vayamos a crear una sentencia, se listar automticamente y estar disponible al momento de insertar elementos dentro del site.

Para insertar, por ejemplo, una sentencia de comandos guardada dentro del administrador de comandos de Google Sites, nos ubicamos en la pgina donde deseamos insertarla y activamos la opcin Editar Pgina.

Google Apps Script

15

Finalmente, para insertar la secuencia de comandos, nos ubicamos en la seccin: Insertar > Gadgets Apps Script.

Al escoger dicha seccin, nos mostrar la lista de comandos Apps Script que contamos en nuestra cuenta.

Dentro de esta opcin, tambin podemos insertar la URL de la secuencia de comandos Google Apps Script que fueron publicados como servicio.
Google Apps Script 16

Cuando insertamos nuestro elemento, nos mostrar una pantalla que debemos de tener en cuenta a fines de determinar el grado de privacidad de ejecucin de nuestro aplicativo.

Cuando aceptamos los trminos, veremos que nuestra secuencia de comandos se ha insertado en un Gadget Apps Script, tal como lo muestra la siguiente imagen:

Por ltimo, guardamos la pgina y ya habremos insertado nuestra secuencia de comandos en una pgina de un Google Site. Nota: Usted debe ser propietario de un sitio o un colaborador del sitio (editor) para acceder a Google Apps en un script.

Google Apps Script

17

1.2.2 Desarrollo de Scripts Sobre el Script Editor La pantalla principal, por defecto, declara una funcin llamada myFunction () e incluye la apertura y el cierre de las llaves de la funcin. Sin embargo, es el nico cdigo. Esta funcin no se ejecutar si se trata de ejecutarla. Podemos instalar un Script de la Galera de Scripts disponible desde el men del spreadsheet. Tambin se puede usar el Script Editor que muestra el rea donde se va a escribir las secuencias de comandos. Se aplican colores para cada criterio a fines de que sea fcil la identificacin de los diversos elementos en el momento de la programacin. Para ello, vamos a ver las siguientes caractersticas: - Los elementos tales como var, function y las estructuras de programacin son de color granate. - Los nombres de las variables son de color azul. - Los argumentos literales a los mtodos estn en verde. - Los argumentos de las variables a los mtodos son de color azul plido. - Los nombres de variables son de color azul plido. - Nombres de los mtodos y la funcin estn en negro. - Texto literal es de color rojo, incluyendo las lneas de cdigo que se comentan. - Los comentarios estn en color marrn claro. Puede realizar las siguientes tareas en el Script Editor. - Administracin de archivos, tareas, como abrir, eliminar, renombrar y guardar, cortar, copiar, buscar, reemplazar y pegar texto y/o scripts. - Establecimiento de una zona horaria para el script, lo que asegura que con el tiempo las secuencias de comandos basado en triggers se ejecutan cuando usted desee que se ejecuten. Establecer una zona horaria en Archivo > Propiedades. - Apertura de la Galera de Script, usando Insertar > Secuencia de comandos. - Al examinar las propiedades del script, que incluyen el nombre, descripcin, fecha y hora de un script, se modific la clave de secuencia de comandos. La clave del script es un identificador nico para cada secuencia de comandos. - Ejecutar las funciones. Cualquier funcin puede ser invocada directamente desde el Editor de secuencias de comandos, excepto aquellos con un nombre que termina con un script bajo, que solo puede ser llamado desde otras funciones. - Viendo mensajes de registro y las transcripciones de la ejecucin.
Google Apps Script 18

Planificacin de una secuencia de comandos Para planificar el desarrollo de un script, le resultar til escribir pseudocdigo. El pseudocdigo es una versin narrativa precisa y detallada de lo que el script tiene que hacer. Se utiliza pseudocdigo para ayudarle a determinar cmo funciona el script ante muchas necesidades, donde se necesitan variables, bucles y contadores. Tambin es til para realizar diferentes clculos. Aqu les presentamos un pseudocdigo sugerido para la gestin de acciones.
first function runs when Spreadsheet is opened read the current Spreadsheet into a variable define menu entries define menu name second function does most of the work in the Spreadsheet read the current Spreadsheet into a variable set the column labels define a counter called row start a while true loop use an if loop to test whether there's a stock symbol in the current row first column write data to the log look up the stock symbol write the stock information in the correct column of each row that has a stock symbol write data to the log increment the counter

Un adecuado flujo de pseudocdigo, le ser ms fcil para que pueda escribir el script. Caractersticas de un scripts en un SpreadSheets Un script en particular est asociado con una sola hoja de clculo de Google. Si hace una copia de la hoja de clculo, el guion tambin se copia. Usted puede verificar esto mediante el historial de revisiones del script de las secuencias de comandos en la hoja de clculo original y la copia. Una hoja de clculo en particular puede tener varios scripts asociados a ella. Si utiliza el onOpen, controlador de eventos, en ms de un script asociado con una hoja de clculo en particular, todos los scripts deben comenzar a ejecutar cuando se abre la hoja de clculo y el orden en que los scripts se ejecutan es indeterminado. Un controlador de eventos es una funcin ejecutada cuando un evento en particular se lleva a cabo. Para obtener informacin completa acerca de los controladores de eventos, consulte <ejecutar secuencias de comandos en respuesta a un evento>. Un script, actualmente, no puede llamar o crear otro script y no se puede llamar a funciones en otro script. Las funciones no pueden cambiar el estado en el entorno de ejecucin, aunque se puede simular que el comportamiento de las clulas de hoja de clculo se pueda modificar. Es decir, despus de que una funcin se ha ejecutado, todos los datos que se almacenan en las variables que la funcin y los objetos se borran.
Google Apps Script 19

Si desea almacenar los resultados de una funcin, debe copiarlos en una celda de hoja de clculo. Caractersticas de un Scripts en un Sites Puede realizar eventos Apps Script tipo triggers de los vnculos que se insertan en un Google Site. Para obtener informacin sobre cmo hacerlo, consulte utilizando Apps en su Site. Tambin puede insertar un script en un sitio como un gadget. Para obtener ms informacin, consulte la informacin de incrustacin de secuencias de comandos Apps Script de Google Sites en los enlaces de inters. A partir de un Script Cuando se abre el Editor de secuencias de una hoja de clculo o el sitio que no contiene un script, se ve lo siguiente: function myFunction ( ) { } El nombre de la funcin myFunction es temporal, sustituto de un nombre que se asigna. Cuando se escribe un script, puede asignar funciones en el script con cualquier nombre. Los nombres de funciones se componen, generalmente de las palabras que indican, lo que hace la funcin como getStockName. Los nombres de las funciones, por lo general, cumple estndares sugeridos ms no obligatorios, donde la primera letra de la primera palabra es minscula y la primera letra de cada palabra que le sigue se escribe con mayscula y, as sucesivamente. Las instrucciones de una funcin deben escribirse entre llaves. Los scripts pueden tener tantas opciones segn lo que el usuario desee. A medida que escribe las funciones de los scripts, se sugiere incluir comentarios que describen lo que los principales bloques de cdigo realizan con el propsito de crear determinadas variables y as sucesivamente. Comentarios que sean ms fciles de entender para saber lo que hace el script y, tambin que sean ms fciles para mantener la secuencia de comandos en el futuro. Funciones que termina en un script bajo (_), por ejemplo, internalStuff_ (), se diferencian de otras funciones. Usted no ve estas funciones en el campo de ejecucin en el Editor de secuencias de comandos y no aparecen en el Administrador de secuencia de comandos en la hoja de clculo. Donde podr utilizar el subrayado para indicar que los usuarios no deben tratar de ejecutar la funcin y la funcin solo est disponible para otras funciones.

Google Apps Script

20

Definir la forma de ejecucin de la secuencia de comandos Usted controla cundo y cmo se debe ejecutar el script. Al escribir scripts, usted debe elegir entre las siguientes formas de ejecucin: Uso de un controlador de eventos: Los controladores de eventos permiten ejecutar los scripts cuando una hoja de clculo se abre, cuando un script se instala, cuando una hoja de clculo se edita y, a veces, cuando usted lo elige. Para obtener informacin completa, consulte en los enlaces de inters del curso. Uso de un elemento de men personalizado: Por ejemplo, el script de Precios en Stock de la accin se ejecuta cuando el usuario hace una seleccin de men particular. Uso de un dibujo o un botn incrustado en una hoja de clculo. Cuando el usuario hace clic en un dibujo o imagen, una secuencia de comandos asociada se ejecuta. Para ms informacin, consulte en: <Creacin de un botn para ejecutar el cdigo> en el tutorial de <Lectura de datos de hoja de clculo Utilizacin de objetos JavaScript>. Utilizando una funcin personalizada que hace referencia como una funcin de hoja de clculo. Para ms informacin sobre funciones personalizadas, consulte en: <Utilizacin de funciones personalizadas>. Al hacer clic en el botn de ejecucin en el Editor de Script. Al hacer clic en la ejecucin del botn Script Manager, que se llega por la eleccin de Herramientas> Administrador de secuencia de comandos. La identidad con la que se ejecuta un script depende de cmo se pone en marcha. Para obtener informacin completa sobre esto, vea Permisos de comprensin y ejecucin de Scripts. Utilizando el API de Google Apps Script Para utilizar la API de Google Apps Script, tendremos que hablar un poco acerca de los lenguajes de programacin orientados a objetos y cmo funcionan. A continuacin, hablaremos de cmo leer la documentacin de la API. Google Apps Script utiliza el lenguaje JavaScript. Operaciones especficas de Google Apps Script que se realizan con los objetos y mtodos descritos en la documentacin del API. API significa interfaz de programacin de aplicaciones. Una API ofrece preempaquetados de cdigo para tareas estndares que usted necesita para llevar a cabo en scripts o programas.

Google Apps Script

21

El API de Google Apps Script incluye objetos que se utilizan para realizar tareas como el envo de correo electrnico, creacin de entradas de calendario, la creacin de mapas, creando una interfaz de usuario, o traduccin de textos. Un mtodo describe el comportamiento de un objeto y una funcin asociado a un objeto. Por ejemplo, Google Apps Script tiene un objeto llamado MailApp que se utiliza para crear y enviar correo electrnico. MailApp tiene dos mtodos, sendEmail y getRemainingDailyQuota. Para enviar correo electrnico, se invoca el mtodo sendEmail y este proporciona los atributos. Google Apps Script tiene la capacidad de trabajar con atributos bsicos y avanzados. Se necesitan atributos para que un mtodo sea ms funcional operativamente. Los atributos son opcionales y le dar ms flexibilidad en la definicin del comportamiento de un mtodo. En el caso del mtodo sendEmail, los atributos especifican la informacin que entra en el correo electrnico. El mtodo sendEmail tiene atributos avanzados. Los atributos son los destinatarios, el asunto del correo electrnico, el cuerpo o el texto que se enva, la direccin de respuesta de correo electrnico, y otros argumentos. Por ejemplo, la instruccin siguiente enva correo electrnico a cuatro personas, mikemike, lisa, Janos, y Nikhil, cuyos nombres estn en una lista delimitada por comas y entre comillas. El correo electrnico tiene la lnea de asunto Attachment Example y el cuerpo del texto Here is my document. Las instrucciones dentro de las llaves definen el archivo adjunto. MailApp.sendEmail("mikemike@example.com,lisa@example.com,janos@example.com,ni khil@example.com", "Attachment example", "Here is my document", {attachments: myFiles}); Las instrucciones de arriba invocan al mtodo sendEmail en la clase MailApp . La sintaxis general es la siguiente:

ClassName.methodName(argument1, argument2, argument3....argumentn); Por ejemplo, para que aparezca un cuadro de mensaje diciendo Hello, World!, que podra llamarse en el mtodo MsgBox en el navegador de clases, debemos pasar el texto Hola, mundo! como un atributo: Browser.msgBox("Hello, World"); Browser.msgBox () no est actualmente disponible en un Google Site, en su lugar puede enviar una notificacin por correo electrnico:

Google Apps Script

22

MailApp.sendEmail("you@email.com", "Hello world!", "Sent from Apps Script") O aadir un mensaje en el registro: Logger.log("Hello world!") Nota: En el API de Google Apps Script, la barra lateral de la izquierda contiene enlaces a todos los servicios y todos los objetos asociados a un servicio particular. Por ejemplo, si hace clic en el enlace DocsList, ver una pgina web que detalla los objetos y todos los mtodos de los objetos. Si hace clic en el enlace con el archivo de clase base, se ve una pgina que describe los mtodos de la clase. Si hace clic en un nombre de mtodo en la tabla, aparece una lista de argumentos disponible para el mtodo y los valores devueltos por el mtodo. Por ejemplo, el getName mtodo devuelve, el nombre de un archivo como un valor de cadena (de texto). o Almacenamiento de datos y fuente de datos Google Apps Script puede acceder o recuperar los datos en diferentes formatos de diferentes maneras. La forma ms sencilla de proporcionar datos a un script es poner los datos en la hoja de clculo o el sitio donde se almacena el script. Puede escribir, importar datos a hojas de clculo de Google a partir de los siguientes formatos: Xls Xlsx Ods Csv Txt Si usted tiene datos en otro formato, puede ser capaz de exportar a uno de los formatos de archivo mencionado, y luego importar los datos en hojas de clculo de Google. Google Apps Script puede trabajar con datos XML. Es necesario conocer la estructura de los datos XML para analizar y manipular los datos. Para ms informacin, consulte la API para el manejo de documentos XML y el tutorial para analizar documentos XML. o Utilizacin de funciones personalizadas Una funcin personalizada es una funcin que se llama directamente desde una celda de una hoja de clculo, utilizando la sintaxis myFunctionName = (). Las funciones personalizadas devuelven valores, pero no pueden establecer los valores fuera de las celdas que estn dentro en la mayora de circunstancias, una funcin personalizada en la celda A1, no puede modificar la celda A5. Sin embargo, si una funcin retorna un doble arreglo, los resultados sobrepasan la celda que contiene la funcin y, llenan la parte inferior y del costado derecho de la celda que contiene la funcin personalizada. Usted puede probar (testear) esto con una funcin personalizada que contenga [[1,2]].[[3,4]]; como retorno.
Google Apps Script 23

El script The Oracle of Bacon que se puede ver en el tutorial sobre el anlisis de los datos XML, utiliza una funcin personalizada para obtener los nombres de los dos actores antes de usar the Oracle of Bacon: = kb ( "ACTOR_NAME1" , "ACTOR_NAME2" ) . No es necesario realizar ninguna accin en una funcin personalizada para ejecutar, adems de proporcionar, los datos requeridos por la funcin personalizada dentro de la celda. Las funciones personalizadas tienen algunas restricciones, pues no son compartidos por otras funciones: Una funcin personalizada no puede enviar un correo electrnico. Una funcin personalizada no puede operar en Google Site. En una funcin personalizada, no se pueden realizar operaciones que requieren la autorizacin del usuario. Por ejemplo, una funcin personalizada no se puede colocar en una agenda de eventos en el calendario de otro usuario. Una funcin personalizada no puede realizar operaciones que requieren el conocimiento de quin es el usuario. o Interacciones con las frmulas en spreadsheets existentes En un spreadsheet, existen funciones que nos permitirn ejecutar las funciones que podamos escribir o instalar, directamente, desde la galera de scripts. Aqu est la informacin acerca de cmo las frmulas de los SpreadSheets y las funciones en el script pueden ejecutar e interactuar. Si hay una funcin onInstall en el spreadsheet, se ejecuta cuando se instala la hoja de clculo. Si hay una funcin on Open en el spreadsheet, se ejecuta cuando se abre la hoja de clculo. Funciones personalizadas y las frmulas de la hoja, se ejecutan cada vez que se evalu el spreadsheet completo o cuando cambian los datos en la funcin de celda o frmula. Otras funciones se ejecutan de forma manual o cuando se activan, haciendo clic en un vnculo o un dibujo para que una funcin se adjunte. o Compartir los Scripts Usted tiene varias opciones para el intercambio de scripts. Es posible que desee compartir un script con los amigos o compaeros de trabajo en particular. Para ello, explcitamente, podemos compartir el Spreadsheet en el que se almacena el script. Es posible que desee compartir una escritura pblica. Si usted tiene una cuenta de Google, puede publicar el script en la Galera de Scripts. Cuando se publica en la Galera de Scripts, el Script estar disponible para otros usuarios de Google Docs.

Google Apps Script

24

Es posible que desee compartir un Spreadsheet y un script. Este es el ms apropiado cuando un script se basa principalmente en el formato de Spreadsheet. Una plantilla de Spreadsheet incluye el script y el formato especial que usted designa. Para compartir la hoja de clculo y puedan ejecutar o modificar la secuencia de comandos, debemos cumplir lo siguiente: 1. Invitar a otros a la hoja de clculo utilizando el Compartir de botn dentro de la hoja de clculo. 2. Asignar los permisos de edicin a los usuarios que deseamos que puedan tener la facultad de editar la hoja de clculo. 3. Para que otros usuarios puedan editar el script: En el Editor de secuencias de comandos, haga clic en Compartir Configuracin del uso compartido. >

Compruebe en Permitir que los colaboradores puedan editar el script y haga clic en Ok.

Para publicar un guion a la Galera de Script, cumpla los siguientes pasos: 1. En el Editor de secuencias de comandos, haga clic en Publicar proyecto. 2. Introduzca el Nombre de script. 3. Escriba una breve descripcin, incluyendo la manera de ejecutar el script, los datos que requiere el guion, y cualquier otra informacin que los usuarios puedan ser tiles. 4. Elija una categora de la lista desplegable. 5. Escriba la ubicacin de una pgina de ayuda. 6. Lea el texto explicativo acerca de los guiones de publicacin.
Google Apps Script 25

7. Lea los trminos adicionales de Google Docs. 8. Haga clic en Publicar. Despus que Google revise el script, lo coloca en la Galera de Script y recibir un correo electrnico confirmando que el guion ha sido publicado. Para enviar una plantilla de hoja de clculo, cumpla los siguientes pasos: 1. 2. 3. 4. 5. Abra la lista de documentos. Seleccione la hoja de clculo. Haga clic en Ms acciones en la lista desplegable. Seleccione Enviar a la galera de plantillas. Escriba una breve descripcin, escoja una o dos categoras de la plantilla, y seleccione un idioma. 6. Haga clic en Enviar plantilla. Para ms informacin sobre las presentaciones de plantilla, lea Envo de una plantilla. o Manejo de Errores Usted puede ver los errores dentro de la secuencia de scripts, mientras que puede estar escribindolos. Si escribe una lnea de cdigo y hay un error tipogrfico en el mismo, el cdigo de colores marcar una lnea que indica que existe un error. Por ejemplo, la siguiente lnea de cdigo del guion precio de la accin es correcta: sheet.getRange(row, 2).setValue(stockInfo.name); Cuando es accedido correctamente mediante el editor de scripts, el cdigo es el siguiente:

Si escribe accidentalmente setVal en lugar de setValue, los parntesis stockInfo.name son de color verde en lugar de negro:

Un script con una sintaxis incorrecta o con fallas, no llegar a ejecutarse. Si hay errores de sintaxis en un script, aparecer un mensaje de error al guardar la secuencia de comandos o en el momento que se intenta ejecutar. Por ejemplo:

Google Apps Script

26

Cannot find method addMenu(string,Undefined). (#3) Los mensajes de error siempre incluyen el nmero de lnea en el script donde se detuvo la ejecucin. Abra el script en el Editor de secuencias de comandos para examinar el guion. Para ms informacin sobre mensajes de error y en los guiones de problemas, consulte a Solucin de problemas y depuracin de scripts. En caso de obtener informacin sobre cmo utilizar el Editor de script incorporado en depurador, vea Utilizar el depurador. Finalmente, revise los enlaces de inters del curso. o Uso del depurador El Script Editor incluye un depurador. El depurador le permite ver el estado actual de las variables y los objetos creados por un script, mientras que se ejecuta. Puede recorrer el cdigo lnea por lnea mientras se ejecuta o establecer puntos de interrupcin en la que se detiene la ejecucin de cdigo para que pueda ver los valores en ese momento. El depurador est destinado, principalmente, para su uso con los guiones largos y complejos que incluyen cientos o miles de lneas de cdigo. Puede escanear y determinar los valores de variables para un pequeo script simplemente viendo el script, pero si el cdigo o los clculos son bastante complejos en un script corto, todava puede encontrar utilizado al depurador. El depurador no funciona con las funciones personalizadas, las funciones onEdit y desencadenantes de eventos o secuencias de comandos, se ejecutan como un servicio. Para iniciar el depurador: 1. Abra una hoja de clculo que contiene un script. 2. Haga clic en Herramientas > Editor de secuencia de comandos > Script Editor. 3. Haga clic en el depurador de cono, que se encuentra entre el triangular, azul Ejecutar el icono y la funcin de la lista desplegable. El depurador cono se parece a un pequeo insecto. El depurador se muestra en la parte inferior de la ventana de Script Editor.

Google Apps Script

27

Los errores de sintaxis son capturados por la escritura de aplicaciones, ya sea en la etapa de entrada o la primera vez que intenta ejecutar un script. Se utiliza el depurador para encontrar errores en los scripts con una sintaxis correcta, pero an no funcionan correctamente. Mientras que puede iniciar el depurador, cuando un script contiene un error de sintaxis, como el SETVAL, tambin puede ver el resultado del error, TypeError: Cannot find function setVal in object Range, en la ventana del editor de secuencias de comandos sobre el script. He aqu un ejemplo del tipo de error que se encuentre con el depurador. Es posible que si tenemos una variable que est siendo utilizada en una posicin incorrecta, automticamente, se almacenar valores incorrectos, por lo que nuestro procedimiento de clculos ser errneo. A continuacin, se utiliza el depurador para observar el valor de la variable en diferentes puntos en el script. Esto permitir localizar a la variable que no est ajustada. Usted puede hacer esto usando declaraciones de registro, que se describen en la creacin de mensajes de registro y ver los registros. Es ms eficaz utilizar el depurador, que le permite ver los valores en tiempo real, sin verificar los registros en varias ocasiones. o Establecer puntos de Interrupcin Un punto de interrupcin o corte es un lugar donde nos gustara que el cdigo detenga la ejecucin para que pueda ver los valores en el depurador. Se puede establecer puntos de interrupcin en un script, haga clic en los nmeros de lnea en el Editor de secuencias de comandos o mediante la insercin de la palabra debugger en una lnea de cdigo. Para eliminar un punto de interrupcin, haga clic en el nmero de lnea, por segunda vez, o eliminar la palabra debugger. Puede establecer puntos de interrupcin en un script si el depurador est visible. Puede establecer puntos de interrupcin en diferentes lugares hasta del script que desee. Los puntos de corte se establecen mediante la insercin del debugger, que se
Google Apps Script 28

guardan con el script. Los puntos de corte establecidos por los nmeros de cada lnea no se guardarn de forma automtica con tan solo hacer clic sobre ellos. Mientras que el depurador no tiene puntos de interrupcin condicionales, puede escribir el cdigo que imita el comportamiento de un punto de interrupcin condicional. Por ejemplo, usted podra poner debugger dentro de un IF... ms construir, de manera que el punto de interrupcin solo se invoca cuando la condicin especificada se cumple: var x=1 while (true) { if (x < 10) debugger }else Exit } x=x+1 } o Utilizar los el visor de filtros El depurador tambin ofrece un par de filtros de visualizacin: Mostrar la herencia y Mostrar todos los datos. Para obtener esta informacin, debe hacer clic en los botones del depurador. Para comprender el filtro de Mostrar herencia, necesita saber un poco acerca de los objetos JavaScript y los mtodos. Cuando se crea un nuevo tipo de objeto, este se basa en un tipo existente que se predefine, lo que podra ser uno de los fundamentos bsicos de JavaScript. Su nuevo objeto no solo hereda los mtodos y propiedades de ella, sino que aade sus propios mtodos y propiedades nicas. Por ejemplo, cualquier objeto String hereda los mtodos y las propiedades de la cadena. Al hacer clic en Mostrar herencia, se muestran los objetos actuales y toda la cadena de la herencia en la jerarqua de objetos. Por lo general, usted no necesita esta cantidad de informacin acerca de los objetos en sus programas. Al hacer clic en Mostrar todos los datos (botn que hay junto al botn Mostrar herencia), nos mostrar todos los objetos estndares y mtodos disponibles para la mquina virtual de JavaScript. 1.2.3 Programacin de tareas comunes Esta seccin proporciona informacin acerca de cmo realizar algunas tareas comunes que se quiere lograr a travs de Google Apps Script. En algunos casos, vamos a apuntar a clases particulares existentes que se puede trabajar para aprender las habilidades.

Google Apps Script

29

a) Creacin de Mens personalizados y mensajes Pop-up Es fcil agregar un men personalizado a una hoja de clculo y vincular las funciones especficas de su script con los elementos del men. He aqu un ejemplo simple. Se aade un men llamado Surprises a la barra de mens. El men tiene dos elementos, una Surprises 1 y otra Surprises 2. Al elegir uno de los elementos del men, las funciones aparecen en un cuadro de mensaje. function onOpen() { var ss = SpreadsheetApp.getActiveSpreadsheet(); var menuEntries = [ {name: "Surprise 1", functionName: "menuItem1"}, {name: "Surprise 2", functionName: "menuItem2"} ]; ss.addMenu("Surprises", menuEntries); } function menuItem1() { Browser.msgBox("You clicked Surprise 1 on the menu!"); } function menuItem2() { Browser.msgBox("Surprise! Surprise!") } Por lo general, se desea que el men personalizado se muestre en cuanto se abra la hoja de clculo. Para ello, incluyen un onOpen, funcin en el script. Estas funciones se ejecutan tan pronto como la hoja de clculo se abre, y son tiles para llenar una hoja de clculo con los mens y datos que el usuario desea ver de inmediato. En el script de ejemplo, las entradas del men se definen en el siguiente cdigo: var menuEntries = [ {name: "Surprise 1", functionName: "menuItem1"}, {name: "Surprise 2", functionName: "menuItem2"} ]; La variable menuEntries contiene una serie de objetos. Cada objeto contiene un par de valores para el nombre y las claves de nombre de la funcin. Un arreglo es una coleccin de elementos que funciona algo as como una hoja de clculo. Cada elemento de una matriz puede ser identificado por su ubicacin en la matriz, denominado punto de ndice. Arrays en JavaScript y Google Apps Script estn basados en cero, es decir, el primer elemento que se conoce como 0, no 1. Por ejemplo, si se crea una matriz de medicin de tres elementos por dos elementos, la primera posicin se conoce como 0,0. Las matrices son una manera conveniente de almacenar y manipular datos en un programa de ordenamiento o secuencias de comandos. Se puede decir que los elementos del men se encuentran en una serie, a causa de los corchetes que encerraban los nombres de los mens y funciones.
Google Apps Script 30

Cada elemento del men se coloca dentro de las llaves, y esto define la sintaxis de cada par de nombre y el nombre de funcin como un objeto. Despus de la definicin de las entradas del men, viene la definicin del propio men: ss.addMenu("Surprises", menuEntries); La etiqueta del men es Sorprises. menuEntries es un parmetro para el mtodo AgregarMen, que pasa en los valores de la matriz que define los nombres de los elementos de men y las funciones de los elementos del men que se encuentran vinculados. Aqu est el cdigo general para la creacin de elementos de men y un men. function onOpen() { var ss = SpreadsheetApp.getActiveSpreadsheet(); var menuEntries = [ {name: "item_name_1", functionName: "function_1"}, {name: "item_name_2", functionName: "function_2"}, {name: "item_name_n", functionName: "function_n"]; ss.addMenu("menu_name", menuEntries); } El siguiente cdigo aparece en un cuadro de mensaje cuando un usuario selecciona un elemento del men: function menuItem1() Browser.msgBox("You clicked Surprise 1 on the menu!"); Generalizando el cdigo sera: function yourFunctionName() { Browser.msgBox("message_to_display" ); Para dar a la funcin del nombre que utiliz en la matriz menuEntries, entonces llame al mtodo msgBox en la clase Browser, pasando como parmetro el mensaje que desea mostrar. b) Optimizacin scripts para un mejor rendimiento Para lograr la optimizacin de nuestros scripts y buscar un mejor rendimiento, vamos a tomar como base dos principios: Minimizar las llamadas a otros servicios.
Google Apps Script 31

Utilice operaciones por lotes siempre que pueda. Las siguientes dos secciones dan un mejor detalle de estos principios: Minimizar las llamadas a otros servicios. Las operaciones de JavaScript son considerablemente ms rpidas que el de comunicarse con otros servicios. Cualquier cosa que usted puede lograr dentro de Google Apps Script, en s, ser mucho ms rpido que la realizacin de llamadas a las hojas de clculo, documentos, sitios, traducciones, y as sucesivamente. Por lo tanto, las secuencias de comandos se ejecutarn ms rpido, si usted puede encontrar maneras de reducir al mnimo las llamadas de los scripts a los servicios. Utilizando operaciones por lotes Los scripts comnmente necesitan leer los datos de una hoja de clculo, realizar clculos, y luego escribir los resultados de los datos a otra hoja de clculo. En Google Apps, se ha incorporado look-ahead cache que nos sirve para optimizar dicho punto para recuperar lo que un script es probable que obtenga y la cach de escritura salve lo que se determine. Usted puede escribir scripts para aprovechar al mximo el almacenamiento en cach, reduciendo al mnimo el nmero de lecturas y escrituras. Alternando la lectura y escritura de comandos. Para aumentar la velocidad de escritura, leer todos los datos en una matriz con un solo comando, realizar cualquier operacin en los datos de la matriz, y escribir los datos con un solo comando. He aqu un ejemplo -un ejemplo que no se recomienda seguir ni usar. El script de hoja de clculo de Fractal Art scriptl en la Galera utiliza el siguiente cdigo para establecer los colores de fondo de cada celda en una cuadrcula de 100 x 100 hojas de clculo: // DO NOT USE THIS CODE. It is an example of SLOW, INEFFICIENT code. // FOR DEMONSTRATION ONLY. var cell = sheet.getRange('a1'); for (var y = 0; y < 100; y++) { xcoord = xmin; for (var x = 0; x < 100; x++) { var c = getColor_(xcoord, ycoord); cell.offset(y, x).setBackgroundColor(c); xcoord += xincrement; } ycoord -= yincrement; SpreadsheetApp.flush(); } El script es ineficiente: se realiza un bucle a travs de 100 filas y 100 columnas, la escritura consecutiva a 10.000 clulas. The Script Aplicaciones write-back cache ayuda, porque obliga al uso de write-back flush al final de cada lnea. Debido al almacenamiento en cach, slo hay 100 llamadas a la hoja de clculo.
Google Apps Script 32

Sin embargo, el cdigo se puede hacer mucho ms eficiente si utilizamos llamadas por lotes. Aqu est una nueva versin en la que se lee el rango de celdas en una matriz llamada colores, la operacin de asignacin de color se realiza en los datos de la matriz, y los valores de la matriz se escriben en la hoja de clculo: // OKAY TO USE THIS EXAMPLE or code based on it. var cell = sheet.getRange('a1'); var colors = new Array(100); for (var y = 0; y < 100; y++) { xcoord = xmin; colors[y] = new Array(100); for (var x = 0; x < 100; x++) { colors[y][x] = getColor_(xcoord, ycoord); xcoord += xincrement; } ycoord -= yincrement; } sheet.getRange(1, 1, 100, 100).setBackgroundColors(colors); El cdigo ineficiente toma cerca de 70 segundos para correr. El cdigo eficiente se ejecuta en apenas 1 segundo. Si usted est buscando en el script de la hoja de clculo de Fractal Art script, reestructurar la sintaxis en la secuencia del script, a fin de buscar el mejor rendimiento para que este ejemplo sea ms fcil de seguir. El script que se publica utiliza la llamada setBackgroundRGB, en lugar de setBackgroundColor, que puede ver ms arriba. La funcin getColor_ fue cambiado de la siguiente manera: if (iteration == max_iteration) { return "#000000"; } else { var c = 255 - (iteration * 5); c = Math.min(255, Math.max(0, c)); var hex = Number(c).toString(16); while (hex.length < 2) hex = "0" + hex; return ("#"+hex+"3280"); } c) Envo de correo electrnico utilizando un script Para realizar dicha funcionalidad, podemos revisar los apartados que se encuentran en los siguientes puntos: <Envo de correo electrnico de una hoja de clculo> <Simple Mail fusin>

Google Apps Script

33

Revise los enlaces de inters del curso para ver cada punto mencionado. 1.2.4 Eventos a) Ejecucin de scripts en respuesta a un evento Es posible que usted desee que un script se ejecute cada da a una determinada hora, o que pueda tener un script que se debe ejecutar despus de que un usuario enve un formulario de recopilacin de datos. Google Apps Script proporciona manejadores de eventos simples y manejadores de eventos instalables, que son maneras fciles para que especifique las funciones a ejecutar en un momento determinado o en respuesta a un evento. Antes de examinar los detalles de cada sistema y las diferencias entre ellos, vamos a considerar la terminologa que usamos para los eventos. Un caso es, generalmente, considerado como el que pas. Por ejemplo, he aqu algunos hechos: El reloj dio la una. La hoja de clculo se abri. La hoja de clculo ha sido editado. El formulario se envi. En Google Apps Script, como en la mayora de los lenguajes de programacin, estos eventos tambin son conocidos como factores desencadenantes de eventos, o simplemente disparador (triggers). El cdigo se llama, en respuesta al evento, un controlador de eventos. A menudo, aunque no siempre, el cdigo pasa un atributo al controlador de eventos que describe el evento, y este atributo tambin se conoce como parte el evento. b) Manejador de eventos simples Los manejadores de eventos simples estn integrados en el lenguaje de Google Apps Script. Para utilizar controladores de eventos, debe dar a su funcin un nombre especial que denote el tipo de evento que ejecute la funcin. Utilice los controladores de eventos simples para ejecutar un script o una funcin en las siguientes circunstancias: Cuando un script se instala desde la Galera de Script, con la funcin onInstall . Cuando una hoja de clculo se abre, con la funcin onOpen . Cuando una hoja de clculo se modifica, con la funcin onEdit. Estos controladores de eventos simples se ejecutan en respuesta a las acciones en el editor de hojas de clculo, y se ejecutan con el mismo contexto de usuario. Por ejemplo, si Bob abre la hoja de clculo, la funcin onOpen se ejecuta como Bob, con independencia de quien aadi el script de la hoja de clculo.

Google Apps Script

34

Por esta razn, los controladores de eventos simples estn restringidos en lo que se les permite hacerlo: La hoja de clculo que contiene el script debe ser abierto para su edicin. Los controladores de eventos simples no pueden determinar el usuario actual. Los controladores de eventos simples no pueden acceder a servicios que requieren autenticacin como por ejemplo de usuario. Por ejemplo, el servicio Google Translate es annimo y se puede acceder a los controladores de eventos simples. Calendario, correo y el sitio no son annimos y los controladores de eventos simples no pueden acceder a esos servicios. Los controladores de eventos simples solo pueden modificar la hoja de clculo actual. El acceso a otras hojas de clculo est prohibido. Para ms informacin sobre eventos de seguridad, consulte en: Descripcin de los permisos y la ejecucin de scripts en los enlaces de inters del curso. onOpen () La funcin onOpen se ejecuta automticamente cuando un usuario abre una hoja de clculo. La funcin onOpen es ms comnmente utilizada para agregar elementos de men personalizados a la barra de men de la hoja de clculo. // The onOpen function is executed automatically every time a Spreadsheet is opened function onOpen() { var ss = SpreadsheetApp.getActiveSpreadsheet(); var menuEntries = []; // When the user selects "addMenuExample" menu, and clicks "Menu Entry 1", the function function1 is executed. menuEntries.push({name: "Menu Entry 1", functionName: "function1"}); menuEntries.push({name: "Menu Entry 2", functionName: "function2"}); ss.addMenu("addMenuExample", menuEntries); } onEdit () La funcin onEdit se ejecuta automticamente cuando cualquier celda de la hoja de clculo se edita. Un caso de uso muy sencillo para onEdit es registrar la modificacin de un dato almacenado en una celda. Guarda la ltima modificacin que se ha editado. El atributo E que se pasa a la funcin contiene una sola propiedad, source, que es la hoja de clculo que se est editando. function onEdit(event) { var ss = event.source.getActiveSheet(); var r = event.source.getActiveRange(); r.setComment("Last modified: " + (new Date())); }

Google Apps Script

35

onInstall () La funcin onInstall se invoca cuando un script se instala desde la Galera de Script. El caso de uso ms comn para onInstall es el mismo que para onOpen: la creacin de mens personalizados para el usuario. Cuando un script se instala, por primera vez, en una hoja de clculo, la funcin onOpen no puede ser llamado por la hoja de clculo si ya est abierto. Si el script tiene que hacer mens o realizar cualquier otra tarea inmediatamente despus de ser instalado, el script puede llamar onOpen de onInstall. Por ejemplo: // Call onOpen from onInstall function onInstall() { onOpen(); } // onOpen will run when the script is subsequently opened function onOpen() { // some code here } c) Controlador de eventos instalables Para instalar manejadores de eventos en los triggers, utilice el Script Editor y mediante su configuracin, realice llamadas a los triggers del documento. Podemos usar triggers para ejecutar scripts cuando se presente cualquiera de los siguientes eventos: Cuando una hora determinada llega. Puede definir el tiempo como un ao, mes, da de un mes, el da de la semana, hora, minuto o segundo. Cuando se enva un registro utilizando formulario. Cuando una hoja de clculo se edita. A diferencia de los controladores de eventos simples onEdit, instalar el controlador de eventos puede actuar como el usuario que configur el trigger. Cuando una hoja de clculo se abre. A diferencia de los controladores de eventos simples onOpen, instalar el controlador de eventos puede actuar como el usuario que configur el trigger. Para acceder a la gestin de triggers, nos podemos ubicar en Herramientas > Editor de secuencia de comandos > Triggers.

Google Apps Script

36

Para obtener ms informacin acerca de la gestin de eventos, puede seguir el enlace de <Running Scripts in Response to an Event> en los enlaces de inters del curso. 1.2.5 GUI Interfaz grfica de usuario Google Apps Script le ofrece la posibilidad de crear una interfaz de usuario para la visualizacin o la captura de informacin. Las secuencias de comandos pueden crear una amplia gama de elementos de la interfaz de usuario, incluyendo pero no limitado a los siguientes: Los botones. Los botones de radio. Botones de seleccin. Las casillas de verificacin. Los campos de texto. Las etiquetas. Ttulos. Los cuadros de lista. Los cuadros de dilogo. Paneles de muchos tipos. Y elementos mucho ms de los que es posible enumerar aqu. En la seccin Visualizacin de los elementos de interfaz de usuario disponible, indica cmo ver todos los elementos disponibles. Tambin puede revisar la documentacin de la API para esta funcin. Despus de poner todos estos elementos, el resultado es una interfaz de usuario de trabajo. Las secuencias de comandos puede mostrar la interfaz de usuario de dos maneras: Directamente de un Spreadsheet. Directamente desde un sitio. Como un servlet independiente. Para ms informacin sobre la decisin de cmo mostrar la interfaz, consulte en: decidir si ejecutar un script desde un spreedsheet o como un servicio. a) Visualizacin de los elementos de interfaz de usuario disponible Usted puede crear un gran nmero de elementos de la interfaz de usuario, a travs de Google Apps Script. Para ver todos los elementos disponibles: 1. Abrir una hoja de clculo de Google. 2. Haga clic en Herramientas > Editor se secuencia de comandos. 3. Escriba las siguientes instrucciones: no copiar y pegar:

Google Apps Script

37

funcin myFunction () { var aplicacion = UiApp . createApplication (); var boton = aplicacion . } Usted ve un men con todos los elementos disponibles que se pueden crear, as como los argumentos necesarios para cada elemento. Si usted no ve una lista de mens, puede ser debido a que se ha pegado en el cdigo. La funcionalidad integrada de autocompletado de cdigo en el editor, deber escribir el punto final que sigue a la aplicacin. b) El diseo de la interfaz de usuario Antes de empezar a escribir el script para mostrar la interfaz de usuario, haga lo siguiente: 1. Plan del Script. Qu tareas debe realizar el script? 2. Escriba la informacin especfica que desea mostrar o cobrar a sus usuarios. 3. Dibujar la interfaz de usuario y hacer notas acerca de todos los elementos de la interfaz que debe crear con su script. 4. Determine lo que el script y la interfaz debe hacer en respuesta a la intervencin del usuario. 5. Determinar las condiciones para salir del script. c) Creacin de elementos de la inferfaz de usuario Antes de que pueda crear elementos de interfaz de usuario, tales como botones o cuadros de dilogo, se necesita un UiApp objeto de la aplicacin que contiene los elementos de interfaz de usuario. Despus de crear la UiApp objeto de aplicacin, puede agregar botones, cuadros de dilogo, paneles y otros elementos a la UiApp objeto de aplicacin. La sintaxis general para estas operaciones es el siguiente: Para crear un UiApp objeto de aplicacin, utilice la sintaxis var your_application_object_name UiApp.createApplication=(); donde your_application_object_name es el nombre que se asigna. Para crear un elemento de la interfaz de usuario y asociarlo con su UiApp objeto de aplicacin, utilice la sintaxis var your_ui_element_name =your_application_object_name.createElement_Name (); Para agregar un elemento de la interfaz de usuario a otro, por ejemplo para mostrar un botn en un panel, utilice la sintaxis your_ui_element_name1.add( your_ui_element_name2); La siguiente sentencia crea un objeto de aplicacin llamada myApp llamando al createApplication mtodo de la clase UiApp:
Google Apps Script 38

var myapp = UiApp . createApplication ( ); Ahora puede crear algunos elementos de la interfaz de usuario. Aqu hay un botn con el texto Press Me en l: var myButton = myapp . createButton ( 'Press Me' ); El texto que desea mostrar en un botn se pasa como un argumento. Es posible que desee un grupo que contenga el botn. El siguiente, crea un panel vertical. var MyPanel = myapp . createVerticalPanel ( ); Hay otros tipos de paneles, tambin: paneles pop-up, paneles de pila, los paneles de enfoque, paneles de formato, y as sucesivamente. Aqu est el cdigo para mostrar el botn en el panel: MyPanel . add ( myButton ); A continuacin, aadir el panel de la aplicacin: myapp . add ( MyPanel ); Por ltimo, es necesario instruir a Google Apps Script para mostrar los elementos de la interfaz: show ( Myapp ); Puede crear los elementos de la interfaz de usuario en cualquier orden. El orden en que se agregan los elementos a los objetos determina el orden de presentacin. Por ejemplo, si crea un objeto VerticalPanel, y aade elementos a, b, c, en el panel, los elementos se muestran de arriba a abajo, en ese orden.

Google Apps Script

39

Sin embargo, usted puede crear a, b, y c en cualquier orden. La creacin de elementos y agregarlos a su aplicacin, son pasos separados que requieren instrucciones por separado. He aqu un pequeo script que no hace ms que mostrar un panel con un botn en l. Puedes seguir lo que hace cada lnea en los comentarios. function myAppFunction() { // Name the function // Read the current Spreadsheet into mydoc var mydoc = SpreadsheetApp.getActiveSpreadsheet(); // Create the UiApp object myapp and set the title text var myapp = UiApp.createApplication().setTitle('Here is the title bar'); // Create a button called mybutton and set the button text var mybutton = myapp.createButton('Here is a button'); // Create a vertical panel called mypanel and add it to myapp var mypanel = myapp.createVerticalPanel(); // Add mybutton to mypanel mypanel.add(mybutton); // Add my panel to myapp myapp.add(mypanel); // Use the show() method on the Spreadsheet to display the UiApp object and all elements associated with it. mydoc.show(myapp); } Puede encadenar mtodos setter, que son mtodos que establecen los valores a los objetos. En el programa anterior, la instruccin var myApp = UiApp.createApplication( ). setTitle (Here is the title bar); crea un objeto UiApp y establece su ttulo. Usted tambin puede configurar el tamao del objeto: var myapp = UiApp . createApplication( ) . setTitle ( "Here is the title bar" ). setHeight ( 50 ). setWidth ( 100 ); Aqu hay otro pequeo script que muestra un panel, pero no hace nada ms. Muestra cmo utiliza el grid de objetos y el mtodo setWidget para crear un diseo ms complejo, tambin cmo crear cuadros de texto y la etiqueta de ellos. Se puede introducir texto en los cuadros de texto, pero al presionar el botn no hace nada. El tamao de la cuadrcula de 3 x 2 se define en la instruccin var myGrid = myapp.createGrid (3, 2), y cada mtodo setWidget define el elemento que se muestra
Google Apps Script 40

en cada posicin dentro de la cuadrcula. Tenga en cuenta las definiciones de la posicin al utilizar un ndice basado en cero, por lo que las filas se identifican con los nmeros 0, 1 y 2 en lugar de 1, 2 y 3. function demoUI() { var mydoc = SpreadsheetApp.getActiveSpreadsheet(); var myapp = UiApp.createApplication().setTitle('An improved GUI'); var mygrid = myapp.createGrid(3, 2); mygrid.setWidget(0, 0, myapp.createLabel('Name:')); mygrid.setWidget(0, 1, myapp.createTextBox()); mygrid.setWidget(1, 0, myapp.createLabel('Age:')); mygrid.setWidget(1, 1, myapp.createTextBox()); mygrid.setWidget(2, 0, myapp.createLabel('City')); mygrid.setWidget(2, 1, myapp.createTextBox()); var mybutton = myapp.createButton('Press me'); var mypanel = myapp.createVerticalPanel(); mypanel.add(mygrid); mypanel.add(mybutton); myapp.add(mypanel); mydoc.show(myapp); } d) La actualizacin de una hoja de clculo de la interfaz de usuario Los dos scripts en la seccin de Creacin de elementos de la interfaz de usuario muestran un panel con varios controles, pero no hacen nada ms. Para hacer una interfaz de usuario utilizable, necesita la capacidad de actualizar un Spreadsheet con la informacin que el usuario entra en la interfaz. He aqu un pequeo script que responde a una accin en la interfaz mediante la actualizacin del spreadsheet. Todo lo que hace es incrementar el valor de la celda A1 en 1 cada vez que haga clic en un botn. function foo() { var doc = SpreadsheetApp.getActiveSpreadsheet(); var app = UiApp.createApplication(); var button = app.createButton('submit'); app.add(button); var handler = app.createServerClickHandler('b'); button.addClickHandler(handler); doc.show(app); } function b() { var doc = SpreadsheetApp.getActiveSpreadsheet();

Google Apps Script

41

var cell = doc.getRange('a1'); cell.setValue(Number(cell.getValue()) + 1); var app = UiApp.getActiveApplication(); app.close(); // The following line is REQUIRED for the widget to actually close. return app; } Cuando se copia esto y se ejecuta en el Editor de Scripts, encontrar que tiene que volver a ejecutar la funcin para visualizar el panel con el botn por cada vez que lo presione. Eso es porque no hay una estructura de bucle en el script para mantener el panel mostrado y activo. En cambio, el panel desaparece cuando llega a las instrucciones app.close (); y return app; Ya est familiarizado con el cdigo de la funcin foo () de las secciones anteriores de esta gua. Las nuevas instrucciones son las siguientes: var handler = app.createServerClickHandler('b'); button.addClickHandler(handler); La instruccin var handler = app.createServerClickHandler ('b'); crea controlador del click del lado del server llamado handler como parte de la aplicacin UiApp llamada app. Un controlador (handler) de clic realiza una accin en respuesta a un clic de mouse. Del lado del servidor, significa que las acciones son realizadas por un servidor, en este caso, el servidor de Google Apps Script. El argumento ('b') significa que el controlador de accin se va a ejecutar la function B ( ).Usted puede agregar varios controladores (handlers) de clic, en un botn. Estos se ejecutan en paralelo. La instruccin button.addClickHandler (handler) asocia el controlador (handler) de clic con el objeto botn ya definido, llamado button. La segunda funcin en el script, b (), contiene las instrucciones que incrementan el valor de la celda A1, cierra la aplicacin app, y, finalmente, devuelve el script a su punto de partida. Aqu hay un script ms largo y complejo. Este script recoge algunos datos de los campos de texto en un panel y escribe la informacin en el spreadsheet. Vea los comentarios entre lneas para ms detalle. function foo() { var doc = SpreadsheetApp.getActiveSpreadsheet(); var app = UiApp.createApplication().setTitle('New form!'); // Create a grid with 3 text boxes and corresponding labels var grid = app.createGrid(3, 2); grid.setWidget(0, 0, app.createLabel('Name:'));

Google Apps Script

42

// Text entered in the text box is passed in to userName grid.setWidget(0, 1, app.createTextBox().setName('userName')); grid.setWidget(1, 0, app.createLabel('Age:')); grid.setWidget(1, 1, app.createTextBox().setName('age')); // Text entered in the text box is passed in to age grid.setWidget(2, 0, app.createLabel('City')); grid.setWidget(2, 1, app.createTextBox().setName('city')); // Text entered in the text box is passed in to city. // Create a vertical panel.. var panel = app.createVerticalPanel(); // ...and add the grid to the panel panel.add(grid); // Create a button and click handler; pass in the grid object as a callback element and the handler as a click handler // Identify the function b as the server click handler var button = app.createButton('submit'); var handler = app.createServerClickHandler('b'); handler.addCallbackElement(grid); button.addClickHandler(handler); // Add the button to the panel and the panel to the application, then display the application app in the Spreadsheet doc panel.add(button); app.add(panel); doc.show(app); } // Function that records the values in the Spreadsheet function b(e) { var doc = SpreadsheetApp.getActiveSpreadsheet(); var lastRow = doc.getLastRow(); // Determine the last row in the Spreadsheet that contains any values var cell = doc.getRange('a1').offset(lastRow, 0); // determine the next free cell in column A cell.setValue(e.parameter.userName); // Set the value of the cell to userName cell.offset(0, 1).setValue(e.parameter.age); // Set the value of the adjacent cell to age cell.offset(0, 2).setValue(e.parameter.city); // set the value of the next cell to city // Clean up - get the UiApp object, close it, and return var app = UiApp.getActiveApplication(); app.close(); // The following line is REQUIRED for the widget to actually close.

Google Apps Script

43

return app; } Aqu est el mismo script con funciones adicionales, que permiten al formulario ser utilizado mltiples veces antes que el usuario decida salir. Los comentarios entre lneas explican las nuevas instrucciones. function foo() { var doc = SpreadsheetApp.getActiveSpreadsheet(); var app = UiApp.createApplication().setTitle('form!'); // Create the entry form, a 3 x 2 grid with text boxes for name, age, and city that is then added to a vertical panel var grid = app.createGrid(3, 2); grid.setWidget(0, 0, app.createLabel('Name:')); grid.setWidget(0, 1, app.createTextBox().setName('userName').setId('userName')); grid.setWidget(1, 0, app.createLabel('Age:')); grid.setWidget(1, 1, app.createTextBox().setName('age').setId('age')); grid.setWidget(2, 0, app.createLabel('City')); grid.setWidget(2, 1, app.createTextBox().setName('city').setId('city')); // Create a vertical panel and add the grid to the panel var panel = app.createVerticalPanel(); panel.add(grid); // Here's where this script diverges from the previous script. // We create a horizontal panel called buttonPanel to hold two buttons, one for submitting the contents of the form // to the Spreadsheet, the other to close the form. var buttonPanel = app.createHorizontalPanel(); // Two buttons get added to buttonPanel: button (for submits) and closeButton (for closing the form) // For the submit button we create a server click handler submitHandler and pass submitHandler to the button as a click handler. // the function submit gets called when the submit button is clicked. var button = app.createButton('submit'); var submitHandler = app.createServerClickHandler('submit'); submitHandler.addCallbackElement(grid); button.addClickHandler(submitHandler); buttonPanel.add(button); // For the close button, we create a server click handler closeHandler and pass closeHandler to the close button as a click handler. // The function close is called when the close button is clicked. var closeButton = app.createButton('close'); var closeHandler = app.createServerClickHandler('close'); closeButton.addClickHandler(closeHandler); buttonPanel.add(closeButton); // Create label called statusLabel and make it invisible; add buttonPanel and
Google Apps Script 44

statusLabel to the main display panel. var statusLabel = app.createLabel().setId('status').setVisible(false); panel.add(statusLabel); panel.add(buttonPanel); app.add(panel); doc.show(app); } // Close everything return when the close button is clicked function close() { var app = UiApp.getActiveApplication(); app.close(); // The following line is REQUIRED for the widget to actually close. return app; } // function called when submit button is clicked function submit(e) { // Write the data in the text boxes back to the Spreadsheet var doc = SpreadsheetApp.getActiveSpreadsheet(); var lastRow = doc.getLastRow(); var cell = doc.getRange('a1').offset(lastRow, 0); cell.setValue(e.parameter.userName); cell.offset(0, 1).setValue(e.parameter.age); cell.offset(0, 2).setValue(e.parameter.city); // Clear the values from the text boxes so that new values can be entered var app = UiApp.getActiveApplication(); app.getElementById('userName').setValue(''); app.getElementById('age').setValue(''); app.getElementById('city').setValue(''); // Make the status line visible and tell the user the possible actions app.getElementById('status').setVisible(true).setText('User ' + e.parameter.userName + ' entered. To add another, type in the information and click submit. To exit, click close.'); return app; } e) Definiendo si la ejecucin de un script se realizar desde un Spreadsheet o como un servicio. Usted puede hacer que la interfaz de usuario de un script est disponible para los usuarios desde el interior de un Spreadsheet, de un Site o mediante la ejecucin por separado como un servicio. Esta seccin describe las diferencias y te dice cmo hacer la interfaz de usuario como un servicio. Tenga en cuenta lo siguiente al escribir un cdigo para mostrar una interfaz de usuario: Un script que ofrece una interfaz de usuario, independiente, debe invocar la funcin doGet (e) o la funcin doPost (e) para un envo de un formulario HTML.

Google Apps Script

45

Un script que provee la interfaz de usuario desde un spreadsheet invoca doc.show(aprox). La funcion doGet (e) toma el argumento e, pasando los argumentos para la interfaz de usuario. Despus de escribir el script, lo publica como un servicio. Durante el proceso de publicacin, se define quin tiene acceso al script. En un dominio de Google Apps, puede publicar el script, de manera que, solo usted tenga acceso o todos en el dominio lo tengan. En una cuenta de usuario de Google, puede publicar el script, de manera que, slo usted tenga acceso o que todo el mundo lo tenga. En los ejemplos en la seccin de Actualizacin de un spreadsheet de la interfaz de usuario, la interfaz de usuario se muestra en el spreadsheet donde se almacena el script. El siguiente cdigo define la forma en que la interfaz de usuario se muestra: function showGui( ) { var doc = SpreadsheetApp.getActiveSpreadsheet(); // create UiApp object named app var app = UiApp.createApplication().setTitle('my title'); // .... populate app with ui objecs ... // ..and display the UiApp object from the current spreadsheet doc.show(app); } Aqu est el cdigo esqueleto para la visualizacin de una interfaz de usuario como un servicio independiente: function doGet(e) { var app = UiApp.createApplication(); // .... populate app with ui objects here ... return app; } La siguiente tabla compara algunos aspectos de las dos formas de mostrar una interfaz de usuario.

Google Apps Script

46

Mtodo de visualizacin Pantalla dentro de un spreadsheet

Script se ejecuta como El usuario que ejecuta el script El autor del script

Autor facilita a los usuarios El acceso al spreadsheet

Script puede hacer Lo que el usuario puede hacer Lo que el autor puede hacer

Script tiene acceso a A lo que el usuario tiene acceso A lo que el autor tiene acceso

Mostrar como un servlet independiente

Un URL

f) Publicacin de un script como un servicio Para publicar un script como un servicio y ver el servicio que se ejecuta a partir de un spreadsheet, cumpla lo siguiente: En el Editor de secuencias de comandos, haga clic en Publicar > Publicar como servicio. Usted ver el siguiente cuadro de dilogo:

Elegir quin tiene acceso al servicio. Para restringir al acceso solo para usted, marque Permitir solo a m mismo (your_email_address) para utilizar esto. Para permitir a otros usuarios en el dominio, marque Solo otros miembros de your_domain lo usen. 1. 2. 3. 4. Marque Habilitar Servicio de la casilla de verificacin. Copia el URL que se muestra. Haga clic en Guardar. Pegue el URL en la barra de direcciones del navegador pulse Entrar o Recargar. Usted ve la interfaz de usuario definido por el script.

Las instrucciones siguientes, suponen que ya ha creado un script en su sitio.

Google Apps Script

47

Para insertar un gadget Apps Script en un sitio de Google y publicar el script como un servicio, haga lo siguiente: 1. Navegue al sitio. 2. Haga clic en Editar pgina. 3. Haga clic en Insertar > Apps Gadget Script. All, ver un cuadro de dilogo que le muestra las secuencias de comandos del sitio. 4. Escoja un script y haga clic en Seleccionar. Usted ver el panel de insercin de Gadget App Script. 5. Elija quin tendr acceso al servicio.
o Para restringir el acceso slo a usted, marque Permitir slo a m mismo

( your_email_address ) para utilizar este.

o Para permitir a otros usuarios en el dominio para tener acceso, marque Slo otros

miembros de your _domain ingresen a este servicio. 6. Para incluir un borde alrededor del gadget, marque la primera casilla. 7. Para modificar o incluir un ttulo, marque la segunda casilla y, opcionalmente, puede incluir un ttulo nuevo. 8. Opcionalmente, modifique las dimensiones predeterminadas del gadget. 9. En el cuadro de dilogo, haga clic en Guardar. 10. En la pgina Sitios, haga clic en Guardar. La pgina muestra el gadget y la salida del script. g) Google Apps Script & Google Web Toolkit Cuando se crean y muestran los elementos de la interfaz de usuario Google Apps Script, utilice el Google Web Toolkit (GWT). No es necesario estar familiarizado con GWT para utilizar este aspecto de Google Apps Script. Sin embargo, si est familiarizado con GWT, ya conoce los tipos de objetos que estn disponibles en Google Apps Script y cmo funcionan los setters. Por ejemplo, en la clase de cuadrcula GWT y tambin en Google Script Aplicaciones, puede llamar al mtodo setWidget de la siguiente manera: setWidget ( row , column , widget ); Hay algunas diferencias sintcticas entre GWT y la escritura de Google Apps. GWT sigue la sintaxis Java y Google Apps script generalmente sigue la sintaxis de JavaScript. Por ejemplo, aqu hay un cdigo GWT: Grid g = new Grid(rows, cols); g.setVisible(false); g.setHeight("100px");

Google Apps Script

48

Aqu estn las mismas instrucciones en Google Apps Script: var g = app.createGrid(rows, cols); g.setVisible(false); g.setHeight("100px"); Por cada objeto que GWT podra crear, utilice new XYZ en GWT. Google Apps Script tiene un mtodo equivalente: create XYZ. 1.2.6 GUI Builder Esta seccin contiene informacin bsica sobre la creacin de una interfaz de usuario en Apps Script usando el GUI Builder. a) Descripcin general de la GUI Builder La GUI Builder es una herramienta en el editor de Apps Script que permite a los usuarios armar una interfaz de usuario sin necesidad de escribir cdigo. Se trata de una alternativa al uso de los Servicios Ui. Usted ensambla la interfaz de usuario eligiendo los widgets, construyendo bloques de cualquier interfaz de usuario, desde la paleta de la interfaz de usuario y arrastrndolos a un panel central, llamado el canvas (lienzo). A continuacin, se modifican las propiedades de cada widget en el panel de propiedades. Una interfaz creada utilizando el GUI Builder solo puede ser utilizada por la script para la interfaz de usuario que fue creada. El Constructor de GUI se compone de tres partes. La barra lateral de la izquierda es la paleta de la interfaz de usuario (ver el diagrama abajo). La seccin principal es el Canvas disponible, donde la interfaz de widgets se ensambla. La seccin en el extremo derecho es el panel de propiedades.

Google Apps Script

49

Cuando los widgets son seleccionados en el canvas (lienzo), el panel de propiedades refleja las propiedades asociadas con los widgets. Los usuarios pueden utilizar este panel de propiedades para configurar cada widget. b) Apertura de la GUI Builder El Constructor de GUI es accedido desde el editor de Scripts. Se inicia el Editor de scripts mediante la apertura de un Spreadsheet existente o sitio, o creando un nuevo spreadsheet o sitio. Para iniciar el editor de script de un spreadsheet, seleccione Herramientas > Editor de Scripts > Archivo > Crear una interfaz de usuario. El constructor de interfaz grfica de usuario se abrir en una pestaa del navegador. c) Usar el GUI Builder Para montar una interfaz de usuario, arrastre un widget de la paleta de la interfaz de usuario al canvas. Esta paleta de la interfaz de usuario muestra los widgets de interfaz de usuario disponible. Para configurar un widget, seleccinelo en el canvas. A continuacin, modifique las propiedades mediante el panel de propiedades. d) Guardar una interfaz de usuario Para guardar la interfaz de usuario recin creada, haga clic en Guardar y d a la interfaz de usuario un nombre. Luego utilizar ese nombre cuando incluya la interfaz de usuario en su script. e) Insertar una interfaz de usuario en un Script Para incorporar una interfaz de usuario en un script, utilice el mtodo loadComponent (GUI_NAME) en una funcin. En el siguiente ejemplo, la interfaz de usuario MyGui se incorpora en el script. Para mostrar la interfaz de usuario independientemente, utilice return app, y publique el script como un servicio. function doGet() { var app = UiApp.createApplication(); app.add(app.loadComponent("MyGui")); return app; } Para mostrar la interfaz de usuario de un Spreadsheet. function myFunction() { var app = UiApp.createApplication(); app.add(app.loadComponent("MyGui")); SpreadsheetApp.getActiveSpreadsheet().show(app); }

Google Apps Script

50

f) Expandir la interfaz de usuario Usted puede fcilmente expandir y modificar la interfaz de usuario creada usando el GUI Builder. Luego de que cargue la interfaz de usuario usando app.loadComponent(...), agregue nuevos widgets y estilos. El siguiente ejemplo muestra cmo agregar nuevos widgets. function doGet() { var app = UiApp.createApplication(); app.add(app.loadComponent("MyGui")); var panel = app.getElementById("Panel1"); // use the widget's id from the builder with getElementById panel.add(app.createButton("a new button!")); return app; ,} 1.2.7 Modelo de seguridad Google Apps Script tiene un modelo de seguridad robusto para proteger sus datos que vamos a definir por los siguientes puntos: Un script que se ejecuta, solo puede acceder a la informacin en las aplicaciones de Google y servicios a los que tiene derechos de acceso. Por ejemplo, si usted tiene la posibilidad de colocar una entrada en el calendario de otra persona, su script ejecutada tambin puede colocar una entrada en el calendario de esa persona. Si usted no puede tener acceso al calendario de alguien, por ejemplo, si el calendario no se comparte con usted, su script ejecutada no puede colocar una entrada en el calendario de esa persona. Debe conceder, explcitamente, los derechos de acceso a cualquier script que al ejecutarse tenga acceso a cualquier aplicacin que contenga datos privados, por ejemplo, calendario y correo electrnico. Debe conceder, explcitamente, los derechos de acceso a cualquier script escrito por otra persona o compartido con usted. Por ejemplo, cuando hace una copia de un Spreadsheet que contiene un script. Una funcin no puede acceder a sus datos privados (por ejemplo, el Google Calendar), a menos que haya otorgado explcitamente los derechos. Funciones personalizadas y manejadoras de eventos simples que funcionan sin autorizacin no pueden acceder a todo lo que requerira una autorizacin. Todos los scripts que se agregan a un Spreadsheet tienen acceso al Spreadsheet, ya sea si se instalan de la Galera de Script o lo hagan por su propia cuenta utilizando el Editor de Script.

Google Apps Script

51

 Anlisis de Permisos y Ejecucin de Scripts La siguiente tabla describe las acciones que los individuos con niveles de permisos diferentes pueden realizar con respecto a una secuencia de comandos en un Spreadsheet.
Propietario de un script Propietario del Spreadsheet El propietario del Spreadsheet es la persona que cre el Spreadsheet, ya sea por empezar un nuevo Spreadsheet o hacer una copia de un Spreadsheet existente. Editor de Spreadsheet Un editor de Spreadsheet es alguien a quien el propietario del Spreadsheet le ha otorgado derechos de edicin. Espectador de Spreadsheet Un lector de Spreadsheet es alguien a quien el propietario del Spreadsheet ha concedido los derechos de visualizacin. Propietario del Script Un propietario de un Script es el propietario del Spreadsheet o el editor del Spreadsheet. Lector de un Script Editor de un script Ejecutar un script

Pueden crear nuevos scripts y luego ser el propietario de dichos scripts.

Scripts que el dueo del Spreadsheet es propietario. Scripts compartidos con el propietario del Spreadsheet por otros. Scripts que el Editor de Spreadsheet es propietario. Script compartido con el editor de Spreadsheet por otros.

Pueden crear nuevos scripts y luego ser el propietario de dichos scripts.

No puede crear nuevos scripts.

No

No

No

Propietario de los scripts que crea.

Solo las scripts del propietario de la script

Permisos para la ejecucin del Script Cuando un script se invoca haciendo clic en un elemento de men o una imagen, el script se ejecuta bajo la identidad de la persona que se ha registrado y ha hecho clic en el elemento de men o la imagen. Esta persona debe ser el propietario del Spreadsheet o el editor del mismo.
Google Apps Script 52

Las funciones personalizadas se ejecutan de forma annima, cuando el Spreadsheet se edita. Las funciones de scripts personalizados no tienen acceso a datos especficos del usuario. Por ejemplo, si un usuario cambia un valor en una celda donde hay una funcin personalizada, cuando el Spreadsheet se guarda, muestra que la revisin fue hecha por un usuario annimo. Permisos para la ejecucin de eventos Eventos simples, tales como onOpen, onEdit y onInstall se ejecutan bajo la identidad del usuario que opera el Spreadsheet. Eventos instalables (triggers de Spreadsheet) se ejecutan bajo la identidad del usuario que ha creado los triggers. Entendiendo la ejecucin de Time-Driven triggers Los time-driven triggers son privados. Para instalar un trigger, el usuario debe tener al menos permisos de slo lectura del script, es decir, el usuario debe ser capaz de abrir el script en el editor de script. Los triggers no pueden ser compartidos, independientemente de si el Script ha sido compartido o no. Cuando un script se activa, se ejecuta bajo la identidad del propietario del trigger, que es la persona que instal el trigger. Permisos para ejecutar un script como un servicio El propietario del Script tiene permiso exclusivo para publicar un script como un servicio. Un Script publicado como un servicio se ejecuta bajo la identidad del propietario del script. Asignar derechos de acceso Cuando se instala un nuevo script de la Galera de Scripts o se copia de un Spreadsheet que contiene un script que no escribi o ejecuta cualquier script por primera vez, incluidas las que usted escribi, se le pide expresamente dar al script el permiso de acceso a los servicios que est intentando utilizar. Usted ve el cuadro de dilogo de autorizacin de seguridad, que establece el nombre del Script, el propietario y los servicios a los que el script requiere el acceso:

Usted tambin podra ver el siguiente cuadro de dilogo, en el que el script solicita acceso a un servicio o una aplicacin especifica de Google:

Google Apps Script

53

Anulacin de los derechos de acceso Si el Script que escribi o ejecut se queda sin acceso a sus datos y requiere autorizacin para el acceso, se puede anular el acceso que script. Para revocar el acceso de un script, cumpla lo siguiente: 1. En el navegador, en el que est registrado con su cuenta Gmail de usuario o de dominio, vaya a Google.com. 2. En el men desplegable Configuracin o el etiquetado con su direccin de correo electrnico, haga clic en Configuracin de la cuenta de Google. 3. En la seccin Seguridad, haga clic en Cambiar sitios web autorizados. Ver una lista de sitios web autorizados que incluye un Script de Google Apps. 4. Haga clic en el enlace Revocar Acceso para cualquier Script cuya autorizacin desee revocar. a) Restricciones de seguridad en funciones personalizadas y controladores de eventos Los Scripts que escribe a travs de Google Apps Scripts pueden hacer todo tipo de cosas, pero no todas las funcionalidades estn disponibles en todas las circunstancias. Las funciones personalizadas son funciones que se ejecutan cada vez que un Spreadsheet se recalcula. Por ejemplo, el Script Oracle of Bacon discutido en el tutorial de XML utiliza la funcin personalizada = kb ( actor1 , actor2 ). Las funciones personalizadas pueden leer datos del Spreadsheet actual y pueden llamar a los servicios annimos como SOAP, UrlFetch y Traductor de Google. Un servicio no especfico es un servicio que no requiere credenciales de usuario para funcionar. Un servicio especfico del usuario es un servicio que est ligado a un determinado usuario, como Google Calendar. Los Servicios especficos del usuario pueden almacenar los datos privados, tales como el Calendar, o puede actuar como el usuario, en el envo de correo electrnico. Las funciones personalizadas y todos los controladores de eventos simples se ejecutan de manera silenciosa y no se les permite el acceso a los servicios especficos del usuario. Apps Script no permite que las funciones personalizadas puedan obtener
Google Apps Script 54

acceso a datos privados de un usuario, por ejemplo el Calendar, Gmail, o de los Sites. Las funciones personalizadas tampoco pueden escribir a otra Spreadsheet que no sea una con retorno de valor. Las funciones personalizadas solo pueden escribir en la celda en la que se colocan. La funcin onEdit funciona de manera similar a las funciones personalizadas. La funcin onEdit se ejecuta de manera silenciosa y el Google Apps Script no permite que la funcin onEdit tenga acceso a los datos del usuario. La funcin onEdit puede llamar a los servicios no especficos, tales como SOAP y UrlFetch. Adems, la funcin onEdit puede escribir en cualquier celda del Spreadsheet. Las funciones onOpen y onInstall tambin funcionan de manera silenciosa. Por lo general, estas funciones se utilizan slo para instalar los mens y opciones del men o para rellenar un Spreadsheet con datos o columnas o encabezados de filas. b) Uso de varias cuentas de Google Google Docs no permite utilizar varias cuentas de Google en el mismo navegador al mismo tiempo, ya sean cuentas pblicas de Gmail o cuentas de Google Apps. Usted podra encontrarse con un problema si sigue esta secuencia de acciones: 1. Que se conecte a una cuenta de Google, por ejemplo, account1@gmail.com. 2. Si abre un Spreadsheet e inicia el editor de script. Tanto el Script como el Spreadsheet indican que est conectado como account1. 3. Cierre el editor de Script y se desconecta de account1. 4. Se conecta con otra cuenta de Google, por ejemplo, account2@gmail.com. 5. Abra un Spreadsheet e inicie el editor de script. El Spreadsheet indica que est conectado como account2, pero el editor de script indica que est conectado como account1. 6. Guarda el script. En esta situacin, salga de la cuenta actual, borre las cookies de su navegador, y reinicie el navegador. Google Docs se comporta de esta manera cuando vuelva a entrar: Si usted vuelve a entrar utilizando account1, tiene acceso al Script guardado y es capaz de editarlo. Si usted vuelve a entrar utilizando account2, puede cargar el script guardado, pero no lo puede editar. El Script es propiedad de account1 y un candado aparece junto al Script. 1.2.8 Solucin de problemas y depuracin de scripts En esta seccin, se analizan algunas formas bsicas de solucionar los problemas que encuentre en sus Scripts.

Google Apps Script

55

Cuotas Google Apps Script impone cuotas a las diferentes acciones realizadas por los scripts. Por ejemplo, puede encontrarse con un lmite en el nmero de mensajes de correo electrnico que puede enviar su script. Si el script llega al lmite establecido por la cuota, aparecer un mensaje similar al siguiente: Service invoked too many times: email Las cuotas se establecen en diferentes niveles para usuario, dominio y cuentas de primer nivel. Las cuotas estn sujetas a cambio en cualquier momento sin previo aviso por Google. Si se encuentra con una cuota, y cree que en su caso se justifica un incremento en la cuota, por favor, pngase en contacto con el equipo de Google Apps script mediante el Google Apps Script Help Forum (Foro de ayuda de Google Apps Script). El equipo revisar su situacin y se contactar con usted. Interpretacin de mensajes de error Cuando Google Apps Script no es capaz de ejecutar un script, es usual ver un mensaje de error. Todos los mensajes de error incluyen la lnea de cdigo en el que se encontr el error y una breve descripcin del error en particular. En la mayora de los casos, el mensaje de error es fcil de entender y se refiere a un error concreto en el Script. Por ejemplo, considere el script de ejemplo para agregar un men personalizado y elementos de men de un Spreadsheet: function onOpen() { var ss = SpreadsheetApp.getActiveSpreadsheet(); var menuEntries = [ {name: "Surprise 1", functionName: "menuItem1"}, {name: "Surprise 2", functionName: "menuItem2"} ]; ss.addMenu("Surprises", menuEntries); } function menuItem1() { Browser.msgBox("You clicked Surprise 1 on the menu!"); } function menuItem2() { Browser.msgBox("Surprise! Surprise!") } Qu pasara si el script define el men antes de definir los elementos que aparecen en el men? La primera funcin sera la siguiente: function onOpen() { var ss = SpreadsheetApp.getActiveSpreadsheet(); ss.addMenu("Surprises", menuEntries); var menuEntries = [ {name: "Surprise 1", functionName: "menuItem1"}, {name: "Surprise 2", functionName: "menuItem2"} ]; }

Google Apps Script

56

La prxima vez que abra el Spreadsheet, el nuevo men, Surprises, nunca aparecer. Si se abre el Editor de secuencias de comandos, haga clic en Ejecutar > onOpen. De esta manera, aparecer un mensaje de error: Cannot find method addMenu(string,Undefined). (#3) El nmero al final, es el nmero de lnea donde Google Apps Scripts encuentra el error. El script no es capaz de ejecutar el mtodo addMenu porque el mtodo espera dos argumentos y el segundo argumento, menuEntries , no se define hasta la cuarta lnea del script. Es por eso que ss.addMenu ("Surprises", menuEntries); debe venir luego de la definicin de menuEntries en el script. Por lo general, el mensaje de error que ver ser fcil de entender. Algunos errores resultarn en un mensaje de error ms genrico como el siguiente: Server not available. o Server error occurred, please try again. Es inusual que un servidor de Google no est disponible. Si ve este mensaje, puede esperar unos minutos y ejecutar el script de nuevo. Si observa el mismo mensaje de error, probablemente, signifique que hay un error en el script, pero no corresponde a ningn mensaje de error especfico, por lo que est viendo un mensaje de error para todo propsito (genrico). En este punto, empiece a tratar de depurar el script. Puede avisar estos errores en el Foro de Google Apps Script. Para obtener ms informacin acerca de la depuracin de scripts, puede seguir revisando Troubleshooting and Debugging Scripts en enlaces de inters del curso.

1.3 Aplicaciones Apps Script

La seccin de tutoriales publicados dentro de la seccin de Google Apps Script en code.google.com, hacen referencia a describir por niveles diversos ejemplos que pueden describir un marco ms claro para todo aquel que est comenzando a desarrollar con Google Apps Script. Los niveles que presenta son:

Google Apps Script

57

Programando nuestros primero scripts. Funciones personalizadas. Definicin de Men en Spreadsheet. Envo de correos desde un Spreadsheet. UI services.

Lectura y escritura de datos de spreadsheets utilizando objetos de JS. Creacin de un Google Site. Interactuar con Documents Lists. Utilizando el depurador, etc.

Analisis de documentos con XML. Interactuando con Google App Engine Utilizacin de SOAP. Automatizacin de flujo de trabajo tipo Help Desk, etc.

Para ver los detalles de cada nivel, se sugiere acceder a la seccin de enlaces de inters del curso y revisar los tutoriales en mencin.

Google Apps Script

58