Widgets

Widgets are building blocks used to create pages. They can be anything from simple labels that display text to complex forms that allow users to view and edit data.

App Maker's drag-and-drop page creation make widgets straight-forward to use, while their extensive properties give you the power to customize them and add functionality to build a fully-featured UI.

Types of widgets

Access widgets through the widget palette widgets in the upper-left corner of the page editor. App Maker groups the palette's widgets into categories to make them easier to find:

CategoryPurposeExamples
Data Widgets capable of displaying or editing model data. These are composite widgets—hierarchies of widgets including panels, labels, text boxes, and buttons. You can edit the output of the wizards. Form, Table
Input Widgets that handle user input like clicks or text entry. Button, Label, Text Box, Text Area, Checkbox, Dropdown, Date Box, Radio Group, Star Rating, Slider, Suggest Box, Text Editor, Multi Select, User Picker, Drive Picker
Display Widgets that display text, images, and other relatively non-interactive UI elements. Link, Image, Google Map, Help Icon, Spinner, Html, Pager
Layout Widgets used to arrange other widgets. They can also take datasource assignments. Fixed Panel, Horizontal Panel, Vertical Panel, List, Grid, Accordion, Tabs, Horizontal Split, Vertical Split
Charts Widgets that display visualizations of data as charts. Bar Chart, Line Chart, Pie Chart, Table Chart
Page Fragments A palette of page fragments that you've created. UI elements repeated on multiple pages, such as page headers and footers
Your Images A palette of images that you've uploaded for your app. Product logos, custom icons

Widget properties

Each widget has editable properties that let you specify everything from what data it displays, to where it's positioned, and even how it responds to user input. Use the Property Editor to the right of a page's canvas to view and edit properties of the currently-selected widget.

The Property Editor groups properties by their function. The exact properties in each group vary from widget to widget.

Property group Description
Widget name This group consists of two fundamental widget properies—name and datasource—and one or more additional properties specific to the widget's function.
Performance settings This group has a single property that controls when child widgets load. This property only appears for pages, layout widgets, and data widgets that contain layout widgets.
Layout Properties in this group specify the widget's position and size.
Spacing Properties in this group specify the widget's margin and padding.
Events Properties in this group determine how the widget responds to events such as data loading and user input.
Data Validation Properties in this group set validation requirements for text input widgets. It only appears for relevant input widgets.
Display Properties in this group affect the appearance and visibility of the widget.
Flow Properties in this group determine how flow-enabled layout widgets position their children. It only appears for layout widgets.
Other Properties in this group control how validation errors display and set the widget's HTML title. On most browsers, the HTML title displays as a tooltip.

Fundamental properties

Every widget has two fundamental properties:

  • Name—An identifier used to reference the widget in databinding, scripting, styles, and more. Widget names must be unique to their page, and can't start with a number or contain spaces. App Maker automatically generates names when you add widgets to a page, but it's often helpful to rename widgets to something memorable for later reference.
  • Datasource—Assigns a datasource to give the widget easy access to the source's data. Datasources can only be assigned on form and layout widgets. All other widgets inherit their datasource from their parent layout widget.

Widget life cycle

Widgets go through a simple life cycle—first App Maker creates them, and then attaches them to a page so they're visible. App Maker detaches them when they're no longer needed. Widgets can be attached and detached multiple times, but the are created only once.

Creation

When App Maker creates a widget, it sets the widget's properties and builds its HTML. You can access widget properties immediately after creation through the app.pages property, even if a widget is not yet attached to a page. By default, App Maker creates most widgets immediately after a user accesses an app. Lists and related widgets are an exception—App Maker only creates their children after their datasources load.

Attachment

When App Maker attaches a widget to a page, it's actually inserting the widget in the page's HTML structure, or DOM, making it visible to users. App Maker attaches most of a page's widgets when a user visits, and unloads them when they leave. Again, lists and related widgets are exceptions, because their children only attach after their datasources load, and because they can attach and detach new rows as their datasources change.

App Maker sets up widget bindings when it attaches widgets and removes them when it detaches widgets. This means two things—you can't rely on widget properties to set values before a widget's attached and widget attachment often triggers server requests as datasources load to populate bindings.

All widgets have onAttach, onDetach, and onDataLoad events that execute code in response to changes in widget life cycles. Read more about these events in Widget Logic.

Performance settings

You can control when your app's pages and widgets are initialized. By default, App Maker downloads everything when a user opens the app. As you add pages, though, you may need to delay the loading of some content to keep the app from taking too long to open.

To control how your app initializes content, click a page or panel, and then click Performance settings in the Property Editor. Choose one of the following options:

  • Complete initialization—App Maker initializes all pages and widgets when the user opens the app. This is App Maker's default setting, and it works best for smaller apps. Using this option on every page can make a large app with complex pages take too long to open.
  • Partial initialization—Choose this option for panels or lightweight pages in large apps. App Maker downloads the content and structure of a page or panel when a user opens the app. However, widgets aren't initialized until the user opens their parent page. This option makes the app load faster than the default setting, but it can increase the load time for individual pages.
  • Deferred initialization—This option is best for complex pages in large apps. App Maker doesn't load the page or panel structure unless the user opens the parent page. The app displays an animated progress indicator while App Maker downloads content and builds the page. This option makes the app load faster, but individual pages with this setting are slower to load.
  • Script-based initialization—Use this option if your app includes widgets that are used only when certain conditions are met. You can write a script that calls createChildren when the user performs the actions you specify. App Maker won't load child widgets unless they're needed.

If your app takes too long to load, you might, for example, leave the most critical pages of your app set to Complete initialization. You can then delay the loading of other pages by setting them to Partial initialization. If you find that it still takes too long for your app to load, try setting some pages to Deferred initialization.

Keep in mind that the properties and bindings of a widget are inaccessible until that widget is initialized. You'll need to thoroughly test any custom performance settings before you deploy these changes to users.

Learn more about app design best practices.