Welcome to @pega/lists-react
To import
import { RepeatingStructures } from '@pega/lists-react';
To consume
<RepeatingStructures
meta={meta}
ref={compRef}
apiContext={{
...apiContext,
stateUpdateCallback
}}
renderFactory={renderFactory}
formatters={repeatFormatters}
additionalInfo={additionalInfo}
...
/>
Table configuration (meta - prop)
Property | Value type | Mandatory | Default value | Notes |
---|---|---|---|---|
itemKey | String | Yes | Name of a field to use as the key of the rendered item(s) in the view. This field need not necessarily be one of the fields configured for display as part of the field definitions array. This field is directly looked up in the item data. | |
patchQueryFields | String array | No | Array of fields(extra) to be included in a query | |
sortOrder | String array | No | ['asc', 'desc', null] |
Array denoting sort operation order. Default is a tri-state sort |
displayDensity | Array of options | No | [{ name: 'Short', id: '1' }, { name: 'Medium', id: '2' },{ name: 'Tall', id: '3' },{ name: 'Full content', id: '4' }] |
A map of names(for display) and id(for persistence). The id values have specific behavior(s) associated with them |
height | Object | No | height: { minHeight: 600 } |
Height of the view. Full set of options include height: { minHeight: 600, /* Minimum height in pixels to the view */, height: 700, /* Explicit height in pixels - fitHeightToElement option is ignored */ fitHeightToElement: el, /* Fit view to a specific HTML element (or string query selector) in the DOM heightwise */ deltaAdjustment: 10 /* A height adjustment value in pixels */ autoSize: true /* Responsively Height will be adjusted on window resize only if you have given fitHeightToElement */, maxHeight: 800, /* Maximum height value in pixels to the view or a css variable (--view-height) */}
|
toggleFieldVisibility | Boolean | No | true |
Allow show/hide of fields |
grouping | Boolean | No | true |
Allow grouping on fields |
template | String | Yes | Table |
Determines the view of a Repeating Structure, values:['Table','Gallery','Timeline'] |
basicMode | Boolean | No | false |
Display views ['Table','Gallery','Timeline'] with full or condensed toolbar. Default shows full toolbar. |
editing | Boolean | No | false |
Allow editing on fields |
deleting | Boolean | No | false |
Allow deleting of rows |
personalization | Boolean | No | true |
Allow personalization views |
enableAppDefault | Boolean | No | false |
Enable app default personalization options |
nonPersonalizationViewName | String | No | Initial view |
Name to be shown for non personalized view |
reorderFields | Boolean | No | true |
Allow field reordering through a drag and drop action |
reorderItems (experimental) | Boolean | No | false |
Allow row reordering through a drag and drop action |
dragHandle (experimental) | Boolean | No | false |
Allow to add a column for drag handle |
globalSearch | Boolean | No | true |
Brings in a search widget to allow searching across all text type fields |
toolbar | Boolean | No | true |
Display toolbar on the view |
showCount | Boolean | No | true |
Display count in toolbar |
defaultRowHeight | String | No | undefined |
Row density id value from displayDensity options |
allowBulkActions | boolean | No | false |
Renders the 'Bulk actions' button in the table toolbar, which gets enabled on row selection |
dateFunctions | Object | No | undefined |
Enables date-functions like MONTHS/WEEKS/... during Grouping and Filtering. (Object structure) |
relativeDates | Boolean | No | false |
Enables Relative Dates, such as "Last 7 days" or "Current Year", in Filtering for DateTime or Date_Only values. |
footer | Boolean | No | true |
Display footer on the view |
dynamicFieldTemplates | Object | No | dynamicFieldTemplates: [{ name: 'Comma separated', value: 'comma',selected: true }, { name: 'Space separated', value: 'space' }, { name: 'Multi line', value: 'multiline' }, { name: 'Forward slash', value: 'forwardslash' }] |
Templates for dynamic fields. See section on Dynamic fields |
title | String | No | '<label not set>' | Repeating Structure Title |
icon | String | No | 'picture' | Repeating Structure Icon |
headerBar | Boolean | No | false | Display Header Bar |
showHeaderIcons | Boolean | No | true | Display Respective Header Icons at field labels based on type |
rowActions | Array<object> |
No | [] | list of available static actions for an editable table with following properties[{ text: 'Open in a new tab', id: 'row-new-tab', onClick: () => {} }]
|
selectionMode | String | No | [] | Decides type of row selection mode (radio for single/ checkbox for multi) possible values single / multi / multi-on-hover
|
toolbarActions | Array<Object> |
No | [] | List of available static actions at table level (shown in toolbar/ header bar) with following properties [{ text: 'Add', tooltip: 'Add story', id: 'Add', onClick: () => {}}]
|
selectionCountThreshold | Number | No | Displays select-all checkbox if selectionMode is multi-on-hover and the records count is not greater than threshold | |
disableSelectionOnLoad | Boolean | No | false | To Disable/Enable selection of rows |
requiredOnLoad | Boolean | No | false | To show asterisk(*) symbol on table header in case of Data Reference/Embedded views. (Note: This works perfectly if the personalization is off.) |
timezone | String | No | Timezone which is passed to formatter | |
locale | String | No | document.documentElement.lang | Locale which is passed to formatter function |
refreshAction | Object | No | Action to support manual Refresh from consumer of Repeating structure. Whenever Repeating structure is notified with Refresh action It will show a banner by consuming this action info. Structure : {id: 'uniqueId for banner', message: To show specific message on banner related to refresh notification, action : { text: Action button text, onClick: Function to be executed on click of action that will perform refresh of data based on consumer apiContext logic}} Example: {id: 'refreshBanner', message: 'New records have been added',action: { text: 'Click to refresh.', onClick }}
|
| displayFeatures | Object | No | displayFeatures:{filter:true, grouping:true, sort:true}
| Allow display of features-Group, Sort, Filter |
Field configuration
fieldDefs
A mandatory array of objects with the following keys
API Context
API | Arguments | Mandatory | Notes |
---|---|---|---|
stateUpdateCallback | state: updated state from the component | No | This api gets called with updated state whenever it gets modified |
setSelectedRows | selectedRows: selected rows data on the table | Yes | This api sets the selected rows data on the state |
getSelectedRows | This api gets the selected rows data from the state |
Value type | Mandatory | Notes |
---|---|---|
Object |
No | Object of formatter functions mapping where each function accepts 2 parameters, (inputValue, Options). Options is an object having properties: {locale, timezone, rowData, fieldDef, translate}
|
Render Factory
Prop key | Mandatory | Description | Return type |
---|---|---|---|
renderFactory | No | This should be a factory function which receives two arguments where second argument is optional. First argument value is the cell renderer name (if added in fieldDefs of that column). Second argument value is metadata which contains info configured for that column. It should return a component definition (or an object that contains component definition --> see Return type). This component definition will be used by RepeatingStructures to render a cell with the component provided by renderFactory. If component definition is not provided from render factory or renderFactory is not provided to Repeating structures then cell will be rendered directly with value derived for the cell or the formatted value(if formatter is provided for that column) | Repeating structures currently support 2 return types from renderFactory function
|
Presets
Value type | Mandatory | Notes |
---|---|---|
Array<Array<Object>> |
No | This property value comes from authorization |
Other Props
Property | Value type | Mandatory | Default value | Notes |
---|---|---|---|---|
toolBarOptions | Array<Array<Object>> |
No | [] |
This property extends options provided in toolbar. Object structure: { id: <string(required)>, icon: <optional>, label: <required>, show: <bool(optional)> , onClick: <Func(optional)> }
|
onViewReady | Function | No | null |
This function acts as a callback that is invoked when the view is ready |
onRowClickAction | Function | No | null |
This function is invoked when an item/entry is clicked. The corresponding item data is passed into the function on invocation |
showExportToExcelOption | Boolean | No | false |
This option is shown in the toolbar menu when the ListView is sourced from queryable DataPage |
additionalInfo | Object | No | `undefined | AdditionalInfo displayed on the toolbar is passed as is to List Toolbar component |
State
Feature | Property | Value type | Example |
---|---|---|---|
Column reorder | colOrder |
Array<string> - Array of column id |
colOrder: ["A", "custom1590925631168", "2", "3", "D", "10", "11"] |
Column resize | columnWidths |
Object - key: columnId, value: column width |
columnWidths: {10: 132.5, 11: 132.5, 12: 132.5, 2: 235.5, 3: 353} |
Column freeze | freezeColumns |
Array<string> - Array of column id |
freezeColumns: ["3", "10"] |
Column show/hide | hiddenColumns |
Array<string> - Array of column id |
hiddenColumns: ["8", "9"] |
Density | selectedHeightOption |
String - id value from displayDensity table configuration property |
selectedHeightOption: "4" |
Sort | sortingOrder |
Array<object> - [{columnId: string, order: [asc|desc] , sequence: number}] |
javascript sortingOrder: [ {columnId: "2", order: "asc", sequence: 1}, {columnId: "A", order: "desc", sequence: 2} ] |
Filter | filterExpression |
Object - output of condition builder |
Refer - Condition builder documentation |
Group | groups |
Array<object> - [{columnId: string, level: number, order: [asc|desc] }] |
groups: [ {columnId: "F", level: 0, order: "asc"}, {columnId: "D", level: 1, order: "asc"} ] |
Aggregation | aggregationInfo |
Array<object> - [{columnId: string, type: [Sum|Max|Min|Avg] }] |
aggregationInfo: [ {columnId: "D", type: "Max"}, {columnId: "11", type: "Avg"} ] |
Merge column | customFields |
Array<object> - [{id: string - should be unique, expression: array, primaryColumnId: string, label: string }] |
customFields: [ { id: 'custom4', label: 'MyCustomColumn', primaryColumnId: '2', expression: ['2', '1', ['template1'], '3', ['template2'] ] } ] |
Reference to the Component ("compRef" in below example)
APIs exposed on the component ref are accessible via compRef.current.<API_NAME>
(like compRef.current.refreshView)
API_NAME | Default values | Notes | Example |
---|---|---|---|
refreshView | refreshView api is used to re-render the already loaded table to re-fetch the data and re-fetch selections using apiContext.getSelectedRows api (if any of the selection mode is enabled). You can provide two arguments to refreshView; 1. stateToReset (<object> ) - (ex: you want to remove grouping before triggering re-render). Currently, supported state flushing of only ['filterExpression', 'search', 'selectedRows'] , 2. featuresToAvoid (Array<string> ) - to avoid re-running of the following features - ['rowAnimation', 'columnAnimation'] |
compRef.current.refreshView({ filterExpression: true, search: true }, ['rowAnimation']); |
|
moveListRecords |
apiContext.moveListRecords api is used to consume a dx api which invokes a OOTB data transform. api flow: 1. invokes dx api with necessary payload, 2. dx api is configured with activity which invokes a data transform based on the payload & path param received 3. returns success response object with {refresh: true} 4. based on this flag it triggers refresh strategy which fetch new set of data |
compRef.current.apiContext.moveListRecords({sourceID, destinationID}) |
|
dispatchAction |
dispatchAction(action,payload) is used to trigger specific actions to the table with a specific payload. Below actions are available: 'toggleDisableSelection' - it supports enable/disable of selection of rows. Payload should be a boolean in order to enable disable the selection. 'updateDebugInfo' - Show the stats of API call for debugging purposes. The payload must be an object. 'toggleRequired' - It supports show/hide of asterisk(*) sign in case of embedded/data reference tables, To show/hide of warning sign in case required condition is not met. The payload must be an object. 'notifyDataRefresh' - To show notification banner for refresh of data by consuming refreshAction from meta 'clearDataRefreshNotification' - To reset the refresh that was notified by consumer by sending 'notifyDataRefresh' action 'userConfirmationAction' - Display a generic confirmation modal with cancel and submit action. This will return a promise. 'setInExternalState' - To set something in table external state. By default the externalState will take part in personalization of table. 'updateSelectedRows' - To force re-fetch the selections using apiContext.getSelectedRows. |
Disable the selection - compRef.current.dispatchAction('toggleDisableSelection',true) Pass API stats - compRef.current.dispatchAction('updateDebugInfo', {className: "ABC", dataPage: "D_Page", dataSource: "RDBMS", timeTaken: "1.2 s", insightId: "someId"}) Show/Hide Required UX(asterisk(*) & warning sign) - cosmosTableRef.current?.dispatchAction('toggleRequired',{required, validatemessage Notify the data refresh - compRef.current.dispatchAction('notifyDataRefresh') Clear the notification of data refresh - compRef.current.dispatchAction('clearDataRefreshNotification') Show confirmation modal - compRef.current.dispatchAction(USER_CONFIRMATION_ACTION, {labels: {header, description, submitButtonLabel, cancelButtonLabel}}): Promise<any> Set in external state - compRef.current.dispatchAction('setInExternalState', {PromotedFilters: {[filterExpression payload]}}) updateSelectedRows - compRef.current.dispatchAction('updateSelectedRows')
|
|
getActiveViewInfo |
getActiveViewInfo() returns {id, name, isDirty} of current active view |
compRef.current.getActiveViewInfo() |
|
setHiddenColumns |
setHiddenColumns(columns,{ dragHandle: boolean }) sets the hiddenColumns property in component state and re-renders with features appropriately, the second parameter is an optional payload that can be used for hidding and showing the columns provided by repeating structures |
compRef.current.setHiddenColumns('pyLabel', 'pyDescription') |
|
setColumnOrder |
setColumnOrder(columns) sets the colOrder property in component state and re-renders with features appropriately |
compRef.current.setColumnOrder('pyID', 'pxCommitDateTime', ',pxUpdateDateTime', 'pyStatusWork') |
|
setFilter |
setFilter(filter) sets the filterExpression property in component state and re-renders with features appropriately. The new filter must consist of a top-level AND condition in ConditionBuilder format. |
compRef.current.setFilter({ "condition": { "comparator": "IS_TRUE", "lhs": { "field": "IsActive" } } }) |
|
setGrouping |
setGrouping(groups) sets the groups property in component state and re-renders with features appropriately |
compRef.current.setGrouping([{ "columnId": "Status", "order": "asc", "level": 0 }]) |
|
setSorting |
setSorting(groups) sets the sortingOrder property in component state and re-renders with features appropriately |
compRef.current.setSorting([{ "columnId": "Priority", "order": "asc", "sequence": 1 }]) |
Cell renderers
Dynamic field templates and renderers
**
Accessibility
Keyboard
Navigation in the toolbar component
- The Toolbar component can be traversed with the tab key.
- Popover elements such as: Filter, Sort, Group by, and Toolbar more elements can be navigated by tab key.
- On reaching the last element, pressing the tab will focus on the first element performing circular navigation.
- Similarly, if focus is on first element, then pressing SHIFT+TAB will focus the last focusable element.
- Pressing escape will close the popover and puts the focus back to the action button i.e. filter, sort, group by, and more toolbar button.
Navigation in the table
- The first focus will be on the table's first header cell if earlier no navigation has been done.
- To navigate between the cells, use the arrow keys.
- Pressing enter on the cell can turn the cell in edit mode if it is editable.
- Pressing enter again will submit the data
- Pressing escape will discard the changes and turn the cell back to read mode.
- To focus out from the table cells, press the tab key and focus will be shifted to the next focusable element on the page after table.
- Next time when navigated again to the table, the last visited cell will be focused.
Translations
- RepeatingStructures uses the cosmos, hence translations are fetched from
useConfiguration
hook exposed by cosmos-core. - Note:
Configuration
component which is a provider component of cosmos accepts thetranslations
prop, in which make sure to send the translations required for RepeatingStructure component as part of{lists: {'Sort': 'Translation of Sort'}}
Note to this repo code owners / Dev's:
- Every time a user facing / listening string is added in a component:
- Make sure to add the new translation in the pyGenericFields localisation rule under the
cosmosFields.fields.lists
category. - Then raise a PR to Cosmos translations pack defintions file to update the same key string.
- Make sure to add the new translation in the pyGenericFields localisation rule under the