ホーム ガイド Samples and Templates リファレンス サポート

App Maker Client API - Widgets

Accordion

A ListPanel with a 'detailed view' that expands below the selected row. This detailed view is edited as a prototype, like the main row view.

During runtime, one row is shown per item in the Accordion's datasource. The datasource for that row is a special single item datasource pointing to the corresponding item in the Accordion's datasource. The detail row is also given this special datasource. This allows the prototype row to access the current row's item with the @datasource.item syntax.

Styles

Name Description
.app-Accordion The primary style for the accordion widget.
.app-AccordionRow Style for every row of the accordion.
.app-AccordionRow.selected Style for the selected row.
.app-AccordionDetail Style for the 'detailed view' section of the selected row.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
children PropertyMap The direct children of this Layout widget, identified by their names.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
descendants PropertyMap All the children of this Layout widget recursively, identified by their names. This excludes any repeated children, such as rows in a List, cells in a Grid, Accordion, and their content.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
selectedIndex number The index of the selected row.
selectedRow LayoutWidget The selected row widget.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether all the children have a true valid property or no valid property. This can often be used in forms to determine whether all the input widgets in a form have valid values.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focusFirstWidget() undefined

Focuses the first focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusFirstWidget();
focusLastWidget() undefined

Focuses the last focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusLastWidget();
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onSelectedIndexChange(
  widget:Widget,
  newIndex:number)		 This script will run on the client whenever the selectedIndex property of this widget changes. The widget can be referenced using parameter widget and the new index is stored in newIndex.
onSelectedIndexEdit(
  widget:Widget,
  newIndex:number)		 This script will run on the client whenever the selection of this widget is changed by the user (for example by clicking on a row). The widget can be referenced using parameter widget and the new selected index is stored in newIndex. Unlike onSelectedIndexChange(), this runs only when a user changes the selected row; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

BarChart

A widget which displays its data as bar chart.

The first column contains a list of labels for the x-axis of the chart. Every additional column is a list of numbers to show on the bar chart. Example use:

Say you have a model that represents the total budget for a given year, and you wanted a chart showing the budget history. You can create a bar chart, bind the first column's (the label column) data property to @datasource.items.year and the second column (the data column) data property to @datasource.items.budget. This will show a chart with one bar for every item in your datasource, using the year field as a label, and the budget field as the length of the bar. You can add additional columns to chart more data against the same Y axis, so for example you might add another column and bind its data property to @datasource.items.revenue to add total revenue for that year to this chart, alongside the budget.

Styles

Name Description
.app-BarChart The primary style for the bar chart.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
chartAreaHeight string The relative size of the chart itself. Setting this to a value of 50% will allocate 50% of the overall canvas to the chart and 50% to the legend, if the legend is in the top or bottom position. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartAreaLeft string The position or percentage of the upper left corner of the chart. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartAreaTop string The position or percentage of the upper left corner of the chart. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartAreaWidth string The relative size of the chart itself. Setting this to a value of 50% will allocate 50% of the overall canvas to the chart and 50% to the legend, if the legend is in the left or right position. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartColors string[] An array of colors to display in this chart. The exact meaning differs based on the type of chart. Each element in the array is an html color string, for example ['red','#004411'].
chartTitle string The title to display above this chart.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
columns PropertyMap A PropertyMap of all the ChartColumns this chart has, by the chart name. For example, assuming you have a chart variable chart, to access a column named "Rabbits" you'd use the expression chart.columns.Rabbits.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
isStacked boolean If set to true, extra columns of data are stacked, rather than placed side by side.
legendPosition string Position of the legend. Can be one of the following:
  • 'right' - To the right of the chart.
  • 'left' - To the left of the chart.
  • 'top' - Above the chart.
  • 'bottom' - Below the chart.
  • 'none' - No legend is displayed.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
vertical boolean If set to true the bars grow upward, otherwise they grow rightward.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
getChartJs() object

Returns the underlying JavaScript Google Visualization object used by this chart. Standard methods for this object are specified here. This method (as well as getDataTableJs() and getOptionsJs()) are exposed to allow you to take advantage of advanced uses of the Google Visualization API. Whenever possible you should prefer to use the App Maker property system the chart inspector (in the Property Editor) to modify chart data and options.

If you want to add a custom event handler to the table you can use getChartJs() in onAttach event, for example: 

 var chart = widget.getChartJs();
 google.visualization.events.addListener(chart, 'select', function() {
   alert('Something was selected!');
 });
getDataTableJs() DataTable

Returns the Google Visualization API Data Table object used by this chart. Note that editing this directly can cause inconsistency between the "data" property on this charts columns and the actual underlying data being shown.

Note that when you update the data table, you'll likely want to redraw the chart. You can manually call redraw() method after updating the data table.

If you want to customize your data output using Formatters you can use getDataTableJs() in onDataLoad event, for example: 

 var data = widget.getDataTableJs();
 var formatter = new google.visualization.PatternFormat('{0}');
 formatter.format(data, [0]);

See the Google Visualization documentation for drawing for more information on using data tables and options.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
getOptionsJs() Options

Returns the Google Visualization API object which represents the options for your bar chart. Read more about bar chart options here. Note that editing this directly won't fire property change events for existing App Maker options, so you should prefer to use App Maker whenever possible, and only rely on this when App Maker doesn't provide the option you need.

Note that when you update the options, you'll likely want to redraw the chart so the options will be displayed. You can manually call redraw() method after updating the options.

If you want to customize options before chart is displayed on UI you can use getOptionsJs() in onAttach event.

See the Google Visualization documentation for drawing for more information on using data tables and options.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

Button

A simple push button.

Styles

Name Description
.app-Button The primary style for the button.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
text string HTML text field of this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onClick(
  widget:Widget,
  event:object)		 This script will run on the client whenever this widget is clicked. The widget can be referenced using parameter widget and the JavaScript click event is stored in event. Entering this code app.showPage(app.pages.NameOfPage) would navigate to the named page whenever this widget is clicked.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

ChartColumn

A column in a Chart, the exact meaning can change based on the chart type, but the first column is usually a label column with the data being strings to able chart items, subsequent columns are data for the chart.

Properties

Name Type Description
allowUnsafeHtml boolean Disables HTML sanitization allowing a potentially dangerous HTML markup like scripts, applets, frames, etc.

Note: It is advisable to keep this property disabled to allow only safe HTML. If an unsafe html is allowed and user input can affect the html property of the widget, it can lead to a cross-site scripting (XSS) attack.

Note: This property is only available on string columns of table charts.
data Dynamic[] List of data displayed by this column. Note that the length of data should be the same for every column in a chart.
name string The name of this column. Used as the columns property name when being accessed through scripting. For example, if the name is FooBar, to access the column in scripting you'd use chart.columns.FooBar.
title string The title or label of this column.
visible boolean True if the column is visible, false otherwise.

Back to Top

Checkbox

A checkbox component.

Styles

Name Description
.app-Checkbox The primary style for an outer panel around the check box.
.app-Checkbox.disabled Style for the widget when it is disabled.
.app-Checkbox.focus Style for the widget when it has focus.
.app-Checkbox.invalid Style for the widget when it has a validation error.
.app-Checkbox-Label Style for the label.
.app-Checkbox-Input Style for the inner check box.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value boolean The current value of this widget. Corresponds to the HTML value field.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onValueChange(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value property of this widget changes. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

DateBox

A text box that when entered pops up a date picker.

Styles

Name Description
.app-DateBox The primary style for an outer panel around the date box.
.app-DateBox.disabled Style for the widget when it is disabled.
.app-DateBox.focus Style for the widget when it has focus.
.app-DateBox.invalid Style for the widget when it has a validation error.
.app-DateBox-Label Style for the label.
.app-DateBox-Input Style for the inner input box.
.app-DateBox-Popup The primary style of the date picker popup.
.app-DateBox-Button Style for the calendar icon button.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
format string A pattern describing how dates should be formatted in the text box. The pattern used is defined by the GWT DateTimeFormat class. The pattern must include the year, day, and month and nothing else. Otherwise there may be inconsistencies when the date picker is used since the date picker only specifies the year, month, and day.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
loaded boolean Whether the widget has been attached to the DOM.
maxValue date The maximum value of the date inclusive.
minValue date The minimum value of the date inclusive.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
placeholder string Placeholder text to show when there is no value to show. For example, "Enter full email address" for a field meant to contain an email address.
required boolean Whether a value is required or it can be missing.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value date The current value of this widget. Corresponds to the HTML value field.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onValueChange(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value property of this widget changes. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

DrivePicker

A widget that uses the Google Picker API to show a file selection dialog.

Styles

Name Description
.app-DrivePicker The primary style for the Drive picker button.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
dialogTitle string The title of the picker dialog.
enabled boolean Whether the widget allows the user to change its value.
features string[] Specifies the features for the picker. For a complete description of each feature see Picker Reference - Feature.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
selectedDocId string The ID of the selected document. Pass this ID to DriveApp.getFileById() to perform operations on the file. This property is set after the user selects the document using the picker dialog.

Note that if the user selects more than one document, this value will only point to the first selected document (in case the Multiple Select Feature is enabled). To get all selected documents, either use the selectDocuments property or respond to the onDocumentSelect event.
selectedDocName string The name of the selected document. This property is set after the user selects the document using the picker dialog.

Note that if the user selects more than one document, this value will only point to the first selected document (in case the Multiple Select Feature is enabled). To get all selected documents, either use the selectDocuments property or respond to the onDocumentSelect event.
selectedDocUrl string A URL of the selected document. This property is set after the user selects the document using the picker dialog.

Note that if the user selects more than one document, this value will only point to the first selected document (in case the Multiple Select Feature is enabled). To get all selected documents, either use the selectDocuments property or respond to the onDocumentSelect event.
selectedDocuments PickerDocument[] The set of documents last selected from this picker.

Note that multiple documents can only be selected if the Multiple Select Feature is enabled on this picker. If not, this array will contain at most one element.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
text string HTML text field of this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
views string[] Configures a set of views to display in the picker. For a complete description of each view see Picker Reference - ViewId.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
open() undefined

Opens the picker dialog associated with this widget.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onCancel(
  widget:Widget)		 This script will run after user clicks cancel in the picker window or closes it.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onDocumentSelect(
  widget:Widget,
  result:object)		 This script will run after the user selects a file in the picker dialog. The result of the user''s selection can be referenced using the result variable which is a JSON object. See Picker - JSON Guide for a complete reference to the result object format and structure.
onPickerInit(
  widget:Widget,
  pickerBuilder:object)		 Called right before the picker is opened. Passes in a PickerBuilder which can be used to provide any functionality not provided in the App Maker UI. Note, you should not call build() on this object.

Back to Top

Dropdown which allows user to select a single choice from a list of options. The selected value is exposed in the value property, and the options to pick from are in options. The type of items in options should match the type of items in value. You can specify a custom string to display for each option by setting the names property.

Styles

Name Description

Properties

Name Type Description

Methods

Name Return Value Description

Events

Name Description

Back to Top

GoogleMap

A Google Map widget that uses the Google Maps API.

Styles

Name Description
.app-GoogleMap The primary style for the widget.

Properties

Name Type Description
address string The address of the center of the map. Latitude and longitude properties will be affected when this property changed. However changes of latitude and longitude properties will not affect this property. If the address is cleared, the latitude and longitude will be restored to the last user-defined values.
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
formattedAddress string A string containing the human-readable Google version of the address property. Changes of latitude and longitude properties will not affect this property.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
latitude number The latitude of the center of the map between -90 degrees and +90 degrees.
loaded boolean Whether the widget has been attached to the DOM.
longitude number The longitude of the center of the map between -180 degrees and +180 degrees.
mapType string The type of the map including roadmap, hybrid, satellite, and terrain. If the map type is changed inside the map widget, there is no event fired due to the API limitation.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
showAddressMarker boolean Whether to show a marker for the address. If the address is not specified, no marker will be shown.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.
zoom number The initial resolution at which to display the map is set by the zoom property, where zoom 0 corresponds to a map of the Earth fully zoomed out, and higher zoom levels zoom in at a higher resolution.

Methods

Name Return Value Description
getAddressMarkerJs() Marker

Returns the underlying Google Maps v3 API Marker object used to show the address.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
getMapJs() GoogleMap

Returns underlying Google Maps v3 API Map object.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

Grid

A layout widget that shows a collection of records by cloning a panel and repeating it in a left-to-right, top-down order.

During runtime, one panel of the grid is shown per item in the Grid's datasource. The datasource for that row is a special single item datasource pointing to the corresponding item in the Grid's datasource. This allows the prototype panel to access the current panel's item with the @datasource.item syntax.

Styles

Name Description
.app-Grid The primary style for the grid widget.
.app-GridCell Style for every cell of the grid.
.app-GridCell.selected Style for the selected cell.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
children PropertyMap The direct children of this Layout widget, identified by their names.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
descendants PropertyMap All the children of this Layout widget recursively, identified by their names. This excludes any repeated children, such as rows in a List, cells in a Grid, Accordion, and their content.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
selectedCell LayoutWidget The selected cell widget.
selectedIndex number The index of the selected row.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether all the children have a true valid property or no valid property. This can often be used in forms to determine whether all the input widgets in a form have valid values.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focusFirstWidget() undefined

Focuses the first focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusFirstWidget();
focusLastWidget() undefined

Focuses the last focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusLastWidget();
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onSelectedIndexChange(
  widget:Widget,
  newIndex:number)		 This script will run on the client whenever the selectedIndex property of this widget changes. The widget can be referenced using parameter widget and the new index is stored in newIndex.
onSelectedIndexEdit(
  widget:Widget,
  newIndex:number)		 This script will run on the client whenever the selection of this widget is changed by the user (for example by clicking on a row). The widget can be referenced using parameter widget and the new selected index is stored in newIndex. Unlike onSelectedIndexChange(), this runs only when a user changes the selected row; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

HelpIcon

A help icon widget that shows a popup tooltip when the widget gets focus or when the user hovers over it. The popup is closed when the widget looses focus and when the mouse is moved out of the icon or the popup.

Styles

Name Description
.app-HelpIcon The primary style for the widget.
.app-HelpIcon.hover Style for the icon widget when it's hovered over.
.app-HelpIcon-Icon Style for the widget's icon.
.app-HelpIcon-Popup Style for the tooltip popup.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
html string A string possibly containing HTML markup.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

HorizontalSplit

A panel with a left and right child and a movable splitter.

Styles

Name Description
.app-HorizontalSplit The primary style for the horizontal split panel.
.app-HorizontalSplitLeft Style for the left panel.
.app-HorizontalSplitRight Style for the right panel.
.app-HorizontalSplit-Splitter Style for the splitter.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
children PropertyMap The direct children of this Layout widget, identified by their names.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
descendants PropertyMap All the children of this Layout widget recursively, identified by their names. This excludes any repeated children, such as rows in a List, cells in a Grid, Accordion, and their content.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
splitPosition number The position of the splitter from the left/top of the panel.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether all the children have a true valid property or no valid property. This can often be used in forms to determine whether all the input widgets in a form have valid values.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focusFirstWidget() undefined

Focuses the first focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusFirstWidget();
focusLastWidget() undefined

Focuses the last focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusLastWidget();
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

Html

An HTML area that can display static HTML or bound to dynamic content. Caution should be used if user input can affect the value of this widget, since it can lead to a XSS attack.

Note: When displayed in the App Maker editor, the HTML Area will not execute any scripts, nor will it inherit global styles.

Styles

Name Description
.app-Html The primary style for the html widget.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
html string A string possibly containing HTML markup.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

Image

An Image widget.

Styles

Name Description
.app-Image The primary style for the image.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
altText string The alternate text for an image. This text provides image information to the user if they cannot view the image, such as before the image loads or when the user uses a screen reader.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
href string The URL to open when the user clicks the image.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
resizeMode string How to resize the image in the image widget. Possible values:
  • resize - Resize the image widget to match the size of the source image.
  • constrain - Resize the source image to fit the image widget but do not change its proportions.
  • stretch - Resize and reproportion the source image to fit the image widget.
  • clip - Show only the portion of the source image that fits in the widget.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
target string Where to open the href URL:
  • _blank - Open the link in a new window.
  • _self - Open the link in the same frame.
  • _parent - Open the link in parent frameset.
  • _top - Open the link in the body of the window.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
url string The URL of the image (assigned to the src attribute).
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
resizeToImage() undefined

Resizes the widget to the natural size of its image.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onClick(
  widget:Widget,
  event:object)		 This script will run on the client whenever this widget is clicked. The widget can be referenced using parameter widget and the JavaScript click event is stored in event. Entering this code app.showPage(app.pages.NameOfPage) would navigate to the named page whenever this widget is clicked.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onError(
  widget:Widget,
  event:object)		 An event that runs if an error occurs when the image loads. You can use this event to replace the image URL with a fallback image or report an error to the user.

Back to Top

Label

A simple label.

Styles

Name Description
.app-Label The primary style for the label.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
text string HTML text field of this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onClick(
  widget:Widget,
  event:object)		 This script will run on the client whenever this widget is clicked. The widget can be referenced using parameter widget and the JavaScript click event is stored in event. Entering this code app.showPage(app.pages.NameOfPage) would navigate to the named page whenever this widget is clicked.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

LayoutWidget

Represents any widget that can contain other widgets inside. Layout widgets are the only widgets which a datasource can be set on.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
children PropertyMap The direct children of this Layout widget, identified by their names.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
descendants PropertyMap All the children of this Layout widget recursively, identified by their names. This excludes any repeated children, such as rows in a List, cells in a Grid, Accordion, and their content.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether all the children have a true valid property or no valid property. This can often be used in forms to determine whether all the input widgets in a form have valid values.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focusFirstWidget() undefined

Focuses the first focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusFirstWidget();
focusLastWidget() undefined

Focuses the last focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusLastWidget();
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

LineChart

A widget which displays its data as line chart.

The first column contains a list of labels for the x-axis of the chart. Every additional column is a list of numbers to show on the line chart. Example use:

Say you have a model that represents the total budget for a given year, and you wanted a chart showing the budget history. You can create a line chart, bind the first column's (the label column) data property to @datasource.items.year and the second column (the data column) data property to @datasource.items.budget. This will show a chart with a line that has one point for every item in your datasource, using the year field as a label, and the budget field as the position of the point. You can add additional columns to chart more data against the same Y axis, so for example you might add another column and bind its data property to @datasource.items.revenue to show the revenue alongside the budget.

Styles

Name Description
.app-LineChart The primary style for the line chart.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
chartAreaHeight string The relative size of the chart itself. Setting this to a value of 50% will allocate 50% of the overall canvas to the chart and 50% to the legend, if the legend is in the top or bottom position. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartAreaLeft string The position or percentage of the upper left corner of the chart. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartAreaTop string The position or percentage of the upper left corner of the chart. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartAreaWidth string The relative size of the chart itself. Setting this to a value of 50% will allocate 50% of the overall canvas to the chart and 50% to the legend, if the legend is in the left or right position. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartColors string[] An array of colors to display in this chart. The exact meaning differs based on the type of chart. Each element in the array is an html color string, for example ['red','#004411'].
chartTitle string The title to display above this chart.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
columns PropertyMap A PropertyMap of all the ChartColumns this chart has, by the chart name. For example, assuming you have a chart variable chart, to access a column named "Rabbits" you'd use the expression chart.columns.Rabbits.
curveType string Controls the curve of the lines. Can be one of the following:
  • 'none' - Straight lines without curve.
  • 'function' - The angles of the line will be smoothed.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
legendPosition string Position of the legend. Can be one of the following:
  • 'right' - To the right of the chart.
  • 'left' - To the left of the chart.
  • 'top' - Above the chart.
  • 'bottom' - Below the chart.
  • 'none' - No legend is displayed.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
vertical boolean If set to true the lines grow upward, otherwise they grow rightward.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
getChartJs() object

Returns the underlying JavaScript Google Visualization object used by this chart. Standard methods for this object are specified here. This method (as well as getDataTableJs() and getOptionsJs()) are exposed to allow you to take advantage of advanced uses of the Google Visualization API. Whenever possible you should prefer to use the App Maker property system the chart inspector (in the Property Editor) to modify chart data and options.

If you want to add a custom event handler to the table you can use getChartJs() in onAttach event, for example: 

 var chart = widget.getChartJs();
 google.visualization.events.addListener(chart, 'select', function() {
   alert('Something was selected!');
 });
getDataTableJs() DataTable

Returns the Google Visualization API Data Table object used by this chart. Note that editing this directly can cause inconsistency between the "data" property on this charts columns and the actual underlying data being shown.

Note that when you update the data table, you'll likely want to redraw the chart. You can manually call redraw() method after updating the data table.

If you want to customize your data output using Formatters you can use getDataTableJs() in onDataLoad event, for example: 

 var data = widget.getDataTableJs();
 var formatter = new google.visualization.PatternFormat('{0}');
 formatter.format(data, [0]);

See the Google Visualization documentation for drawing for more information on using data tables and options.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
getOptionsJs() Options

Returns the Google Visualization API object which represents the options for your line chart. Read more about line chart options here. Note that editing this directly won't fire property change events for existing App Maker options, so you should prefer to use App Maker whenever possible, and only rely on this when App Maker doesn't provide the option you need.

Note that when you update the options, you'll likely want to redraw the chart so the options will be displayed. You can manually call redraw() method after updating the options.

If you want to customize options before chart is displayed on UI you can use getOptionsJs() in onAttach event.

See the Google Visualization documentation for drawing for more information on using data tables and options.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

Link wraps an HTML anchor element and can be used to link to other websites or other pages inside your application. Note that the HTML specification does not support disabling links, so at the moment App Maker does not either.

Styles

Name Description

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
href string HTML link to open when the link is clicked.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
target string Specifies where to open the link specified in href.
  • _blank - Opens the link in a new window.
  • _self - Opens the link in the same frame that it was clicked.
  • _parent - Opens the link in parent frameset.
  • _top - Opens the link in the body of the window.
text string HTML text field of this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onClick(
  widget:Widget,
  event:object)		 This script will run on the client whenever this widget is clicked. The widget can be referenced using parameter widget and the JavaScript click event is stored in event. Entering this code app.showPage(app.pages.NameOfPage) would navigate to the named page whenever this widget is clicked.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

List

A layout widget capable of showing a list of items.

In the UI editor, the user edits a prototype row, adding widgets and binding them like in a normal panel.

During runtime, one row is shown per item in the List's datasource. The datasource for that row is a special single item datasource pointing to the corresponding item in the List's datasource. This allows the prototype row to access the current row's item with the @datasource.item syntax.

Styles

Name Description
.app-List The primary style for the list widget.
.app-ListRow Style for every row of the list.
.app-ListRow.selected Style for the selected row.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
children PropertyMap The direct children of this Layout widget, identified by their names.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
descendants PropertyMap All the children of this Layout widget recursively, identified by their names. This excludes any repeated children, such as rows in a List, cells in a Grid, Accordion, and their content.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
selectedIndex number The index of the selected row.
selectedRow LayoutWidget The selected row widget.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether all the children have a true valid property or no valid property. This can often be used in forms to determine whether all the input widgets in a form have valid values.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focusFirstWidget() undefined

Focuses the first focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusFirstWidget();
focusLastWidget() undefined

Focuses the last focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusLastWidget();
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onSelectedIndexChange(
  widget:Widget,
  newIndex:number)		 This script will run on the client whenever the selectedIndex property of this widget changes. The widget can be referenced using parameter widget and the new index is stored in newIndex.
onSelectedIndexEdit(
  widget:Widget,
  newIndex:number)		 This script will run on the client whenever the selection of this widget is changed by the user (for example by clicking on a row). The widget can be referenced using parameter widget and the new selected index is stored in newIndex. Unlike onSelectedIndexChange(), this runs only when a user changes the selected row; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

MultiSelect

A multiple select list box which allows user to select a list of items from another list of options. The selected values are exposed in the values property, and the options to pick from are in options. The type of items in options should match the type of items in values. You can specify a custom string to display for each option by setting the names property.

Styles

Name Description
.app-MultiSelect The primary style for an outer panel around the multi select.
.app-MultiSelect.disabled The style for the widget when it is disabled.
.app-MultiSelect.focus The style for the widget when it has focus.
.app-MultiSelect.invalid Style for the widget when it has a validation error.
.app-MultiSelect-Label Style for the label on top of the multi select.
.app-MultiSelect-Input Style for the inner multi select.
.app-MultiSelect-List Style for the list of items.
.app-MultiSelect-Item Style for every unselected item.
.app-MultiSelect-Item.selected Style for the selected item or items.
.app-MultiSelect-Item.disabled Style for the disabled item or items.
.app-MultiSelect-Item.highlighted Style for the highlighted item.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
names string[] An optional array of strings that correspond 1-to-1 with the options. The strings will be used as labels to display the options. This is useful if the values set in options and values are not strings, and instead set some underlying data in the backend. For example, if value and options are bound to a record, this could be used to display a certain field of the record to the user.
options Dynamic[] You can bind the options property to the following:
  • A constant JavaScript list, such as ["1","2","3"]. Enter the array in the bindings code editor.
  • The values of a field for all items in a datasource, with the following syntax: 
    @datasource.items..field-name

    The ".." is the projections operator that lets you access a compiled list of the values for a field. For example, if you have a model with a field City, you can bind options to @datasource.items..City. If three records in the model have values of "L.A.", "San Francisco", and "Mountain View" for the City field, the list of selectable options contains all those values.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
values Dynamic[] The array of currently selected options. Enter a data binding to link values to a field in the datasource. If a user selects multiple strings, you must transform them into an array. One way to create an array is to use the strToArray binding transformer: 
@datasource.item.field-name#strToArray()
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onValuesChange(
  widget:Widget,
  newValues:object)		 This script will run on the client whenever the values property of the multi-select box changes. The multi-select box can be referenced using parameter widget and the new values are stored in the newValues variable as a JavaScript array.
onValuesEdit(
  widget:Widget,
  newValues:object)		 This script will run on the client whenever the values property of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValues. Unlike onValuesChanges(), this runs only when a user changes the values of the widget; it won''t run in response to bindings or when the values are set programmatically.

Back to Top

Pager

A pager to navigate through the pages of the datasource of the widget's parent. Binding errors will occur if the parent widget does not have a datasource.

The visible property is bound to @datasource.loaded && !(@datasource.firstPage && @datasource.lastPage) so that the pager will be visible only when the associated datasource is loaded and it has more than one page.

Styles

Name Description
.app-Pager The primary style for the widget.
.app-Pager-Text Text that appears between the previous and next buttons
.app-Pager-Prev Style for the previous button.
.app-Pager-Next Style for the next button.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
nextEnabled boolean Whether the next button is enabled. By default it is bound to !@datasource.lastPage so that it is disabled on the last page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
previousEnabled boolean Whether the previous button is enabled. By default it is bound to !@datasource.firstPage so that it is disabled on the first page.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
text string HTML text field of this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onNextClick(
  widget:Widget,
  event:object)		 This script will run on the client whenever the next button is clicked. By default it is bound to the Load Next Page action. The widget can be referenced using parameter widget and the JavaScript click event is stored in event.
onPreviousClick(
  widget:Widget,
  event:object)		 This script will run on the client whenever the previous button is clicked. By default it is bound to the Load Previous Page action. The widget can be referenced using parameter widget and the JavaScript click event is stored in event.

Back to Top

Panel

A simple layout widget which contains other widgets.

Styles

Name Description
.app-Panel The primary style for the panel.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
alignChildren string Aligns in-flow children along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel.
  • start - In-flow children are aligned at the start of the cross axis of the line.
  • end - In-flow children are aligned at the end of the cross axis of the line.
  • center - In-flow children are centered in the cross axis within the line.
  • baseline - In-flow children are aligned such that their baselines align.
  • stretch - In-flow children that have the cross-axis set to auto stretch to fill the panel.For example, if the panel has row direction, in-flow children whose height is set to auto will stretch vertically to fill the panel.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
children PropertyMap The direct children of this Layout widget, identified by their names.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
descendants PropertyMap All the children of this Layout widget recursively, identified by their names. This excludes any repeated children, such as rows in a List, cells in a Grid, Accordion, and their content.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
justify string Aligns children along a single line of the panel. Typically it helps distribute extra free space, horizontally for horizontal panels and vertically for vertical panels.
  • start - In-flow children are packed toward the start of the line.
  • end - In-flow children are packed toward the end of the line.
  • center - In-flow children are packed toward the center of the line.
  • spaceBetween - In-flow children are evenly distributed in the line.
  • spaceAround - In-flow children are evenly distributed in the line, with half-size spaces on each end.
layout string Defines whether the panel places its children in fixed positions, in a vertical flow or in a horizontal flow.
  • fixed - The position of a child is independent of the position of its siblings.
  • horizontal - The flow grows rightward, as a row.
  • vertical - The flow grows downward, as a column.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether all the children have a true valid property or no valid property. This can often be used in forms to determine whether all the input widgets in a form have valid values.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.
wrap string Controls whether the flow panel is single-line or multi-line and the direction new lines are stacked in.
  • nowrap - The flow panel is single-line.
  • wrap - The flow panel is multi-line.
  • wrapReverse - The flow panel is multi-line as in wrap, but new lines are stacked in the opposite direction.
wrapAlign string Aligns the lines of the flow panel when there is extra space in the cross-axis, similar to how justify aligns in-flow children along the lines. Note, this property has no effect when the flow panel has a single line.
  • start - Lines are packed toward the start of the panel.
  • end - Lines are packed toward the end of the panel.
  • center - Lines are packed toward the center of the panel.
  • spaceBetween - Lines are evenly distributed in the panel.
  • spaceAround - Lines are evenly distributed in the panel, with half-size spaces on each end.
  • stretch - Lines stretch to take up the remaining space.

Methods

Name Return Value Description
createChildren() undefined

Creates and adds all the children. Usually this happens automatically when the panel is created. However, you can specify that children are created when the panel is loaded or that children are only created when this method is called. The latter can be useful if the panel's children's visibility is controlled via scripts and you don't want the children to be created until the children will be visible. If this method is called after the children have been created, then it does nothing.
downloadContent(
  callback:Function)		 undefined

Downloads content as follows:

  • when passed for pages, loads content of the page then invokes callback.
  • when passed for panels, immediately invokes callback.
  • if content has already been downloaded, immediately invokes callback.
  • if download has been requested but hasn't completed, then downloadContent has no effect.
app.pages.MyPage.downloadContent(function(page) {
page.createChildren();
// MyPage is fully initialized at this point.
}
);

focusFirstWidget() undefined

Focuses the first focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusFirstWidget();
focusLastWidget() undefined

Focuses the last focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusLastWidget();
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onClick(
  widget:Widget,
  event:object)		 This script will run on the client whenever this widget is clicked. The widget can be referenced using parameter widget and the JavaScript click event is stored in event. Entering this code app.showPage(app.pages.NameOfPage) would navigate to the named page whenever this widget is clicked.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

PieChart

A widget which displays its data as a Pie Chart.

Can only support two columns, a label column and a data column. Each item in the data column is a slice of the pie should be a positive number, it need not be a percentage, that is calculated and displayed automatically by the pie chart.

Styles

Name Description
.app-PieChart The primary style for the pie chart.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
chartAreaHeight string The relative size of the chart itself. Setting this to a value of 50% will allocate 50% of the overall canvas to the chart and 50% to the legend, if the legend is in the top or bottom position. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartAreaLeft string The position or percentage of the upper left corner of the chart. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartAreaTop string The position or percentage of the upper left corner of the chart. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartAreaWidth string The relative size of the chart itself. Setting this to a value of 50% will allocate 50% of the overall canvas to the chart and 50% to the legend, if the legend is in the left or right position. This value can be an integer, like '50' (and pixels is assumed) or a %, like 50%.
chartColors string[] An array of colors to display in this chart. The exact meaning differs based on the type of chart. Each element in the array is an html color string, for example ['red','#004411'].
chartTitle string The title to display above this chart.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
columns PropertyMap A PropertyMap of all the ChartColumns this chart has, by the chart name. For example, assuming you have a chart variable chart, to access a column named "Rabbits" you'd use the expression chart.columns.Rabbits.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
legendPosition string Position of the legend. Can be one of the following:
  • 'right' - To the right of the chart.
  • 'left' - To the left of the chart.
  • 'top' - Above the chart.
  • 'bottom' - Below the chart.
  • 'none' - No legend is displayed.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
threeDimensional boolean If set to true, displays a three-dimensional chart.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
getChartJs() object

Returns the underlying JavaScript Google Visualization object used by this chart. Standard methods for this object are specified here. This method (as well as getDataTableJs() and getOptionsJs()) are exposed to allow you to take advantage of advanced uses of the Google Visualization API. Whenever possible you should prefer to use the App Maker property system the chart inspector (in the Property Editor) to modify chart data and options.

If you want to add a custom event handler to the table you can use getChartJs() in onAttach event, for example: 

 var chart = widget.getChartJs();
 google.visualization.events.addListener(chart, 'select', function() {
   alert('Something was selected!');
 });
getDataTableJs() DataTable

Returns the Google Visualization API Data Table object used by this chart. Note that editing this directly can cause inconsistency between the "data" property on this charts columns and the actual underlying data being shown.

Note that when you update the data table, you'll likely want to redraw the chart. You can manually call redraw() method after updating the data table.

If you want to customize your data output using Formatters you can use getDataTableJs() in onDataLoad event, for example: 

 var data = widget.getDataTableJs();
 var formatter = new google.visualization.PatternFormat('{0}');
 formatter.format(data, [0]);

See the Google Visualization documentation for drawing for more information on using data tables and options.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
getOptionsJs() PieChart.PieOptions

Returns the Google Visualization API object which represents the options for your pie chart. Read more about pie chart options here. Note that editing this directly won't fire property change events for existing App Maker options, so you should prefer to use App Maker whenever possible, and only rely on this when App Maker doesn't provide the option you need.

Note that when you update the options, you'll likely want to redraw the chart so the options will be displayed. You can manually call redraw() method after updating the options.

If you want to customize options before chart is displayed on UI you can use getOptionsJs() in onAttach event.

See the Google Visualization documentation for drawing for more information on using data tables and options.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

RadioGroup

A radio group widget which allows to select a single choice from a list of options. The selected value is exposed in the value property, and the options to pick from are in options. The type of items in options should match the type value . You can specify a custom string to display for each option by setting the names property.

Styles

Name Description
.app-RadioGroup The primary style for an outer panel around the radio group.
.app-RadioGroup.disabled Style for the widget when it is disabled.
.app-RadioGroup.focus Style for the dropdown when it has focus.
.app-RadioGroup.invalid Style for the widget when it has a validation error.
.app-RadioGroup-Label Style for the label on top of the radio group.
.app-RadioGroup-Input Style for the inner radio group.
.app-RadioGroup-Item Style for radio group items.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
allowNull boolean Whether the user should be allowed to make no selection. The default label for this option is "No Selection", you can change it by setting the nullItemName property.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
names string[] An optional array of option labels that correspond 1-1 with the option values. This is useful if the value set in options and value are not strings, and instead set some underlying data in the backend. For example, if value and options are bound to a record, this could be used to display a certain field of the record to the user.
nullItemName string Optional label to use to display the null option. Which is shown if there is no selection. The default label is "No Selection". Cannot be set to null or undefined.
options Dynamic[] You can bind the options property to the following:
  • A constant JavaScript list: ["1","2","3"]. Enter the array in the bindings code editor.
  • The items of a datasource. If you have a model with a field City, you can bind options to @datasource.items..City. If three records in the model have values of "L.A.", "San Francisco", and "Mountain View", the list of selectable options contains the same values.
  • The possible values of a field: @datasource.model.fields.FIELD_NAME.possibleValues.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
text string Label being displayed for the selected value, or nullItemName if the selected value is null or invalid.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value Dynamic The selected value.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onValueChange(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value property of this widget changes. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

Slider

A slider bar widget.

Styles

Name Description
.app-Slider The primary style for an outer panel around the widget.
.app-Slider.disabled Style for the widget when it is disabled.
.app-Slider.invalid Style for the widget when it has a validation error.
.app-Slider-Label Style for the label.
.app-Slider-Input Style for the inner slider.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
continuousValue number The slider's continuous value. Updates constantly while the user interacts with the slider. Note: Unless you need constant updates while the slider is moving, binding to value is usually preferred over binding over continuousValue. Especially if bound to a record, since updating a record requires a call to the server. Except while the user is moving the slider, value and continuousValue have the same value.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
loaded boolean Whether the widget has been attached to the DOM.
max number The maximum slider value.
min number The minimum slider value.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
step number The slider value step size.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value number The slider's stable value. Only changes after the user finishes sliding the slider.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onContinuousValueChange(
  widget:Widget,
  newValue:number)		 This script will run on the client whenever the continuousValue property of this slider changes. The slider can be referenced using parameter widget and the new value of the slider is stored in newValue.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onValueChange(
  widget:Widget,
  newValue:number)		 This script will run on the client whenever the value property of this slider changes. The slider can be referenced using parameter widget and the new value of the slider is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

Spinner

Widget which shows a spinner whenever the datasource of the widget's parent is loading new data. Note, a binding error will occur if the parent widget does not have a datasource.

When styling the spinner, you can add up to four colors by setting the border-color of each circle. Additionally, you can modify the circle width by setting the border-width. You can use app-Spinner-AllCircles to style all circle at once, for example, if you want to change all widths, or if you want a spinner with a single color.

Styles

Name Description
.app-Spinner The primary style for the spinner widget.
.app-Spinner-AllCircles Style name which applies to all four circles of the spinner. You can use this style to style the spinner to be a single color.
.app-Spinner-FirstCircle The style name for the first of four circles which make up the spinner.
.app-Spinner-SecondCircle The style name for the second of four circles which make up the spinner.
.app-Spinner-ThirdCircle The style name for the third of four circles which make up the spinner.
.app-Spinner-FourthCircle The style name for the fourth of four circles which make up the spinner.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

StarRating

A star rating widget which can be bound to data.

Styles

Name Description
.app-StarRating The primary style for an outer panel around the widget.
.app-StarRating.disabled Style for the widget when it is disabled.
.app-StarRating.invalid Style for the widget when it has a validation error.
.app-StarRating-Label Style for the label.
.app-StarRating-Input Style for the inner star rating.
.app-StarRating-Input.highlighted Style for the inner star rating when editing its value.
.app-StarRating-Star Style for every star.
.app-StarRating-Star::after Style for the icon of every star. Use the content CSS property to change the icon.
.app-StarRating-Star.filled Style for every filled star.
.app-StarRating-Star.filled::after Style for the icon of every filled star. Use the content CSS property to change the icon.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
integer boolean Whether the number must be an integer.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
loaded boolean Whether the widget has been attached to the DOM.
maxValue number The maximum value of the number inclusive.
minValue number The minimum value of the number inclusive.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
precision number The level of precision. The displayed value is rounded to closest multiple of 1 / precision. For example, a precision of 2 will show half stars, while 1 will only show full stars.
required boolean Whether a value is required or it can be missing.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
size number The total number of stars.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value number The selected number of stars.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onValueChange(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value property of this widget changes. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

SuggestBox

A text field that suggests completions for the user.

The selected value is exposed in the value property, and the options to complete from are in options. The type of items in options should match the type of items in value.

Alternatively, the suggest text field can be configured to pull its suggestions from a field with possible values, a relation, or to a record from an existing model. This can currently only be done using the UI provided in the suggest text field.

Styles

Name Description
.app-SuggestBox The primary style for an outer panel around the suggest box.
.app-SuggestBox.disabled Style for the widget when the input is disabled.
.app-SuggestBox.focus Style for the widget when the input has focus.
.app-SuggestBox.invalid Style for the widget when it has a validation error.
.app-SuggestBox-Label Style for the label.
.app-SuggestBox-Input Style for the inner input box.
.app-SuggestBox-Popup The primary style for the suggest popup.
.app-SuggestBox-Error Style applied to text when there is an error.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
limit number Limits the number of options which are displayed.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
options Dynamic[] The options.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
placeholder string Placeholder text to show when there is no value to show. For example, "Enter full email address" for a field meant to contain an email address.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the text that the user has typed is one of the current suggestions. If suggestions are being generated from a model and a user types a valid value, then there may be a delay until the valid property is true because of the latency in loading suggestions. The empty string is always considered to be a valid value. Any value that is set from scripting or bindings is considered valid, even if it does not match a suggestion.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value Dynamic The value.
valueIsRecord boolean Whether the value property is the record or the auto-complete label.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
isErrorState() boolean

Whether the suggest text field is considered to be in an error state.
setErrorState(
  errorState:boolean)		 undefined

This methods changes whether the suggest text field is considered to be in an error state. If it is in an error state, the error state is indicated by a CSS class.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onInputChange(
  widget:Widget)		 This script will run on the client whenever the user changes the input value. For example, in a text field, this script will be run each time the user types a character or pastes text into the text field. This script is not run when the value of the widget is changed programmatically, i.e. through a binding or a script.
onValueChange(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value property of this widget changes. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

TableChart

The columns of the table display data of a particular type, which is chosen when the column is added. Columns of type Number and Date provide some formatting options like prefix for numbers (useful to add a currency symbol), or formatType for dates that allows to choose from some common date formats. When the data property of a column is bound to @datasouce.items.MyField, where MyField is a field of the table chart's datasource:

  • the table's selected row is synchronized with the datasource's current item, and
  • sorting by this column is done in the server (assuming the field is sortable).

      Styles

      Name Description
      .app-TableChart The primary style for the table chart.

      Properties

      Name Type Description
      align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
      • inherited - The widget is aligned as specified by its parent (default).
      • start - The widget is aligned at the start of the cross axis of the line.
      • end - The widget is aligned at the end of the cross axis of the line.
      • center - The widget is centered in the cross axis within the line.
      • baseline - The widget is aligned such that their baselines align.
      If the widget is not in-flow, it has no effect.
      ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
      autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
      autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
      childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
      columns PropertyMap A PropertyMap of all the ChartColumns this chart has, by the chart name. For example, assuming you have a chart variable chart, to access a column named "Rabbits" you'd use the expression chart.columns.Rabbits.
      dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
      datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
      firstRowNumber number The row number for the first row in the table. Used only if showRowNumber is true.
      grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
      invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
      • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
      • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
      loaded boolean Whether the widget has been attached to the DOM.
      name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
      parent LayoutWidget Parent Layout widget that contains this widget on the screen.
      root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
      showRowNumber boolean If set to true, shows the row number as the first column of the table.
      styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
      Deprecated: use styles instead.
      styles string[] A list of CSS style classes to apply to this widget.
      title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
      valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
      validationDisplay boolean Whether to display validation errors using a popup near the widget.
      validationErrors string[] The validation errors associated with this widget.
      visible boolean True if the widget is visible, false otherwise.

      Methods

      Name Return Value Description
      getChartJs() object

      Returns the underlying JavaScript Google Visualization object used by this chart. Standard methods for this object are specified here. This method (as well as getDataTableJs() and getOptionsJs()) are exposed to allow you to take advantage of advanced uses of the Google Visualization API. Whenever possible you should prefer to use the App Maker property system the chart inspector (in the Property Editor) to modify chart data and options.

      If you want to add a custom event handler to the table you can use getChartJs() in onAttach event, for example: 

       var chart = widget.getChartJs();
 google.visualization.events.addListener(chart, 'select', function() {
   alert('Something was selected!');
 });
      getDataTableJs() DataTable

      Returns the Google Visualization API Data Table object used by this chart. Note that editing this directly can cause inconsistency between the "data" property on this charts columns and the actual underlying data being shown.

      Note that when you update the data table, you'll likely want to redraw the chart. You can manually call redraw() method after updating the data table.

      If you want to customize your data output using Formatters you can use getDataTableJs() in onDataLoad event, for example: 

       var data = widget.getDataTableJs();
 var formatter = new google.visualization.PatternFormat('{0}');
 formatter.format(data, [0]);

      See the Google Visualization documentation for drawing for more information on using data tables and options.
      getElement() Element

      Returns component's DOM element.

      This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
      getFullPath() string

      Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
      getOptionsJs() Table.Options

      Returns the Google Visualization API object which represents the options for your table chart. Read more about table chart options here. Note that editing this directly won't fire property change events for existing App Maker options, so you should prefer to use App Maker whenever possible, and only rely on this when App Maker doesn't provide the option you need.

      Note that when you update the options, you'll likely want to redraw the chart so the options will be displayed. You can manually call redraw() method after updating the options.

      If you want to customize options before chart is displayed on UI you can use getOptionsJs() in onAttach event.

      See the Google Visualization documentation for drawing for more information on using data tables and options.
      validate() boolean

      For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

      For layout widgets validates all children and returns true if all of them are valid, false otherwise.

      If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

      Events

      Name Description
      onAttach(
        widget:Widget)      		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
      onDataLoad(
        widget:Widget)      		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

      Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
      onDetach(
        widget:Widget)      		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

      Back to Top

Tabs

A layout widget that displays its children in tabs.

Styles

Name Description
.app-Tabs The primary style for the tab container.
.app-Tabs-Tab Style for each tab title.
.app-Tabs-Tab.selected Style for the title of the selected tab.
.app-Tabs-Header Style for the container that holds all the tab titles.
.app-Tabs-Body Style for the section that shows content of currently selected tab.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
children PropertyMap The direct children of this Layout widget, identified by their names.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
descendants PropertyMap All the children of this Layout widget recursively, identified by their names. This excludes any repeated children, such as rows in a List, cells in a Grid, Accordion, and their content.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
selectedTab number The currently selected tab index. The first tab is 0.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether all the children have a true valid property or no valid property. This can often be used in forms to determine whether all the input widgets in a form have valid values.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focusFirstWidget() undefined

Focuses the first focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusFirstWidget();
focusLastWidget() undefined

Focuses the last focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusLastWidget();
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
getTabTitle(
  index:int)		 string

Gets the title of given tab.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onSelectedTabChange(
  widget:Widget,
  selectedTab:number)		 Fired when the user selects a new tab. The newly selected index is passed in as selectedTab.

Back to Top

TextArea

Multi-line text input widget.

Styles

Name Description
.app-TextArea The primary style for an outer panel around the text area.
.app-TextArea.disabled Style for the widget when it is disabled.
.app-TextArea.focus Style for the widget when it has focus.
.app-TextArea.invalid Style for the widget when it has a validation error.
.app-TextArea-Label Style for the label.
.app-TextArea-Input Style for the inner input box.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
loaded boolean Whether the widget has been attached to the DOM.
maxLength number The maximum length of the value in characters.
minLength number The minimum length of the value in characters.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
placeholder string Placeholder text to show when there is no value to show. For example, "Enter full email address" for a field meant to contain an email address.
regexp string A regular expression that all valid values must match. JavaScript regular expression syntax is used for this, read more about regular expressions.
regexpError string The error message to show to the user if the regular expression does not match the user input. An occurrence of '%s' in the error message will be substituted with the user input.
required boolean Whether a value is required or it can be missing.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value string The current value of this widget. Corresponds to the HTML value field.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onValueChange(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value property of this widget changes. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

TextBox

A simple text field widget.

Styles

Name Description
.app-TextBox The primary style for an outer panel around the text box.
.app-TextBox.disabled Style for the widget when it is disabled.
.app-TextBox.focus Style for the widget when it has focus.
.app-TextBox.invalid Style for the widget when it has a validation error.
.app-TextBox-Label Style for the label.
.app-TextBox-Input Style for the inner input box.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
loaded boolean Whether the widget has been attached to the DOM.
maxLength number The maximum length of the value in characters.
minLength number The minimum length of the value in characters.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
placeholder string Placeholder text to show when there is no value to show. For example, "Enter full email address" for a field meant to contain an email address.
regexp string A regular expression that all valid values must match. JavaScript regular expression syntax is used for this, read more about regular expressions.
regexpError string The error message to show to the user if the regular expression does not match the user input. An occurrence of '%s' in the error message will be substituted with the user input.
required boolean Whether a value is required or it can be missing.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value string The current value of this widget. Corresponds to the HTML value field.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onValueChange(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value property of this widget changes. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

TextEditor

A rich text editor.

Styles

Name Description
.app-TextEditor The primary style for the text editor.
.app-TextEditor.disabled Style for the widget when it is disabled.
.app-TextEditor.focus Style for the widget when is has focus.
.app-TextEditor.invalid Style for the widget when it has a validation error.
.app-TextEditor-Label Style for the label.
.app-TextEditor-Input Style for the inner text editor.
.app-TextEditor-Toolbar Style for text tool bar.
.app-TextEditor-Body Style for text area container.
.app-TextEditor-Button Style for buttons on the tool bar.
.app-TextEditor-Button.pressed Style for pressed toggle buttons on tool bar.
.app-TextEditor-Dropdown Style for list boxes on tool bar.
.app-TextEditor-Popup Style for sub-bar popup.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value string The current value of this widget. Corresponds to the HTML value field.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onValueChange(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value property of this widget changes. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

UserPicker

User Picker widget that uses the Directory model to suggest users matching a keyword query. See the documentation for details on how the Admin SDK Directory API matches records to query tokens without an associated filter.

Styles

Name Description
.app-UserPicker The primary style for the widget.
.app-UserPicker.disabled Style for the widget when it is disabled.
.app-UserPicker-Popup-Image Style for the profile image thumbnail.
.app-UserPicker-Popup-Text Base style for full name and email text.
.app-UserPicker-Popup-Name Style for the full name text.
.app-UserPicker-Popup-Email Style for the email text.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
enabled boolean Whether the widget allows the user to change its value.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
label string A label that describes the input's value.
limit number Limits the number of options which are displayed.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
placeholder string Placeholder text to show when there is no value to show. For example, "Enter full email address" for a field meant to contain an email address.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
tabIndex number Indicates if the widget is focusable, if it is reachable using the tab key, and if so, at what position.
  • a negative value allows the widget to receive "programmatic" focus, e.g. through scripting, but it is not reachable using tab;
  • 0 means that the widget is focusable and reachable via tab. Its relative order is defined by the browser;
  • a positive value means the widget is focusable and reachable via tab; its relative order is defined by the given value.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
value Dynamic The current value of the HTML widget.
valueIsRecord boolean Whether the value property is a primitive value or record.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focus() undefined

Focuses this widget.
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.
onInputChange(
  widget:Widget)		 This script will run on the client whenever the user changes the input value. For example, in a text field, this script will be run each time the user types a character or pastes text into the text field. This script is not run when the value of the widget is changed programmatically, i.e. through a binding or a script.
onValueChange(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value property of this widget changes. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue.
onValueEdit(
  widget:Widget,
  newValue:object)		 This script will run on the client whenever the value of this widget is edited by the user. The widget can be referenced using parameter widget and the new value of the widget is stored in newValue. Unlike onValueChange(), this runs only when a user changes the value of the widget; it won''t run in response to bindings or when the value is set programmatically.

Back to Top

VerticalSplit

A panel with a top and bottom child and a movable splitter.

Styles

Name Description
.app-VerticalSplit The primary style for the vertical split panel.
.app-VerticalSplitTop Style for the top panel.
.app-VerticalSplitBottom Style for the bottom panel.
.app-VerticalSplit-Splitter Style for the splitter.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
children PropertyMap The direct children of this Layout widget, identified by their names.
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
descendants PropertyMap All the children of this Layout widget recursively, identified by their names. This excludes any repeated children, such as rows in a List, cells in a Grid, Accordion, and their content.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
splitPosition number The position of the splitter from the left/top of the panel.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether all the children have a true valid property or no valid property. This can often be used in forms to determine whether all the input widgets in a form have valid values.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
focusFirstWidget() undefined

Focuses the first focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusFirstWidget();
focusLastWidget() undefined

Focuses the last focusable descendant.

Example: 

 app.pages.MyPage.descendants.Panel1.focusLastWidget();
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top

Widget

Represents any widget.

Properties

Name Type Description
align string If the widget is in-flow, it aligns the widget along the cross axis, i.e. horizontally for vertical panels and vertically for horizontal panels, of a single line of the flow panel, overriding the value of the parent's alignChildren.
  • inherited - The widget is aligned as specified by its parent (default).
  • start - The widget is aligned at the start of the cross axis of the line.
  • end - The widget is aligned at the end of the cross axis of the line.
  • center - The widget is centered in the cross axis within the line.
  • baseline - The widget is aligned such that their baselines align.
If the widget is not in-flow, it has no effect.
ariaLabel string Text that describes the content of the widget. This property sets the aria-label HTML attribute which is used by assistive technology to communicate the purpose of the widget to a visually impaired user.
autoHeight boolean The browser calculates the height of the widget. For example. if the widget's alignment is stretch and the parent has horizontal layout, the height of the widget expands to fill the flow-line's height. In particular, if the parent is set to nowrap, the widget will be as tall it's parent. However, if the alignment is other than stretch or if the parent has vertical layout, the widget will be as tall as its content.
autoWidth boolean The browser calculates the width of the widget. For example. if the widget's alignment is stretch and the parent has vertical layout, the width of the widget expands to fill the flow-line's width. In particular, if the parent is set to nowrap, the widget will be as wide it's parent. However, if the alignment is other than stretch or if the parent has horizontal layout, the widget will be as wide as its content.
childIndex number The index of this component in its parent children. For example, if the component is a row in a List widget, then the index is the row number (zero-based).
dataLoaded boolean Whether the widget is attached to the DOM and the widget's datasource has finished loading data.
datasource DataSource The current datasource of a widget. Datasources can be set on Layout widgets, and are inherited by that widget's descendants. Setting a datasource on a widget makes it easier for that widget and its descendants to access the properties of that datasource.
grow number When the widget is in-flow, this property specifies the grow factor, which determines how much the widget will grow relative to its siblings to fill the parent in the direction of the flow. For example, if a horizontal panel has two children, one with grow set 1 and another one with a grow factor of 2, the first widget will grow horizontally to use one third of the empty horizontal space in the panel, while the second one will grow horizontally, consuming two thirds of that space. If the widget is not in-flow, this property has no effect.
invisibilityType string If the widget is not visible, this specifies how it is made invisible, which is important for widgets in flow-enabled layouts.
  • absent - When the widget is not visible, it doesn't take up any space. This is equivalent to the CSS rule display:none.
  • hidden - When the widget is not visible, it is hidden but still takes up space. This is equivalent to the CSS rule visibility:hidden.
loaded boolean Whether the widget has been attached to the DOM.
name string The name used to refer to this widget in the editor and from scripting. Note that this name cannot contain spaces and must be unique within the top level page.
parent LayoutWidget Parent Layout widget that contains this widget on the screen.
root LayoutWidget Top level Layout widget (Page/Page Fragment) that contains this widget in its subtree. For example, if a widget belongs to a Page Fragment, widget.root returns that Page Fragment, rather than the Page that contains that Page Fragment.
styleClasses string A list of CSS style classes to apply to this widget. Multiple classes can be specified in a space delimited list.
Deprecated: use styles instead.
styles string[] A list of CSS style classes to apply to this widget.
title string The HTML title field of this widget. On most browsers, this displays as a tooltip above the widget.
valid boolean Whether the widget's input value (if present) and all it's children (if present) are valid.
validationDisplay boolean Whether to display validation errors using a popup near the widget.
validationErrors string[] The validation errors associated with this widget.
visible boolean True if the widget is visible, false otherwise.

Methods

Name Return Value Description
getElement() Element

Returns component's DOM element.

This method does not guarantee backwards compatibility, because the DOM structure of the element can change.
getFullPath() string

Gets the path of this widget in the hierarchy, for example: "Panel1.ListPanel2.Button3". This is useful for debugging.
validate() boolean

For input widgets, this will validate the widget's value against widget constraints, bound constraints (for example, field data validation), and the widget's onValidate() event handler. Updates the widget's "valid" and "validationErrors" properties. Returns true if the value meets all constraints or the widget doesn't have a value to validate, false otherwise.

For layout widgets validates all children and returns true if all of them are valid, false otherwise.

If a widget changes from invalid to valid as a result of this method, bindings involving the "value" property will be updated.

Events

Name Description
onAttach(
  widget:Widget)		 This script will run on the client when the widget is attached to the DOM. The widget can be referenced using parameter widget. Common uses for the onAttach event on a page are reading a browser cookie or initializing a datasource query from window URL parameters.
onDataLoad(
  widget:Widget)		 This script will run on the client when the data for the widget is loaded into view. The widget can be referenced using parameter widget. You should use this when some state in the page relies on data from the widget''s datasource being loaded before it can be set. For example, you might use this if some complex JavaScript needed to be run to initialize a widget, based on data from its datasource.

Note that many times a binding expression to the datasource can accomplish a similar goal, with less work. For example, if you only wanted to show a widget once the datasource is loaded, you should bind its visible property to @datasource.loaded. This has the advantage of automatically hiding the widget if the datasource was reloaded, while onDataLoad() is only called whenever a datasource finishes loading.
onDetach(
  widget:Widget)		 This script will run on the client when the widget is detached from the DOM. The widget can be referenced using parameter widget. You might want to have a script to update a cookie saving some state about the widget whenever it''s unloaded, and another script in onAttach to load data back from that cookie.

Back to Top