Google Apps Script

Class ServerHandler

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.

Methods

MethodReturn typeBrief description
addCallbackElement(widget)ServerHandlerAdds a widget to this ServerHandler as a "callback element."
getId()StringReturns the id that has been assigned to this object.
getTag()StringGets the text tag of this ServerHandler.
getType()StringGets the type of this object.
setCallbackFunction(functionToInvoke)ServerHandlerSets the name of the function to call when this handler is invoked.
setId(id)ServerHandlerSets the id of this ServerHandler.
setTag(tag)ServerHandlerSets the text tag of this ServerHandler.
validateEmail(widget)ServerHandlerSets this handler to fire only if the given widget's value is a valid email address.
validateInteger(widget)ServerHandlerSets this handler to fire only if the given widget's value can be interpreted as an integer.
validateLength(widget, min, max)ServerHandlerSets this handler to fire only if the given widget's value is a string whose length is between min and max.
validateMatches(widget, pattern)ServerHandlerSets this handler to fire only if the given widget's value matches this regular expression.
validateMatches(widget, pattern, flags)ServerHandlerSets this handler to fire only if the given widget's value matches this regular expression.
validateNotEmail(widget)ServerHandlerSets this handler to fire only if the given widget's value is not a valid email address.
validateNotInteger(widget)ServerHandlerSets this handler to fire only if the given widget's value cannot be interpreted as an integer.
validateNotLength(widget, min, max)ServerHandlerSets 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)ServerHandlerSets this handler to fire only if the given widget's value does not match this regular expression.
validateNotMatches(widget, pattern, flags)ServerHandlerSets this handler to fire only if the given widget's value does not match this regular expression.
validateNotNumber(widget)ServerHandlerSets this handler to fire only if the given widget's value cannot be interpreted as an number.
validateNotOptions(widget, options)ServerHandlerSets 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)ServerHandlerSets 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)ServerHandlerSets 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)ServerHandlerSets this handler to fire only if the given widget's value can be interpreted as a number.
validateOptions(widget, options)ServerHandlerSets 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)ServerHandlerSets 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)ServerHandlerSets this handler to fire only if the given widgets have values that are numbers and sum up to the given value.

Detailed documentation

addCallbackElement(widget)

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

NameTypeDescription
widgetWidgetthe callback element.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


getId()

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

Gets the text tag of this ServerHandler.

Return

String — the text tag.


getType()

Gets the type of this object.

Return

String — the object type


setCallbackFunction(functionToInvoke)

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

Parameters

NameTypeDescription
functionToInvokeStringthe name of the function to call.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


setId(id)

Sets the id of this ServerHandler.

Parameters

NameTypeDescription
idStringthe new id, which can be used to retrieve the ServerHandler from app.getElementById(id).

Return

ServerHandler — the ServerHandler itself, useful for chaining.


setTag(tag)

Sets the text tag of this ServerHandler.

Parameters

NameTypeDescription
tagStringthe new text tag, which can be anything you wish to store with the widget.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateEmail(widget)

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

NameTypeDescription
widgetWidgetthe widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateInteger(widget)

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

NameTypeDescription
widgetWidgetthe widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateLength(widget, min, max)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
minIntegerthe minimum length. If null, no minimum is enforced.
maxIntegerthe maximum length. If null, no maximum is enforced.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateMatches(widget, pattern)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
patternStringthe regex to test, as a string.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateMatches(widget, pattern, flags)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
patternStringthe regex to test, as a string.
flagsStringregex flags. The only valid characters in this string are 'g', 'm', and 'i'.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNotEmail(widget)

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

NameTypeDescription
widgetWidgetthe widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNotInteger(widget)

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

NameTypeDescription
widgetWidgetthe widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNotLength(widget, min, max)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
minIntegerthe minimum length. If null, no minimum is enforced.
maxIntegerthe maximum length. If null, no maximum is enforced.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNotMatches(widget, pattern)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
patternStringthe regex to test, as a string.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNotMatches(widget, pattern, flags)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
patternStringthe regex to test, as a string.
flagsStringregex flags. The only valid characters in this string are 'g', 'm', and 'i'.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNotNumber(widget)

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

NameTypeDescription
widgetWidgetthe widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNotOptions(widget, options)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
optionsString[]the list of unacceptable values

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNotRange(widget, min, max)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
minNumberthe minimum length. If null, no minimum is enforced.
maxNumberthe maximum length. If null, no maximum is enforced.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNotSum(widgets, sum)

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

NameTypeDescription
widgetsWidget[]an array of the widgets to validate on.
sumIntegerthe sum to validate with

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateNumber(widget)

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

NameTypeDescription
widgetWidgetthe widget to validate on.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateOptions(widget, options)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
optionsString[]the list of acceptable values

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateRange(widget, min, max)

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

NameTypeDescription
widgetWidgetthe widget to validate on.
minNumberthe minimum length. If null, no minimum is enforced.
maxNumberthe maximum length. If null, no maximum is enforced.

Return

ServerHandler — the ServerHandler itself, useful for chaining.


validateSum(widgets, sum)

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

NameTypeDescription
widgetsWidget[]an array of the widgets to validate on.
sumIntegerthe sum to validate with

Return

ServerHandler — the ServerHandler itself, useful for chaining.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.