--- title: Table widget description: "Use the **Table widget** to display multiple objects from a dataset. Depending on how you configure it, users may be able to search, filter, sort, group, open, create, edit, or delete those objects. ## When to use it The Table…" url: "https://auclio.com/documentation/table-widget/" updated: "2026-10-16" category: Widgets --- # Table widget Use the **Table widget** to display multiple objects from a dataset. Depending on how you configure it, users may be able to search, filter, sort, group, open, create, edit, or delete those objects. ## When to use it The Table widget is the workhorse of most applications. Use it whenever a page is about a list rather than about one object. Use it for: - the main list page of a dataset - all accounts, all requests, all incidents; - a filtered list on a details page, such as the contacts belonging to one account; - any page where users need to add objects quickly, one row at a time. Where a page is about a single object, use a Text Grid widget instead. ## Add a Table widget To add a Table widget: 1. Open the page and enable **Layout edit mode**. 2. Select **Add a widget**. 3. Select the **Table** tile, or drag it onto the page. 4. Work through the five configuration steps. 5. Select **Create**. 6. Save the page layout. Configuration is arranged as five steps: **Widget**, **Data Source**, **Columns**, **Table Properties**, and **File Management**. Move through them in order the first time. When editing an existing widget you can jump straight to the step you need. ## Step 1: Widget The first step holds the widget's identity and its behaviour. Three collapsible sections group the options, each showing a summary of its current settings. ### General information **Widget Title** and **Description**, each with an eye icon controlling whether it is shown to users. ### Table properties - **Sidebar** - adds a collapsible panel to the side of the table. When on, a **Sidebar Panels** block appears where you choose which panels are available: **Filters**, **Columns**, and **AI Assistant**. The Columns panel lets users show and hide columns themselves; the Filters panel gives them a full filter builder. Switching **Sidebar** on selects **Filters** and **Columns** for you if nothing is selected yet, and clearing every panel switches **Sidebar** off again, since a sidebar with no panels has nothing to show. - **Group Bar** - shows a strip above the table reading *Drag here to set row groups*, where users drag a column heading to group the rows by it. ### Data Editing Three switches decide what users may do to the objects: - **Add Row** - users can create objects; - **Edit Cells** - users can change values in place; - **Delete Row** - users can delete objects. Switch on only what the page needs. A reference list that nobody should change is clearer with all three off. When **Add Row** is on, **Add Row Mode** decides how creating works: - **Pinned Row + Manual Submit** - an empty row is pinned at the top of the table. The user fills it in and submits it deliberately. This is the safest choice, and the right default. - **Pinned Row + Auto Submit** - the same pinned row, but it saves itself as soon as every required value is present. Quick for rapid entry, but easy to trigger by accident. - **Modal Popup** - a dialog opens and the user completes it before the row is added. Best when the dataset has many required properties, because a dialog has room for them. These switches only permit an action. Whether a given user can actually perform it is decided by their permissions on the dataset. ### Display Options - **Column Auto-Size** - how column widths are calculated. **Fit Contents** sizes each column to its widest value, which suits tables with a few columns. **Fit Grid** spreads the columns across the available width, which suits tables that should fill the page. **No Auto Size** keeps the widths you set. - **Text Wrap** - long values wrap onto several lines instead of being cut off. - **Header Wrap** - the same for column headings, useful when headings are longer than their values. - **Tree View** - displays the rows as a hierarchy. Use it for a dataset with a parent dataset, where objects genuinely nest. ## Step 2: Data Source This step decides which objects the table reads. Leave **Use External Connection** off to read a dataset stored in Auclio. Switch it on to read from an external connection, then choose it in **Connection**. Select the dataset in **Dataset**. Both fields offer an option to create a new dataset or connection without leaving the dialog - **Create new dataset** and **Create new external connection**. Once a dataset is selected, **Edit Dataset** opens that dataset's own dialog, so you can add a missing property without abandoning the widget. A **Lock Configuration** control guards the step. It appears once the widget has joins or columns to protect. While the configuration is locked, joins and columns cannot be deleted, and the connection, dataset, and **Edit Dataset** controls are disabled. The button then reads **Unlock Configuration**; unlock it deliberately when you intend to restructure the widget. ### Joins A table can pull in columns from a second dataset by joining it. Use a join when users need one flat list combining both - contacts with their account's country alongside, for instance. The **Joins** block appears below the dataset once the connection offers more than one dataset. Select **Add Join** and complete the join as a sentence: which dataset to join, then which property matches which object. Only Dropdown properties can carry a join, because a Dropdown property is what relates two datasets, and the join can run in either direction - from a Dropdown property on this dataset out to its target, or from a Dropdown property on another dataset back to this one. Finish with **Create Join**, which is disabled until every part of the sentence is filled in. Editing or deleting a confirmed join deletes every column that came from the joined dataset, and Auclio warns you before it does. Rebuild those columns afterwards. Where you instead want a list scoped to one object, do not join. Put a Table widget on a details page and filter it by the page's parameter. ## Step 3: Columns This step has two tabs. ### Columns One entry per column, listed in the order they appear in the table. Drag a row by its number to reorder the columns. Two buttons sit above the list. **Add Column** opens an empty column dialog. **Auto Map Dataset** creates a column for every property of the main dataset and of each joined dataset in one action, which is the fastest way to start; delete the columns you do not want afterwards. Each column's dialog holds: - **Column Label** - the heading users see. This is independent of the property name, so a property called `nameOrTitle` can appear as `Account`. - **Dataset Field** - the property the column reads. This is where the column is bound to data. When the widget has joins, a **Dataset** field appears first, so you can choose whether the column reads the main dataset or a joined one. - **Boolean Field Input Type** - for boolean properties, whether the cell shows a **Checkbox** or a **Dropdown**. - **Enable create new object** - for dropdown properties, lets users create a new object in the target dataset directly from the cell. - **Link** - makes the column's values clickable. Set **Type** to **External Link** and enter a **URL**, or to **Page Link** and choose a **Target Page**, then map the destination's parameters under **Link Parameters** using **Add Parameter** and the **Name** and **Value** pairs. Linking a column to a details page is what turns a list into a navigable application. Save with **Save Column**. Two limits are worth knowing. A dropdown column offers no **Link Configuration** section at all, because the API rejects a link on a dropdown column. And once a column with a link has been saved, its link settings are locked - the dialog says *Link settings are locked for existing items* - so change a column's link by deleting the column and adding it again. ### Column Properties Per-column behaviour, shown as a grid with one row per column: - **Column Name** — which column the row refers to; - **Default Value** — the value a new row starts with. It takes a static value, a page parameter, another property of the row, or a date expression, and the picker offers whichever of those suits the column’s data type. Workflow columns and read-only system properties offer no default; - **Visible** — whether the column appears at all. On by default; - **Filtering** — whether the column offers a filter. On by default; - **Grouping** — whether users can group the rows by this column. On by default; - **Sorting** — whether users can sort the rows by this column. On by default. Clear it and the column heading no longer sorts when selected; a default sort you set on the column in the **Table Properties** step still applies, but users cannot change or clear it; - **Comments** — whether each cell in the column offers a comment button, badged with the number of comments on that value. Off by default; - **Editable** — whether this specific column can be edited, within a table that allows editing. On by default; - **Min Width** and **Max Width** — bounds in pixels; - **Control** — an optional per-row condition on editing, opened in its own dialog. The headings of **Visible**, **Filtering**, **Grouping**, **Sorting**, **Comments**, and **Editable** each carry a checkbox that turns that property on or off for every column at once. Use it to clear everything and then set the few columns you want. **Control** opens **Column Control Settings**, where you build condition groups under **Enable column when**. The conditions are evaluated per row: where the expression is true the cell can be edited, and where it is false the cell is disabled. **Copy from** reuses another column’s conditions, **Apply to all columns** pushes the current ones to every column, and **Clear** removes them. Two more things about this grid are worth knowing. **Visible** gates the rest. Switch it off and every other control on that row is disabled except **Default Value**, because a hidden column has no behaviour to configure but can still supply a value to a new row. **Editable** is the setting people most often miss. A table with **Edit Cells** switched on still shows a read-only column if that column’s **Editable** is cleared — which is exactly how you keep an identifier or a calculated value uneditable while the rest of the row stays editable. ## Step 4: Table Properties This step sets the state the table opens in, across four tabs: - **Admin Filters** — filters applied on the server, before any row reaches the table. Use this to scope a table to the objects that matter, such as open requests only. Conditions are built in groups, and the groups are combined with each other. Admin filters never appear in the grid’s own filter controls, so users can neither see nor remove them. - **Grid Filters** — default column filters, applied when the table first loads as if the user had set them. - **Grouping** — the columns the rows are grouped by from the start. Select **Add Group** and choose a column for each level; the levels are shown as a chain, and rows are grouped in that order. - **Sorting** — the initial sort order. Select **Add Sort**, choose a column, and set it to **Ascending** or **Descending**. Add several to sort by more than one column. Grid filters, grouping, and sorting are the starting point, not a restriction: users can change them afterwards, unless you have locked a group, hidden a sort, or disabled the relevant column properties. ## Step 5: File Management This step controls what users can do with files attached to the objects in the table. It applies only when the dataset allows files. Decide first where files appear. Under **Files Location**: - **Side Panel** - a panel beside the table showing the selected row's files; - **Files Column** - a column showing each row's files, which you can drag to any position in the Columns step. Then switch on what users may do, under **Files Settings**: **Upload**, **Delete**, **Download**, and **Preview**. All four stay disabled until at least one location is on, because an action with nowhere to appear does nothing. When both **Upload** and **Files Column** are on, **Upload button label** and **Upload button tooltip** appear. They rename the upload control, so it can read something meaningful such as `Attach signed contract` instead of the default `Upload new file`. If the dataset does not allow files, the step says so and offers to open the dataset instead. See [Work with files](/documentation/work-with-files/) for detailed instructions on file behaviour and limits. ## What users can do in a finished table Right-clicking a table offers, depending on configuration and permissions: - **Add new row** on an ordinary row, and **Submit new row** and **Cancel** on the pinned new row; - **Delete row**, or **Delete {n} rows** when several are selected; - **Bulk edit {n} rows** — applies the same value to the selected rows. The entry appears only when between 2 and 10 rows are selected, the table has **Edit Cells** switched on, and at least one column can be edited; - **Unselect {n} rows**; - **Preferences**, whose submenu holds **Save**, **Reset**, and **Delete** for the user’s own saved arrangement — **Delete** removes it, and the table returns to the arrangement you configured; - the grid’s own copy, copy-with-headers, and export entries. Entries that would do nothing are not offered. Delete disappears when nothing in the selection can actually be deleted, and the file actions on a row are unavailable where that object’s files are read-only — see [Work with files](https://auclio.com/documentation/work-with-files/). The column menu, opened from a column heading, adds **Clear this column filter** and **Clear all columns filters** whenever filters are active. ### Selecting rows and whole groups When the table allows deleting, or has a column that can be bulk edited, each row carries a checkbox, and so does the heading of the selection column, whose tooltip reads **Select all rows** or **Clear selection**. It selects every row that matches the current filters, not only the rows loaded so far. In a grouped table, each group row has a checkbox too, labelled *Select all rows in group*. It selects every row in the group, including rows not yet loaded because the group is collapsed. Clearing individual rows afterwards leaves the group’s checkbox partly filled, and those rows are left out. A selection made this way can be bulk edited or deleted with the buttons in the table’s header row, **Bulk edit selected** and **Delete selected**. The ten-row limit on bulk editing does not apply to it: the bulk edit dialog says *All rows in the selected group will be updated*, and the change is applied on the server, row by row, under each row’s own editing rules. A large edit or delete runs in the background, and the table refreshes once it has finished. ### Filtering dates and times A Date, DateTime, or Time column’s filter offers **Equals**, **Not Equal**, **Less Than**, **Less Than or Equal**, **Greater Than**, **Greater Than or Equal**, and **In Range**, as well as **Empty**, **Blank**, and **Not Blank**. **Less Than or Equal** and **Greater Than or Equal** include the date or time you enter — on or before it, and on or after it — where **Less Than** and **Greater Than** leave it out. ### Clear canvas A user who has grouped, sorted, and filtered a table and wants to see it plain again can use **Clear canvas**, the broom icon on the widget’s floating toolbar. Its tooltip reads *Temporarily clears all grouping, sorting and column filters for this session. Admin defaults are not affected.* It appears only when there is something to clear. **Clear canvas** removes every column filter, every sort, and every grouping from the table as the user sees it, including those set on the **Grid Filters**, **Grouping**, and **Sorting** tabs. It leaves alone what users cannot change anyway: locked groups, hidden sorts, and admin filters. It does not save anything. The user’s saved preferences and your configuration are unchanged, and reopening the page restores them. ### Grouping users cannot undo Each group you set on the **Table Properties** step has a lock beside it. A locked group’s pill in the group bar has no remove control, so users cannot take it away; an unlocked group starts the table grouped but users can remove it. Groupings that existed before 26.9 are locked, which keeps them working as they did. Users can still add their own grouping beneath yours, reorder what they added, and remove it again. ### The dataset status icon A table reading a connected dataset shows a small status icon in its header. On a clean, successful refresh it stays hidden until you hover the header, so an application that is working shows nothing. Every other state — refreshing, queued, failed, terminated, skipped, or never run — stays visible. Only administrators see it. While a refresh is queued or running, the icon is updated every few seconds, so it shows the refresh’s progress without the page being reloaded. The table itself updates as objects change, including the objects a refresh changes. Select the icon to open **Dataset Refresh History**, which lists the last 30 refresh runs for the dataset. From there, **Edit dataset** opens the dataset’s own dialog, and **Trigger Refresh** starts a new refresh after asking you to confirm, because a refresh re-syncs every object from the external source and can take a while on a large dataset. A dataset refresh is not the same as the **Refresh widget data** button on the widget’s floating toolbar, which only reloads what this one table shows. Use the widget button when the table looks out of date, and a dataset refresh when the source data has changed or the dataset’s query or schema was edited. ## Recommendations When configuring a Table widget: - show the columns users need and no more; extra columns make a table harder to read, not more useful; - set a **Column Label** in the users' language rather than accepting the property name; - link one column to a details page, so the list is a way in rather than a dead end; - use **Fit Grid** for a table that fills a page and **Fit Contents** for a narrow one; - start with **Pinned Row + Manual Submit** and only move to auto-submit if users ask; - apply a default filter so the table opens on the objects that matter; - disable editing per column for identifiers and calculated values; - test with a non-administrator account, because permissions decide what the table can actually show.