List¶
A data component, the List displays a roster of record items, which can be formatted in a template using merge syntax to control how the items render. This component allows end users to employ on-click actions from the List items to launch actions in other components on the page.
Using the List component¶
While typically employed with the Action Framework to update Page Includes on the page, the List can be used for a variety of purposes.
One common use case for this component is to put a List in a Responsive Grid section that lists records by name. When a name is selected, data from a different Skuid page is displayed via a Page Include (in another section of the grid).
Note
The content below assumes you have a Skuid page and at least one working model.
Add a List component to the page, then:
- Ensure that the List is accessing the correct model and name the List (if desired). (General tab)
- Determine what items display on the list by clicking Add fields on the component.
- Choose whether to include a search box. (Search tab)
- Give end users the ability to sort records based on field values. (Sort tab)
- Add Interactions that allow users to launch action when they select a List item.
Every List includes a header and a footer. These sections can include:
- Header
- the List’s title
- a search box
- a button for opening a sort builder
- filters
- mass action buttons
- Footer
- an indicator of which set of rows are showing
The component’s header and footer can be hidden using properties in the General tab.
Add items to a List¶
The power of the List component is in the items you choose to place on that List. Skuid gives you a lot of options from the Add feature and Add fields dropdown menus on the List component.
Customize the List display with any of the items from the Add features dropdown menu.
- Row Actions: Record-level actions represented by row buttons that use a record on the component as the context.
- Mass Actions: Enables the ability to select one or more records. Each selected row becomes context for the mass action.
- List filter: Add filters to the header of the List component.
Customize the List display with any of the items from the Add fields dropdown menu.
- Model fields: Displays a field’s name on the list.
- Template: Allows builders to add multiple field names (along with punctuation or symbols such as “+”) and display on the List.
- Avatar: Displays a small “avatar” image on the List.
- Icon: Displays an icon on the list.
- Image: Displays an image on the list.
When multiple items are added to the List, they are displayed in the order they appear in the Composer. To change the order, drag and drop the item by clicking on the Item’s column header.
In addition to adding multiple items to the List, you can also add fields to any item creating a “column” within the List:
- From the item’s column header, click Add fields.
Add Button Group¶
From the Add fields dropdown in a column, add a button group directly into the List component.
When you add buttons to the List component, these buttons have their own properties. All List button properties are the same as those for Ink Button Set buttons.
Configure List items¶
Configure the item’s properties (including formatting a Template or selecting the image source for Avatars, Icons, and Images) by clicking the Item’s name to open the Field properties pane.
Configure the layout of individual item columns in the List by clicking the item’s column header to open the Column properties pane.
Component actions¶
Component actions are available using Run component action.
Go to page
Navigates to the Target page in the component.
- Target page:
- First page
- Last page
- Previous page
- Next page
Open all drawers
Opens drawers for all rows in the selected List.
Close all drawers
Closes drawers for all rows in the selected List.
Properties¶
Component properties¶
When you add a List to the page, there are several properties you can modify:
General tab [[]]¶
Model: The List will draw and display data from this model.
Title: The title that displays above the List. (If left blank, the List does not have a title.) Can also contain rendered HTML if Allow HTML in title is enabled.
Allow HTML in title: Determines HTML rendering behavior for Title contents. When enabled, any HTML syntax will be rendered. When disabled, HTML syntax is displayed as plain text. For example:
Enabled:
This text is importantDisabled:
<strong>This text is important</strong>
Display tab [[]]¶
Pagination section [[]]¶
Visible rows: Controls how many rows are visible. This property’s value can be one of the listed choices (which includes showing all available rows) or a custom number. The default setting is 10 rows.
This choice is displayed at the bottom of the component at runtime and can be overridden by the end users.
- 5
- 10
- 25
- 50
- Show All
Note
Searches, sorting, and filters will query the entire set of records—even the rows that haven’t been loaded into the List yet.
Show page size dropdown: Checked by default, this displays a page size indicator at the bottom of the list. This indicator allows users to choose to display more or fewer records per page, overriding the Visible Rows setting.
Reset pagination on query: Click to reset to the first page after any edits or queries to the model.
Drawers section [[]]¶
- Enable drawers: When checked, Skuid adds a > (Left Arrow) to the left of any fields, icons, avatars, or images on the list. Click this arrow—or click Configure Drawer—to open the Drawer modal.
Advanced section [[]]¶
- Unique ID (optional): Skuid automatically generates an alphanumeric ID for the component; if preferred, give it a practical name.
Other section [[]]¶
Row actions on left: By default, Row Actions are displayed on the right. If checked, they will be displayed on the left.
Show “Load more” button: If the Max # of records property on the model is set to a limiting number, checking this allows the end user to load additional records.
Show header: If checked, the List header will display.
Show footer: If checked, the List footer will display.
Note
Show header/footer supersedes any settings for individual elements in the header or footer. For example, if Show search box is checked in the Search tab, but Show header is also checked, the search box (which sits within the header) will not display because the header is hidden.
Search tab [[]]¶
In this tab are properties that control whether or not you have a search box, and when search terms and conditions are applied.
Search properties [[]]¶
Show search box: If checked, Skuid displays a search box above the component.
Search method: Determines if a search will query the server and filter its data, or filter local data on the client.
Server (default): Returns search results from all data on the server.
Client: Returns search results from only the data that is currently loaded on the page. Large data sets may require lengthy time to filter. If end users commonly need to sort only the data they have loaded within the page—as opposed to every record on the server—this property may speed the filter process.
Warning
If the server contains a large data set not yet loaded into the page, but Search Method is set to Client, the filter may return incomplete results because it’s filtering incomplete data. This may result in unexpected omissions.
Search results: Determines which results are displayed based on the end user’s search query.
Match exactly: Results are only shown for records that contain the search term verbatim.
If the user searches for George Washington, only the records containing George Washington exactly as written—with no other terms in between—would be displayed.
Contain all terms: Results are shown for records that contain all of the terms in the query, even if they may appear in a different order or disconnected from each other.
If the user searches for George Washington, any record containing George and Washington would be displayed, as long as both terms were anywhere within the record.
Contain at least one term: Results are shown for records that contain any of the terms in the query.
If the user searches for George Washington, any record containing George or Washington would be displayed.
ARIA label: Determines what description will be read by assistive technology, such as screen readers, by setting the aria-label HTML attribute, which is part of the Web Accessibility Initiative—Accessible Rich Internet Applications (WAI-ARIA) spec.
Used to describe elements where text may not be visible, this property can be a specific string of text, the merge variables of one or more fields, or a combination of the two.
Search box placeholder text: The text that appears in the search box before the end user starts a search. (The default is “Search.”)
Empty search behavior: Determines what happens when the search box is emptied.
- Re-query for model data (default): The data displayed in the component returns to the state it was in when you first loaded the page.
Search fields [[]]¶
Specifies which fields will be searched against from the component’s search bar.
Note
Why do this? If you want to use a component to display the list of search results—handy when you have a lot of search results—you need to have an empty component each time you do a new search, so you can display the newly returned results in it. Without this property, the component’s model will be re-queried when the text is cleared from the search box.
Search fields: Specifies which fields will be searched against from the component’s search bar.
Note
Depending on the data source used for the model attached to the component, this property may not be available.
Use SOSL to improve search performance (Salesforce data sources only): SOSL quickly can search multiple objects at a time within a single search query. SOSL does not directly search the database, but instead queries an index of Salesforce text fields. Individual search fields may not be added when this property is enabled.
Warning
Because the search is against the index, results are limited to what is present in the index, and will not include data that may have been recently updated in the database. The index updates very quickly, but expect a delay of up to 30 seconds between changes made to the database, and their appearance in the search results.
Note
SOSL can search Text fields (including Long Text fields), but not Picklist fields and Reference fields.
Fields to search: Sets which Types of fields to query with SOSL. The options are:
- Name Fields (default)
- All Text Fields
- Email Field
- Phone Fields
- SideBar Fields (Name, Phone, Email, External Ids)
Searches on Salesforce data sources can use one of two query languages: SOQL or SOSL. SOQL can only search one object at a time in a single query, but searches all searchable fields in that object in real-time.
Field: Skuid searches on searchable fields by default. Search can be narrowed to individual fields by clicking
Add new Search Field, and then using the field picker to select the field.Note
- (Salesforce data sources only) SOQL can search Picklist fields and Reference fields, but not Long Text fields.
- You can add multiple search fields.
Search operator: Select from the following logical operators:
- =
Skuid SFX [[]]¶
By default, Salesforce Objects use SOQL. To ensure proper functionality, enable the Allow Search property on any Salesforce objects to be included in the search.
For more information on using these search options with Salesforce, check out Salesforce’s SOQL and SOSL Reference Guide.
Sort tab [[]]¶
Sort properties [[]]¶
These properties determine the appearance and behavior of the Sort Builder.
- Show sort builder: Check to display the Sort Builder in the component at runtime.
- Button icon: The icon to display next to the label. Click the icon picker to select a different icon.
- Button label: The label text that appears on the Sort Builder at runtime. Change the text to match what you want to say to your end users.
- Sort client-side: Check to only sort on field values that are loaded into the page at the time the sort is applied. This means that the sort will be applied to data in the model, not to data still on the server.
Interactions tab [[]]¶
Action type: Determines the type of user interaction that triggers the action script.
- Right-click: The right-click interaction will launch the actions added here. A common pattern is to create a customized context menu by using the Show/hide menu action.
After-click state: Determines how a List item behaves after it has been selected.
- No change: The item (despite being clicked) displays as unselected.
- Clicked item displays as selected: The item displays as selected in the List.
- Disable the browser’s default menu?: Override the browser’s context menu for the Skuid page, component, or element. If the browser’s context menu is not disabled, then the actions will run while the browser’s context menu appears on screen.
Note
Using a Page Include with your List? There’s a specific action for that: Run component > Page Include.
- Skuid page: The name of the associated page.
- Page Include component Id: Click to select the Page Include from the list. (If you have given the Page Include a unique name, it will appear here). When a Page Include is selected, a flashing yellow outline will indicate the chosen item within the canvas.
- Query string: Use id={{Id}}. This tells the Page Include to load the record whose ID matches the ID of the record the end user clicked.
Styles tab [[]]¶
Global styles for this component are set in the Design System Studio. The following Style properties can be adjusted for an individual page.
Style variant: Style variants are created and set in the Design System Studio. Some components have pre-defined variants for a specific aspect of a component’s style. Also, Skuid builders can style and customize elements to create their own themes within the DSS. These themes will dynamically populate as selectable values in the Style Variant dropdown menu.
Note
To refresh available style variant options, click
Refresh style variants.This is useful for when changes to the design system (like style variants or variable options) have been made in another browser window or by another user.
Margin: Sets a component’s margin (the space around it) relative to other components on the page.
- To set margins for all sides, click border-all All.
- To set margins for each side individually, click border-separate Separate.
Margin values can be set to any configured spacing variable for the page’s design system. Margin cannot be set an arbitrary value; it must use a design system variable.
Display logic tab [[]]¶
Standard display logic options are available to display or hide the component or feature.
Nested elements¶
When you add items to a List, there are several properties you can modify:
Column properties [[]]¶
Click the item (Field, Template, Avatar, Icon, or Image) element to configure the following options:
- Width behavior: Determines the way items fill the List.
- Fill: Allots a percentage of the space to the selected item, based on the fill ratio.
- Fill Ratio: This sets the amount of space for this item relative to other items in the List. For example, a flex ratio of 2 will be double the width of an item with a flex ratio of 1.
- Fixed: Allots a fixed amount of the space to the selected item, based on the Width settings.
- Width
- Extra Small
- Small (default)
- Medium
- Large
- Extra Large
- Custom
- Custom width amount: This can be specified using px, em, %, vh, or vw measurements.
- Width
- Fill: Allots a percentage of the space to the selected item, based on the fill ratio.
Item properties [[]]¶
Click the item (Field, Template) element to configure the following options:
Type:
- Field: Uses the field Id, i.e. {{Name}}
- Field label: Uses the plain language field name, ie., Account Name.
- Template: Opens the Template property field.
- Template: The fields (selected using the field picker) to display in the queue.
Display style override: By default, any additional fields added to an item use the default text styling. To override that, select one of the following additional style options (all of which are configured in the Design System Studio)
- None
- Style 1
- Style 2
- Style 3
Field: The field to use for the list item. Select from the picklist.
Click the item (Avatar, Icon, or Image) element to configure the following options:
Style variant: The format of the Avatar
- Default (This is set in the Design System Studio)
- Circular
- Square
Image URL: The URL for the image to be used as the Avatar. Or, pick an Image field from the picklist.
Icon: The image to be used as the icon. Select from the picklist.
Alternate text: Add descriptive text about the image that can be used by access/assistive technologies such as screen readers and conforms to Web Accessibility Initiative—Accessible Rich Internet Applications (WAI-ARIA) specifications. This property can be a specific string of text, the merge variables of one or more fields, or a combination of the two. Alt text also increases a search engine’s ability to index the image.
Note
If no Alternative Text is specified, access/assistive technologies will either ignore the image, or (in some cases) speak a generic label, such as “Image displayed.”
Size: The size of the Avatar or Icon.
- X-Small
- Small
- Medium
- Large
Fallback type: An alternative if there is not an Avatar available.
- Text: Replacement text for the Avatar.
- Fallback text: The text to be displayed instead of the Avatar.
- Icon: Replacement text for the Avatar.
- Fallback icon: The icon to be displayed instead of the Avatar.
- Text: Replacement text for the Avatar.
Drawer properties [[]]¶
General tab
Show drawer icon: Determines whether or not to display an icon next to the record. If unchecked, the drawer can be opened and closed by configuring a global action (in a Table component) or row action (in a Table or List component) to run the Open/Close A Drawer action.
Icon: Click the icon picker to select a different icon.
Configure drawer: Opens the drawer configuration modal.
Before load actions
Before Load Actions refers to actions used before a drawer is loaded. Generally, these actions are used to activate and set the values of model conditions, and to query models to ensure that the contextually-relevant data will display in the drawer.
For more information, see Add Nested Rows to your Table with Drawers