Use the Form widget to let users create and edit an object by filling in fields.

What a Form widget actually is #

The Form widget is the Text Grid widget in form mode. Selecting the Form tile in the widget palette opens the same configuration dialog with editing turned on and one extra step, and the result is stored as a Text Grid.

That matters in two practical ways:

• everything in Text Grid widget about items, binding, and layout applies here unchanged;
• a widget created as a Form appears as a Text Grid in the widget list.

This page covers what is different in form mode.

When to use it #

Use a Form widget when users need to supply values rather than read them:

• a Create new account page, where users add an object from scratch;
• an edit page for one object, where a table row would be too cramped;
• a request or submission page for users who never see the underlying dataset.

Where users need to add many objects quickly, a Table widget with Add Row enabled is faster, because it keeps them on the list.

Add a Form widget #

To add a Form widget:

1. Open the page and enable Layout edit mode.
2. Select Add a widget.
3. Select the Form tile, or drag it onto the page.
4. Work through the five configuration steps.
5. Select Create.
6. Save the page layout.

The steps are Widget, Fields, Properties, File Settings, and Submit Button. The first four behave as they do for a Text Grid, except that items are called fields: the buttons read Add Field and Save Field, and the label field reads Field Label.

Two differences beyond the naming. A field offers no Link Configuration section, because a form is for entering values rather than following them. And the Properties step shows no editing pencil, because every field on a form is editable.

Step 2: Fields #

Fields are configured exactly like Text Grid items – each names an Object, which is a page parameter, and a Property of that parameter’s dataset. Boolean Field Input Type, Enable create new object, Control, and Add multiple fields at once all work as they do for a Text Grid.

One switch is specific to form mode: Auto-populate fields from page parameters.

• Switch it on when the form edits an existing object. The fields open filled with that object’s current values.
• Leave it off when the form creates a new object. The fields open empty. This is the default.

A create form that auto-populates shows the values of whatever object the parameter happens to hold; an edit form that does not populate looks blank and quietly overwrites values with nothing.

Required properties that are not on the form #

Auclio validates the whole object on the server, not just the fields you have shown. If the dataset marks a property as required and the submitted object does not carry it, the save is refused and the response names the missing properties.

Put every required property on the form.

Step 5: Submit Button #

This step exists only in form mode.

• Button Text – the label, for example Submit request. It is required.
• the icon preview, which opens Select an Icon, and Icon Position – an optional icon, placed Left or Right of the text.
• Button Style – the colour, from Default, Primary, Secondary, Success, Warning, and Error. This is the Button widget’s set without Info.
• On Submit Behavior – what happens after the form is submitted:
  • Do Nothing – the form stays as it is;
  • Refresh Form – the form reloads, clearing it ready for the next entry;
  • Execute Actions – the configured actions run, which is the only setting under which the button can navigate.

Choose Execute Actions and three more controls appear. Link to decides where the user goes: choose Url and enter an address in Url, or Page and pick the destination in Select Page. An icon toggle beside them controls whether the destination opens in a new tab, and its tooltip reads Open link in new tab or Do not open link in new tab.

Pair these deliberately. A create form used repeatedly wants Refresh Form, which needs no destination. A create form used once wants Execute Actions with a Link to destination, so the user lands on the new object or back on the list.

Recommendations #

When configuring a Form widget:

• decide first whether the form creates or edits, and set Auto-populate fields from page parameters to match;
• include every required property the dataset defines, since the server checks all of them;
• order the fields the way a person would fill them in, not the order the dataset lists them;
• label fields in the users’ language;
• use Refresh Form for repeated entry, and Execute Actions with a destination for one-off entry;
• tell users where they will end up – a button reading Submit that navigates away is a surprise;
• test as a non-administrator, since creating an object needs Modify cascading from the dataset’s Children slot.

See Configure permissions for detailed instructions on granting the access a form needs.