HTML Service: Communicate with Server Functions (original) (raw)

google.script.run is an asynchronous client-side JavaScript API that allows HTML-service pages to call server-side Apps Script functions. The following example shows the most basic functionality of google.script.run —calling a function on the serverfrom client-side JavaScript.

Code.gs

function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }

function doSomething() { Logger.log('I was called!'); }

Index.html

If you deploy this script as a web app and visit its URL, you won’t see anything, but if you view the logs, you'll see that the server functiondoSomething() was called.

Client-side calls to server-side functions are asynchronous: after the browser requests that the server run the function doSomething(), the browser continues immediately to the next line of code without waiting for a response. This means that server function calls may not execute in the order you expect. If you make two function calls at the same time, there is no way to know which function will run first; the result may differ each time you load the page. In this situation,success handlers and failure handlershelp control the flow of your code.

The google.script.run API allows 10 concurrent calls to server functions. If you make an 11th call while 10 are still running, the server function will be delayed until one of the 10 spots is freed. In practice, you should rarely have to think about this restriction, especially since most browsers already limit the number of concurrent requests to the same server at a number lower than 10. In Firefox, for example, the limit is 6. Most browsers similarly delay excess server requests until one of the existing requests has completed.

Parameters and return values

You can call a server function with parameters from the client. Similarly, a server function can return a value to the client as a parameter passed to asuccess handler.

Legal parameters and return values are JavaScript primitives like a Number,Boolean, String, or null, as well as JavaScript objects and arrays that are composed of primitives, objects and arrays. A form element within the page is also legal as a parameter, but it must be the function’s only parameter, and it is not legal as a return value. Requests fail if you attempt to pass aDate, Function, DOM element besides a form, or other prohibited type, including prohibited types inside objects or arrays. Objects that create circular references will also fail, and undefined fields within arrays becomenull.

Note that an object passed to the server becomes a copy of the original. If a server function receives an object and changes its properties, the properties on the client are not affected.

Success handlers

Because client-side code continues to the next line without waiting for a server call to complete,withSuccessHandler(function)allows you to specify a client-side callback function to run when the server responds. If the server function returns a value, the API passes the value to the new function as a parameter.

The following example displays a browser alert when the server responds. Note that this code sample requires authorization because the server-side function is accessing your Gmail account. The simplest way to authorize the script is to run the getUnreadEmails() function manually from the script editor once before you load the page. Alternately, when youdeploy the web app, you can choose to execute it as the “user accessing the web app,” in which case you will be prompted for authorization when you load the app.

Code.gs

function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }

function getUnreadEmails() { return GmailApp.getInboxUnreadCount(); }

Index.html

Forms

If you call a server function with a form element as a parameter, the form becomes a single object with field names as keys and field values as values. The values are all converted to strings, except for the contents of file-input fields, which become Blob objects.

This example processes a form, including a file-input field, without reloading the page; it uploads the file to Google Drive and then prints the URL for the file in the client-side page. Inside the onsubmit handler, the keyword thisrefers to the form itself. Note that upon loading all forms in the page have the default submit action disabled by preventFormSubmit. This prevents the page from redirecting to an inaccurate URL in the event of an exception.

Code.gs

function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }

function processForm(formObject) { var formBlob = formObject.myFile; var driveFile = DriveApp.createFile(formBlob); return driveFile.getUrl(); }

Index.html