Item List
Definition and Usage
The Item List component is a widget that lets you display a list of items from a data set either as a flat list or as a structure tree. Item List allows end users to perform actions on the entire list or specific list items. When data is in a flat list, Item List also allows end users to search, sort, and filter the list.
 |
In previous versions of ThingWorx Navigate, the Item List component was a contained mashup. Now Item List is available as a widget, and the Item List mashup is deprecated.
|
The following are two sample images showing the Item List component:
You can configure the Item List component in the following ways:
• Enable or disable searching and filtering (for flat lists only)
• Set the initial filtering and sorting options (for flat lists only)
• Set the maximum number of rows in the grid
• Define whether items can be selected from the list, and if so whether one or multiple items can be selected
• Set the initial expansion level (for structure tree only)
• Choose whether to show the Export action and allow users to select the exported file format
• Choose whether to export all data or only data that matches filter criteria
• Configure the actions available in the embedded Action Bar
The user can filter or search the Item List using the filter box or the search box. However, if the filter box and the search box are not enabled in the configuration, then filtering and searching are not available. You can click a column title to sort the list by that column. To reverse the sort order, click the column title again.
The Item List component contains an embedded Action Bar component. By configuring the Action Bar, you can enable additional capabilities, such as executing an action on one or more list items. See the Action Bar (BETA) for more information. By default, the Item List contains an Export action, which exports items to a CSV file.
The Item List also includes a Restore defaults button. The Restore defaults button restores the default settings for filtering, searching, and grid level operations including sorting, swapping, and showing and hiding columns.
Activity, Affected Items, Attachments, Drawings, Part Structure, and Tasks are the predefined configurations available for the Item List component.
Flat List Versus Structure Tree
As mentioned earlier, Item List supports both flat lists and structure trees. Whether the Item List appears as a flat list or a structure tree in the user interface depends on how the input to the GetItems service is formatted. For more information, see the GetItems service below.
When Item List is a structure tree, search, sort, and filter are not supported, even if you configure them using the configuration properties below.
When Item List is a flat list, default expansion level is not relevant.
Binding Properties
Input | ||||
|---|---|---|---|---|
Property Name | Description | Property Type | ||
input | Used for identifying the data to be fetched from the backend system. When input is required, set the waitForInput configuration property to true. Sample JSON: { "version":"1.0.0", "data":[ { "adapter":{ "instanceName":"windchill", "thingName":"PTC.WCAdapter" }, "itemListsData":[ { "items":[ { "id":{ "value":"OR:wt.workflow.work.WorkItem:1432583" } } ], "objectType":"PTC.Workflow.WorkItem" } ] } ] } | JSON in CCO format | ||
selectedItems | Used to identify and select grid items and their attributes as input. You can bind the output binding property of other components to this property. Sample JSON: { "data":[ { "itemListsData":[ { "items":[ { "workItem":{ "value":"OR:wt.workflow.work.WorkItem:143921" } }, { "workItem":{ "value":"OR:wt.workflow.work.WorkItem:143928" } } ], "objectType":"PTC.Workflow.WorkItem" } ], "adapter":{ "instanceName":"windchill", "thingName":"PTC.WCAdapter" } } ], "version":"1.0.0", "statusMessage":"OK", "status":"200" }
| JSON in CCO format | ||
tailoringName | Uniquely identifies an instance of the Item List component. This value is used internally for looking up tailoring information for that specific instance. Only use this binding property when there is a dedicated tailoring page for your custom task. | |||
Output | ||||
|---|---|---|---|---|
Property Name | Description | Property Type | ||
totalItemsNumber | Number of list items that match search and filter criteria.
| Integer | ||
selectedItems | Used for identifying the selected grid items and their attributes. This property can be bound to the input binding property of other components. Sample JSON: { "data":[ { "itemListsData":[ { "items":[ { "workItem":{ "value":"OR:wt.workflow.work.WorkItem:143921" } }, { "workItem":{ "value":"OR:wt.workflow.work.WorkItem:143928" } } ], "objectType":"PTC.Workflow.WorkItem" } ], "adapter":{ "instanceName":"windchill", "thingName":"PTC.WCAdapter" } } ], "version":"1.0.0", "statusMessage":"OK", "status":"200" } | JSON in CCO format | ||
Configuration Properties
The following table and images show the JSON fields used to configure this component.
For more information on the structure of the configuration, see Component Configuration Structure.
For more information on sub-properties, see Sub-Properties and Container Keys.
Property Name | Description | Property Type | Default Value | Required or Optional | |||
|---|---|---|---|---|---|---|---|
actionBarConfiguration | Configuration of the embedded Action Bar. See the Action Bar (BETA) for more information. | N/A | Optional | ||||
attributes | Attributes to display. These appear as column titles in the grid. For information on including an action in an attribute column, see the note below this table. | N/A | Required | ||||
defaultExpansionLevel | Defines the initial expansion level of structure tree. Accepts numbers 1–9 and -1 as input. When the property is set to -1, the structure tree is initially fully expanded, showing all levels.
| 3 | Optional | ||||
defaultSelectedFilterValue | The initial selected value or values to filter by. When blank, there is no default filtering. This property is a sub-property to filterFields and is only relevant when filterFields is included in the configuration. Its container key is itemListFilterFieldDefinition.
| N/A | Optional | ||||
defaultSortDirection | The direction of the default sorting. Options: asc, which indicates ascending order, and dsc, which indicates descending order. When blank, sort direction is ascending. This property is a sub-property to defaultSortField and is only relevant when defaultSortField is included in the configuration. Its container key is itemListDefaultSortFieldDefinition.
| asc | Optional | ||||
defaultSortField | The initial column to sort by. When blank, Item List is sorted by the first column.
| N/A | Optional | ||||
enableSearch | Whether to present the search field. Options: true, false.
| true | Optional | ||||
exportUnFilteredData | Whether to include all data or only filtered data when exporting the Item list data to a file. Options: true, false. When set to true, the exported file includes the data regardless of filtering. When set to false, the exported file contains only the filtered data. Data that is not visible in the Item List grid due to the maxNumberOfRowsInGrid property limit is still included in the exported file. This property is a sub-property to showExportAction and is only relevant when showExportAction is included in the configuration. Its container key is itemListExportDefinition. | false | Optional | ||||
exportTypes | The types of export available. Options: exportToCsv, exportToExcel.You can include one or both options. When exportToCsv is included, the Export button includes the option to export data to a CSV file in the standard format. When exportToExcel is included, the Export button includes the option to export data that is formatted for Excel to a CSV file. When only one option is included, the Export button automatically exports the data in the selected format (standard CSV or CSV in Excel format). When both options are included, the Export button appears as a menu button, allowing the user to select the desired export format. This property is a sub-property to showExportAction and is only relevant when showExportAction is included in the configuration. Its container key is itemListExportDefinition. | exportToCsv, exportToExcel | Optional | ||||
filterFields | The IDs in the backend system of the fields by which to filter the data. When blank, there is no option to filter the data.
| N/A | Optional | ||||
filterLabelOverride | A label for the filter which overrides the display value returned from the GetItems service. This property is a sub-property to filterFields and is only relevant when filterFields is included in the configuration. Its container key is itemListFilterFieldDefinition | N/A | Optional | ||||
implementationConfigurations | Entry point for the application builder to pass in additional values needed for their implementation, to further customize the component. | N/A | Optional | ||||
label | The title of the Item List. | [[PTC.ItemList]] | Optional | ||||
maxNumberOfRowsInGrid | Maximum number of rows to display in the grid area. It’s recommended to input a value less than 10,000.
| 500 | Optional | ||||
searchHintText | The hint text shown in the search box. This property is a sub-property to enableSearch and is only relevant when enableSearch is set to true. Its container key is itemListSearchDefinition. | Find Item | Optional | ||||
selectionType | Determines how many items in the grid can be selected at one time. Options: • none– grid items cannot be selected • single– one grid item can be selected at a time • multi– one or more grid items can be selected at a time | multi | Optional | ||||
showExportAction | Enables or disables the Export action. Options: true, false. | true | Optional | ||||
waitForInput | Whether to wait at runtime for a value to be passed to the Item List's input mashup parameter before triggering the retrieval of the items that populate the grid. Options: true, false. | false | Optional | ||||
| | When including an attribute with HTML values that displays a menu button in an attribute column, the action must be under the PTCNav key. The only action type that is currently supported is OpenUrl. Example: { "label":"", "icon":"", "PTCNav":{ "Action":{ "type":"openUrl", "data":{ "url":"http://www.linkTofile.pdf" } } } } |
Sample Configuration
For sample configurations for the Item List component, see Activity, Affected Items, Attachments, Drawings, Part Structure, and Tasks.
Customization Services
In addition to configuration, each component supports extending its business logic to customize the component. The business logic of each component includes overridable services in a Thing Template that you can extend and override. The overridable services for this component are detailed in the following table.
For examples of returns and parameters for each service, see Examples of Input/Output for Customization Services.
| | When returning a JSON object in CCO format from a Business Logic Implementation component to the Item List component, only include attributes of a single object type. Currently, the Item List doesn’t support including attributes of different object types. |
Name | Description |
|---|---|
ComputeMessages | Computes the desired messages to show above the item list grid in the user interface. It receives the current messages JSON and the suggested messages JSON, and it returns a notification messages JSON that contains the messages to display in the item list. Parameters: getItemsResponse (Required)– JSON object in CCO format that contains the items returned from getItems service. currentMessages (Required)– JSON object that contains current notification messages that are displayed in the user interface. suggestedMessages (Required)– JSON object that contains a set of suggested messages. It’s recommended to use the suggested messages. input (Optional)– JSON in CCO format that includes the input ID for the item at the root of the structure. configuration (Optional)– JSON with the configuration. scope (Optional)– JSON that indicates the scope of the data in getItemsResponse. The JSON object contains a scope key that accepts the values root and child. Relevant for hierarchical data. Example: { "scope": "root" } Returns: JSON object containing messages to display in item list grid. Example: "INFO":{ { "messages":[ "[[PTC.Nav.ItemList.HiddenItemsBecauseAccessRightMessage]]" ] } } |
DefHookImplementationConfigurationDefinitionGroup | Returns the implementation-specific definition with the custom configurations for the implementation. Parameters: None Returns: JSON:Array |
DefHookImplementationAttributesDefinition | Returns the implementation-specific definition for the selected attributes. Parameters: None Returns: JSON:Array |
DefHookMaxRowsProperties | Returns the properties for the maximum number of rows to display in the grid area. Parameters: None Returns: JSON |
GetChildren | Receives an item and returns a JSON in CCO format containing that item’s children, meaning all items that are one level below that item in the hierarchical data structure. The returned JSON contains the children as a flat list, not hierarchical data. This service is called whenever a user expands an item on the item list whose children are not loaded. The default implementation of this service assumes that the service MapItemToInputObject is implemented for item to input conversion, if it is required. Parameters: input (Optional)– JSON in CCO format that includes the input ID for the item at the root of the structure. configuration (Required)– JSON with the configuration. item (Required)– JSON that includes the item whose children to return. Returns: JSON in CCO format |
GetConfigurations | Returns the available configurations for the component implementation. Parameters: None Returns: JSON |
GetImplementationLabel | Returns either the localized name of the component or the token that can be used to obtain the localized name. This localized name is displayed in the Mashup Builder user interface. Parameters: None Returns: String |
GetImplementationSettings | Returns the implementation's settings data. Implementations can override this service in order to provide their own settings. For more information, see the topic Enable the selectedItems Input Binding Property for Item List. Parameters: None Returns: JSON object |
GetItems | Returns the list of items from the backend system. To create a custom implementation of Item List, override this service to retrieve the custom data. Parameters: input (Optional)– JSON in CCO format that includes the input ID for the data to be fetched from the backend system and the adapter information for the backend system. When using this parameter, make sure that the waitForInput configuration property is set to true. configuration (Optional)– JSON with the configuration. Returns: JSON in CCO format |
GetItemsByExpansionPath | Returns a hierarchical structure CCO that contains all items on the path from the root to the requested item, including all the requested attributes, itemIdentifierKeys, anditemExpansionKeys, as defined in the GetImplementationSettings service. The hierarchical structure CCO includes all siblings on the path. The service is called when the selectedItems binding property receives input specifying an item that is not loaded. Parameters: input (Optional)– JSON in CCO format that includes the input ID for the item at the root of the structure. configuration (Required)– JSON with the configuration. itemExpansionValues (Required)– A JSON array that holds itemExpansionKeys of the item for which the expansion is requested. The array values are ordered according to the path in the tree, starting with the root item. Returns: JSON in CCO format |
GetItemsForExport | Processes the configuration JSON and input JSON in CCO format, and returns a JSON in CCO format containing all items that are required for export. By default this service returns an empty CCO, but implementations can override the service to return their items for export. In that case, the data for export are the items returned by this service. The result of this service is used when the selectedItems binding property receives input specifying an item that is not loaded. Parameters: input (Optional)– JSON in CCO format that includes the input ID for the data to be fetched from the backend system. configuration (Optional)– JSON with the configuration. Returns: JSON in CCO format |
GetStructureSkeleton | Returns all levels of a hierarchical structure in CCO format, where each item in the structure includes both itemIdentifierKeys and itemExpansionKeys, as defined in the GetImplementationSettings service. Parameters: input (Optional)– JSON in CCO format that includes the input ID for the item at the root of the structure. configuration (Optional)– JSON with the configuration. Returns: JSON in CCO format |
InitializeFilters | Returns the filter type definition for each of the filter fields in the configuration. Parameters: input (Optional)– JSON in CCO format that includes the input ID for the data to be fetched from the backend system and the adapter information for the backend system. configuration (Optional)– JSON with the configuration. Returns: JSON in CCO format |
MapItemToInputObject | Maps an item to an input, which can then be used by the GetItems service. The default implementation returns the item without any changes. If any changes are necessary, for example, changing the object type for the item, override this service. This service is used only by the default implementation of the GetChildren service. Parameters: input (Optional)– JSON in CCO format that includes the input ID for the item at the root of the structure. item (Required)– JSON that includes the item to map to an input. |
PrepareDataForExport | Receives data in the form of an infotable and prepares it for export. The default implementation returns the data as is, but implementations can override this service in order to modify the data as needed. Parameters: configuration (Required)–JSON with the configuration. dataInfoTable (Required)– Infotable that includes the data for export. data (Optional)– JSON object in CCO format that includes the data for export. gridQuery (Optional)– JSON object that represents QUERY type data, which contains a query filter from the item list grid. searchTerm (Optional)– A string to search for in each row of the grid. filterOptions (Optional)– An infotable containing options by which to filter. Returns: Infotable |
Implementation Definition
For implementation definitions for the Item List component, see Activity, Affected Items, Attachments, Drawings, Part Structure, and Tasks.