[email protected]

Migrating from terra-clinical-item-collection v1 to v2

The following sections describe how to migrate from using the ItemCollection API provided in terra-clinical-item-collection v1 to the new API provided in the v2 release. The v2 release introduces new API and now allows for static and selectable Item Collection rendering. These changes allow for easier implementation, as well as more flexibility in use and future enhancements.

Behavior Changes

Added/Changed Behavior

• Allows for either static and selectable implementation
• Supports Children API which introduces the ItemCollection.Item component
• OnSelect returns the event and child key for onClicks and onKeyDowns
• Exports the following components: ItemCollection.Item, ItemCollection.Display and ItemCollection.Comment
• Table layout is no longer dependent on first collection row #213

If a display is missing, the ItemCollection will allocate space to maintain the provided layout.

Prop Changes

Props Added

• children - the Item Collection Items that will flex between either a list item or a table row.
• hasStartAccessory - indicates if space should be allocated for a start accessory.
• numberOfDisplays - the number of displays the Item Collection should allocate space for (maximum of 8).
• hasComment - indicates if space should be allocated for a comment.
• hasEndAccessory - indicates if space should be allocated for an end accessory.
• onSelect - the callback function that is assigned as to a child's onClick and onKeyDown callback if the child isSelectable. The first parameter returned is the event and the second parameter is the child key.

Props Changed

• rows - replaced with children prop.
• onChange - replaced with onSelect prop.
• listStyles - flattened and replaced with isListDivided prop. Additionally, the Item Collection no longer provides chevron styles as chevrons are intended for single-selectable lists only to indicate clicking the item will reveal more information. This behavior is not currently present in selectable tables.
• tableStyles - flattened and replaced with isTablePadded and isTableStriped.

ItemCollection.Item

This component handles the rendering of a list item or table row for the ItemCollection. By default, this would render an ListItem with an ItemView as the content. Else, it will render a TableRow with the element layout order of startAccessory, displays, comment, then endAccessory. This component provides a clean way to represent an item within the item collection, and would not handle missing element logic if used outside of the Item Collection as intended.

Usage

<ItemCollection.Item
  startAccessory={ <Accessory />}
  comment={ <ItemCollection.Comment />}
  endAccessory={ <Accessory />}
  isListItemTruncated
>
  <ItemCollection.Display />
  <ItemCollection.Display />
  <ItemCollection.Display />
</ItemCollection.Item>

Code Migration

Migrating from v1.4 to v2:

   import React from 'react';
-  import ItemView from 'terra-clinical-item-view';
   import ItemCollection from 'terra-clinical-item-collection';

  class OnChangeItemCollection extends React.Component {
    constructor(props) {
      super(props);
-     this.state = { selectedIndex: 2 };
+     this.state = { selectedItemKey: 'key-2' };
      this.handleSelection = this.handleSelection.bind(this);
    }

-    handleSelection(event, selectedIndex) {
-      this.setState({ selectedIndex });
-    }

// Selection logic is not handled by the Item Collection, it only returns the event and child key selected
+  handleSelection(event, selectedItemKey) {
+    if (event.nativeEvent.type === 'click') {
+      this.setState({ selectedItemKey });
+    }
+  }

    render() {
      return (
          <ItemCollection
            breakpoint="medium"
+           hasStartAccessory
+           numberOfDisplays={3}
+           hasComment
+           hasEndAccessory
-           onChange={this.handleSelection}
+           onSelect={this.handleSelection}
-           rows={[
-              {
-               startAccessory: <p>S</p>,
-               displays: [
-                 <ItemView.Display text="Display 1" />,
-                 <ItemView.Display text="Display 2" />,
-                 <ItemView.Display text="Display 3" />
-               ],
-               comment: <ItemView.Comment text="test comment" />,
-               endAccessory: <p>E</p>,
-               isSelected: {this.state.selectedIndex === '1'},
-              },
-              {
-               startAccessory: <p>S</p>,
-               displays: [
-                 <ItemView.Display text="Display 1" />,
-                 <ItemView.Display text="Display 2" />,
-                 <ItemView.Display text="Display 3" />
-               ],
-               comment: <ItemView.Comment text="test comment" />,
-               endAccessory: <p>E</p>,
-               isSelected: {this.state.selectedIndex === '2'},
-              },
-            ]}
-          />
+         >
+           <ItemCollection.Item
+             key="key-1"
+             isSelectable
+             isSelected={this.state.selectedItemKey === 'key-1'}
+             startAccessory={<p>S</p>}  
+             comment={<ItemCollection.Comment text="test comment" />}  
+             endAccessory={<p>S</p>}  
+           >  
+             <ItemCollection.Display text="Display 1" />
+             <ItemCollection.Display text="Display 2" />
+             <ItemCollection.Display text="Display 3" />
+           </ItemCollection.Item>
+           <ItemCollection.Item
+             key="key-2"
+             isSelectable
+             isSelected={this.state.selectedItemKey === 'key-2'}
+             startAccessory={<p>S</p>}  
+             comment={<ItemCollection.Comment text="test comment" />}  
+             endAccessory={<p>S</p>}  
+           >  
+             <ItemCollection.Display text="Display 1" />
+             <ItemCollection.Display text="Display 2" />
+             <ItemCollection.Display text="Display 3" />
+           </ItemCollection.Item>
+         </ItemCollection>
      );
    }
  }

  export default OnChangeItemCollection;

Prop Tables

terra-clinical-item-collection v1.4.0

Prop Name	Type	Is Required	Default Value	Description
breakpoint	string	optional	small	The breakpoint to switch from a table view to a list view. Breakpoint options are tiny, small, medium, large, or huge.
tableStyles	shape	optional	undefined	The styles to spread to the table. Table style options are isPadded and isStriped.
listStyles	shape	optional	undefined	The styles to spread to the list. List style options are isDivided and hasChevrons.
rows	string	optional	[]	The array of hashes to be displayed as rows. Each hash can contain a startAccessory, endAccessory, comment, array of displays, isSelected, and a itemStyles hash. The item style options are layout, textEmphasis, isTruncated and accessoryAlignment.
onChange	func	optional	undefined	A callback event that will be triggered when selection state changes.

terra-clinical-item-collection v2.0.0

ItemCollection Props

Prop Name	Type	Is Required	Default Value	Description
breakpoint	string	optional	small	The breakpoint to switch from a table view to a list view. Breakpoint options are tiny, small, medium, large, or huge.
isTablePadded	bool	optional	false	Whether or not the table cells should be padded.
isTableStriped	bool	optional	false	Whether or not the table rows should be zebra striped.
isListDivided	bool	optional	false	Whether or not the list items should be divided.
children	string	optional	[]	The Item Collection Items that will flex between either a list item or a table row.
hasStartAccessory	bool	optional	false	Whether or not the item collection should create a layout to display a start accessory.
numberOfDisplays	number	optional	0	The number of displays the item collection should create a layout for.
hasComment	bool	optional	false	Whether or not the item collection should create a layout to display a comment.
hasEndAccessory	bool	optional	false	Whether or not the item collection should create a layout to display an end accessory.
onSelect	func	optional	undefined	The callback function that is assigned as to a child's onClick and onKeyDown callback if the child isSelectable. The first parameter returned is the event and the second parameter is the child key. Function is not applied if child is not selectable.

ItemCollection.Item Props

Prop Name	Type	Is Required	Default Value	Description
children	node	optional	undefined	The display elements to be presented.
startAccessory	node	optional	undefined	The start accessory element to be presented.
comment	node	optional	undefined	The comment element to be presented.
endAccessory	node	optional	undefined	The end accessory element to be presented.
listItemLayout	string	optional	'oneColumn'	When displayed as a list item, the column layout in which to present the displays.
listItemTextEmphasis	string	optional	'default'	When displayed as a list item, the text color emphasis when using the two columns layout.
isListItemTruncated	bool	optional	false	When displayed as a list item, whether or not all text should truncate.
accessoryAlignment	string	optional	'alignCenter'	The vertical alignment of the start and end accessories.
isSelectable	bool	optional	false	Wether or not the item is selectable. If true, the item is given list and table hover and focus styles, tabIndex set to 0, and onClick and onKeyDown callbacks set to the onSelect function provided via Item Collection.
isSelected	bool	optional	false	Wether or not the item is selected.
view	string	optional	'list'	The view in which the item should be presented. Options are list or table and this will be set by the Item Collection component.