Class ServerHandler

Deprecated. The UI service was deprecated on December 11, 2014. To create user interfaces, use the HTML service instead.

An event handler that runs on the server. These will, in general, run much slower than ClientHandlers but they are not limited in what they can do.

Any method that accepts a "Handler" parameter can accept a ServerHandler.

When a ServerHandler is invoked, the function it refers to is called on the Apps Script server in a "fresh" script. This means that no variable values will have survived from previous handlers or from the initial script that loaded the app. Global variables in the script will be re-evaluated, which means that it's a bad idea to do anything slow (like opening a Spreadsheet or fetching a Calendar) in a global variable.

If you need to save state on the server, you can try using ScriptProperties or UserProperties. You can also add a Hidden field to your app storing the information you want to save and pass it back explicitly to handlers as a "callback element."

If you set validators on a ServerHandler, they will be checked before the handler calls the server. The server will only be called if the validators succeed.

If you have multiple ServerHandlers for the same event on the same widget, they will be called simultaneously.

Deprecated methods

Method	Return type	Brief description
`addCallbackElement(widget)`	`ServerHandler`	Adds a widget to this `ServerHandler` as a "callback element."
`getId()`	`String`	Returns the id that has been assigned to this object.
`getTag()`	`String`	Gets the text tag of this `ServerHandler`.
`getType()`	`String`	Gets the type of this object.
`setCallbackFunction(functionToInvoke)`	`ServerHandler`	Sets the name of the function to call when this handler is invoked.
`setId(id)`	`ServerHandler`	Sets the id of this `ServerHandler`.
`setTag(tag)`	`ServerHandler`	Sets the text tag of this `ServerHandler`.
`validateEmail(widget)`	`ServerHandler`	Sets this handler to fire only if the given widget's value is a valid email address.
`validateInteger(widget)`	`ServerHandler`	Sets this handler to fire only if the given widget's value can be interpreted as an integer.
`validateLength(widget, min, max)`	`ServerHandler`	Sets this handler to fire only if the given widget's value is a string whose length is between min and max.
`validateMatches(widget, pattern)`	`ServerHandler`	Sets this handler to fire only if the given widget's value matches this regular expression.
`validateMatches(widget, pattern, flags)`	`ServerHandler`	Sets this handler to fire only if the given widget's value matches this regular expression.
`validateNotEmail(widget)`	`ServerHandler`	Sets this handler to fire only if the given widget's value is not a valid email address.
`validateNotInteger(widget)`	`ServerHandler`	Sets this handler to fire only if the given widget's value cannot be interpreted as an integer.
`validateNotLength(widget, min, max)`	`ServerHandler`	Sets this handler to fire only if the given widget's value is a string whose length is less than min or greater than max.
`validateNotMatches(widget, pattern)`	`ServerHandler`	Sets this handler to fire only if the given widget's value does not match this regular expression.
`validateNotMatches(widget, pattern, flags)`	`ServerHandler`	Sets this handler to fire only if the given widget's value does not match this regular expression.
`validateNotNumber(widget)`	`ServerHandler`	Sets this handler to fire only if the given widget's value cannot be interpreted as an number.
`validateNotOptions(widget, options)`	`ServerHandler`	Sets this handler to fire only if the given widget's value is not one of the strings given in the options parameter.
`validateNotRange(widget, min, max)`	`ServerHandler`	Sets this handler to fire only if the given widget's value cannot be interpreted as a number that is between min and max.
`validateNotSum(widgets, sum)`	`ServerHandler`	Sets this handler to fire only if the given widgets have values that are not numbers, or that do not sum up to the given value.
`validateNumber(widget)`	`ServerHandler`	Sets this handler to fire only if the given widget's value can be interpreted as a number.
`validateOptions(widget, options)`	`ServerHandler`	Sets this handler to fire only if the given widget's value is one of the strings given in the options parameter.
`validateRange(widget, min, max)`	`ServerHandler`	Sets this handler to fire only if the given widget's value can be interpreted as a number and is between min and max.
`validateSum(widgets, sum)`	`ServerHandler`	Sets this handler to fire only if the given widgets have values that are numbers and sum up to the given value.

Deprecated methods

`addCallbackElement(widget)`

Deprecated. This function is deprecated and should not be used in new scripts.

Adds a widget to this ServerHandler as a "callback element."

When a ServerHandler is called, any widgets added here, as well as any current child widgets of those widgets, are considered as callback elements. The value of each of these widgets is added to the information sent to the script processing the event, as long as the following two conditions are met:

The callback element has a "setName" method.
A name has been set.

Note in particular that setName and setId are not the same thing.

Here is an example of how this can be used:

 

 function doGet() {
   var app = UiApp.createApplication();
   var textBox1 = app.createTextBox().setName("textBox1");
   var textBox2 = app.createTextBox().setId("textBox2");
   app.add(textBox1);
   app.add(textBox2);
   var textBox3 = app.createTextBox().setName("textBox3");
   var panel = app.createFlowPanel();
   panel.add(textBox3);
   app.add(panel);
   var button = app.createButton("a button");
   var handler = app.createServerHandler("handlerFunction");
   handler.addCallbackElement(textBox1)
       .addCallbackElement(textBox2)
       .addCallbackElement(panel)
   button.addClickHandler(handler);
   app.add(button);
   return app;
 }

 function handlerFunction(eventInfo) {
   var parameter = eventInfo.parameter;
   // There's a lot of information in 'parameter' about the event too, but we'll focus here
   // only on the callback elements.
   var textBox1 = parameter.textBox1;  // the value of textBox1
   var textBox2 = parameter.textBox2;  // undefined! setId is not the same as setName
   var textBox3 = parameter.textBox3;  // works! the parent "panel" was a callback element
 }

Parameters

Name	Type	Description
`widget`	`Widget`	the callback element.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`getId()`

Deprecated. This function is deprecated and should not be used in new scripts.

Returns the id that has been assigned to this object.

This can be used in conjunction with app.getElementById() to retrieve a reference to this object.

Return

String — the id that has been assigned to this object

`getTag()`

Deprecated. This function is deprecated and should not be used in new scripts.

Gets the text tag of this ServerHandler.

Return

String — the text tag.

`getType()`

Deprecated. This function is deprecated and should not be used in new scripts.

Gets the type of this object.

Return

String — the object type

`setCallbackFunction(functionToInvoke)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets the name of the function to call when this handler is invoked.

Parameters

Name	Type	Description
`functionToInvoke`	`String`	the name of the function to call.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`setId(id)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets the id of this ServerHandler.

Parameters

Name	Type	Description
`id`	`String`	the new id, which can be used to retrieve the `ServerHandler` from app.getElementById(id).

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`setTag(tag)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets the text tag of this ServerHandler.

Parameters

Name	Type	Description
`tag`	`String`	the new text tag, which can be anything you wish to store with the widget.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateEmail(widget)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value is a valid email address. This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateInteger(widget)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value can be interpreted as an integer.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateLength(widget, min, max)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value is a string whose length is between min and max.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`min`	`Integer`	the minimum length. If null, no minimum is enforced.
`max`	`Integer`	the maximum length. If null, no maximum is enforced.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateMatches(widget, pattern)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value matches this regular expression.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`pattern`	`String`	the regex to test, as a string.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateMatches(widget, pattern, flags)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value matches this regular expression.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`pattern`	`String`	the regex to test, as a string.
`flags`	`String`	regex flags. The only valid characters in this string are 'g', 'm', and 'i'.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNotEmail(widget)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value is not a valid email address.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNotInteger(widget)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value cannot be interpreted as an integer.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNotLength(widget, min, max)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value is a string whose length is less than min or greater than max.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`min`	`Integer`	the minimum length. If null, no minimum is enforced.
`max`	`Integer`	the maximum length. If null, no maximum is enforced.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNotMatches(widget, pattern)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value does not match this regular expression.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`pattern`	`String`	the regex to test, as a string.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNotMatches(widget, pattern, flags)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value does not match this regular expression.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`pattern`	`String`	the regex to test, as a string.
`flags`	`String`	regex flags. The only valid characters in this string are 'g', 'm', and 'i'.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNotNumber(widget)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value cannot be interpreted as an number.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNotOptions(widget, options)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value is not one of the strings given in the options parameter.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`options`	`String[]`	the list of unacceptable values

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNotRange(widget, min, max)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value cannot be interpreted as a number that is between min and max.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`min`	`Number`	the minimum length. If null, no minimum is enforced.
`max`	`Number`	the maximum length. If null, no maximum is enforced.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNotSum(widgets, sum)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widgets have values that are not numbers, or that do not sum up to the given value.

This will cause an error if any of the widgets do not have a text property.

Parameters

Name	Type	Description
`widgets`	`Widget[]`	an array of the widgets to validate on.
`sum`	`Integer`	the sum to validate with

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateNumber(widget)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value can be interpreted as a number.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateOptions(widget, options)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value is one of the strings given in the options parameter.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`options`	`String[]`	the list of acceptable values

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateRange(widget, min, max)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widget's value can be interpreted as a number and is between min and max.

This will cause an error if the widget does not have a text property.

Parameters

Name	Type	Description
`widget`	`Widget`	the widget to validate on.
`min`	`Number`	the minimum length. If null, no minimum is enforced.
`max`	`Number`	the maximum length. If null, no maximum is enforced.

Return

ServerHandler — the ServerHandler itself, useful for chaining.

`validateSum(widgets, sum)`

Deprecated. This function is deprecated and should not be used in new scripts.

Sets this handler to fire only if the given widgets have values that are numbers and sum up to the given value.

This will cause an error if any of the widgets do not have a text property.

Parameters

Name	Type	Description
`widgets`	`Widget[]`	an array of the widgets to validate on.
`sum`	`Integer`	the sum to validate with

Return

ServerHandler — the ServerHandler itself, useful for chaining.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Last updated February 26, 2015.