Google Apps Script

Class ClientHandler

An event handler that runs in the user's browser without needing a call back to the server. These will, in general, run much faster than ServerHandlers but they are also more limited in what they can do.

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

If you set validators on a ClientHandler, they will be checked before the handler performs its actions. The actions will only be performed if the validators succeed.

If you have multiple ClientHandlers for the same event on the same widget, they will perform their actions in the order that they were added.

An example of using client handlers:

 
function doGet() {
   var app = UiApp.createApplication();
   var button = app.createButton("Say Hello");

   // Create a label with the "Hello World!" text and hide it for now
   var label = app.createLabel("Hello World!").setVisible(false);

   // Create a new handler that does not require the server.
   // We give the handler two actions to perform on different targets.
   // The first action disables the widget that invokes the handler
   // and the second displays the label.
   var handler = app.createClientHandler()
     .forEventSource().setEnabled(false)
     .forTargets(label).setVisible(true);

   // Add our new handler to be invoked when the button is clicked
   button.addClickHandler(handler);

   app.add(button);
   app.add(label);
   return app;
 }
 

Methods

MethodReturn typeBrief description
forEventSource()ClientHandlerSets the target of this handler for subsequent directives to be whatever widget triggered the event that this handler was called for.
forTargets(widgets)ClientHandlerSets the target of this handler for subsequent directives to be the given widgets.
getId()StringReturns the id that has been assigned to this object.
getTag()StringGets the text tag of this ClientHandler.
getType()StringGets the type of this object.
setEnabled(enabled)ClientHandlerA directive to set the enabled/disabled state of the widgets this handler is targeted to.
setHTML(html)ClientHandlerA directive to set the html text of the widgets this handler is targeted to.
setId(id)ClientHandlerSets the id of this ClientHandler.
setStyleAttribute(row, column, attribute, value)ClientHandlerA directive to set a style attribute on a grid element.
setStyleAttribute(attribute, value)ClientHandlerA directive to set a style attribute on the widgets the handler is targeted to.
setStyleAttributes(row, column, attributes)ClientHandlerA directive to set multiple style attributes on a grid element.
setStyleAttributes(attributes)ClientHandlerA directive to set multiple style attributes on the widgets the handler is targeted to.
setTag(tag)ClientHandlerSets the text tag of this ClientHandler.
setText(text)ClientHandlerA directive to set the text of the widgets this handler is targeted to.
setValue(value)ClientHandlerA directive to set the boolean value of the widgets this handler is targeted to.
setVisible(visible)ClientHandlerA directive to set the visibility of the widgets this handler is targeted to.
validateEmail(widget)ClientHandlerSets this handler to fire only if the given widget's value is a valid email address.
validateInteger(widget)ClientHandlerSets this handler to fire only if the given widget's value can be interpreted as an integer.
validateLength(widget, min, max)ClientHandlerSets this handler to fire only if the given widget's value is a string whose length is between min and max.
validateMatches(widget, pattern)ClientHandlerSets this handler to fire only if the given widget's value matches this regular expression.
validateMatches(widget, pattern, flags)ClientHandlerSets this handler to fire only if the given widget's value matches this regular expression.
validateNotEmail(widget)ClientHandlerSets this handler to fire only if the given widget's value is not a valid email address.
validateNotInteger(widget)ClientHandlerSets this handler to fire only if the given widget's value cannot be interpreted as an integer.
validateNotLength(widget, min, max)ClientHandlerSets 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)ClientHandlerSets this handler to fire only if the given widget's value does not match this regular expression.
validateNotMatches(widget, pattern, flags)ClientHandlerSets this handler to fire only if the given widget's value does not match this regular expression.
validateNotNumber(widget)ClientHandlerSets this handler to fire only if the given widget's value cannot be interpreted as an number.
validateNotOptions(widget, options)ClientHandlerSets 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)ClientHandlerSets 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)ClientHandlerSets 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)ClientHandlerSets this handler to fire only if the given widget's value can be interpreted as a number.
validateOptions(widget, options)ClientHandlerSets 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)ClientHandlerSets 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)ClientHandlerSets this handler to fire only if the given widgets have values that are numbers and sum up to the given value.

Detailed documentation

forEventSource()

Sets the target of this handler for subsequent directives to be whatever widget triggered the event that this handler was called for. This does not change the target for any previous directives.

Return

ClientHandler — the ClientHandler itself, useful for chaining.


forTargets(widgets)

Sets the target of this handler for subsequent directives to be the given widgets. This does not change the target for any previous directives.

Parameters

NameTypeDescription
widgetsObject...the widgets to target.

Return

ClientHandler — the ClientHandler 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 ClientHandler.

Return

String — the text tag.


getType()

Gets the type of this object.

Return

String — the object type


setEnabled(enabled)

A directive to set the enabled/disabled state of the widgets this handler is targeted to. This will fail if the widgets being targeted do not support being enabled or disabled.

Parameters

NameTypeDescription
enabledBooleanwhether the targeted widgets should be enabled.

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setHTML(html)

A directive to set the html text of the widgets this handler is targeted to. This will fail if the widgets being targeted do not support having html text set.

Parameters

NameTypeDescription
htmlStringthe new html text for the targeted widgets.

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setId(id)

Sets the id of this ClientHandler.

Parameters

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

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setStyleAttribute(row, column, attribute, value)

A directive to set a style attribute on a grid element. This will fail if the widgets the handler is targeted to are not grids.

Parameters

NameTypeDescription
rowIntegerthe row of the grid.
columnIntegerthe column of the grid.
attributeStringthe CSS attribute to set. Use camelCase (e.g. fontSize, not font-size).
valueStringthe CSS value to set.

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setStyleAttribute(attribute, value)

A directive to set a style attribute on the widgets the handler is targeted to.

Parameters

NameTypeDescription
attributeStringthe CSS attribute to set. Use camelCase (e.g. fontSize, not font-size).
valueStringthe CSS value to set.

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setStyleAttributes(row, column, attributes)

A directive to set multiple style attributes on a grid element. This will fail if the widgets the handler is targeted to are not grids.

Parameters

NameTypeDescription
rowIntegerthe row of the grid.
columnIntegerthe column of the grid.
attributesObjectthe CSS attributes and values to set.

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setStyleAttributes(attributes)

A directive to set multiple style attributes on the widgets the handler is targeted to.

Parameters

NameTypeDescription
attributesObjectthe CSS attributes and values to set.

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setTag(tag)

Sets the text tag of this ClientHandler.

Parameters

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

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setText(text)

A directive to set the text of the widgets this handler is targeted to. This will fail if the widgets being targeted do not support having their text set.

Parameters

NameTypeDescription
textStringthe new text for the targeted widgets.

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setValue(value)

A directive to set the boolean value of the widgets this handler is targeted to. This will fail if the widgets being targeted do not support having a boolean value set.

Parameters

NameTypeDescription
valueBooleanthe new value for the targeted widgets.

Return

ClientHandler — the ClientHandler itself, useful for chaining.


setVisible(visible)

A directive to set the visibility of the widgets this handler is targeted to. This will fail if the widgets being targeted do not support being made invisible.

Parameters

NameTypeDescription
visibleBooleanwhether the targeted widgets should be visible.

Return

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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

ClientHandler — the ClientHandler 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.