Parameter¶
The Parameter widget puts one of the page's parameters on the page as an input control, so visitors can change it. The control matches the parameter's type: a date picker for a date, a dropdown for a list of options, a switch for yes or no, a text box for text. Use it to build filters such as a year picker above a table, or a customer dropdown that drives a chart. It can also show a parameter's value read-only.
See also Button for passing values to another page, Data Table for a table that reacts to a filter, and Nav Link for links that carry values.
Using it¶
Say you want visitors to pick a year and have a table filter by it.
- Add a
yearparameter to the page in the Page ribbon tab under Parameters. - Drop a Parameter widget onto the page and set Parameter to
year. Give it a Label such asYear. - In the table's data source, map its year parameter to
{$params.year}.
When a visitor picks a year, the value lands in $params.year, the data source reloads, and the table shows that year's rows. See Page and Portal State.
Options¶
Only the options that apply to the bound parameter's type are shown.
| Option | Values | Default | Description |
|---|---|---|---|
| Parameter | A page parameter | — | Which parameter this widget shows. Add the parameter to the page first. A required parameter shows the note The selected parameter is required. |
| Label | Any text or template | Label |
Shown above the control. Leave it empty to show no label |
| Description | Any text or template | Empty | Shown below the control |
| Mode | Input · Display | Input | An editable control, or a read-only value |
| Render as | Switch · Checkbox | Switch | For switch parameters: which control to show |
| Text | Any text or template | Empty | For switch parameters: text beside the control. When set, it replaces the label |
| Rows / Resizable | 1 – 30 · On · Off | 4 · On | For JSON parameters: the height of the editor, and whether visitors can resize it |
| Render as | Dropdown · Tab group | Dropdown | For lookup parameters: a dropdown, or a row of tabs |
| Tabs Orientation | Horizontal · Vertical | Horizontal | For lookup parameters shown as a tab group |
| Min options for search | A number, 1 or more | 7 | For lookup dropdowns: the dropdown gets a search box once it has at least this many options. Use 1 to always show it |
| Placeholder | Any text or template | Empty | Shown in the empty control. Not offered for switches or tab groups |
| Icon | An icon key | Calendar for dates and month ranges, otherwise none | An icon inside the control. Offered for text, number, date and month range parameters, and for lookup dropdowns whose options are listed in the parameter itself. The brush button beside it sets the icon's style |
| Display Format | A format string | n;0;6 for numbers, d for dates, dt;MMMyyyy for month ranges |
In Display mode, how numbers, dates and month ranges are shown |
| Disabled Expression | An expression | Empty | In Input mode, greys out the control when the expression is true, for example {$params.country} == 'US' |
| Variant | Theme variants | Default | Picks the control's look from the theme. See Variants |
| Per-part theme styles | Theme values | From theme | Styling for the label, description and validation message, the field, its icon, and the control itself |
| Box Style | Sizing and spacing | 140px wide | The box around the control |
Tips¶
A few things to keep in mind:
- The control follows the parameter's type. To get a different control, change the parameter's type rather than looking for a setting here.
- The value lands in
$params.<name>, which any other widget on the page can read. - Required parameters show the required marker and validation message on their own in Input mode.