Element: <oj-c-card-view>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
18.1.0
G25382-01

Since:
  • 17.0.0
Module:
  • card-view

QuickNav

Slots

Attributes

Events

Methods

Other Topics


JET CardView Component

Description: The JET CardView enhances a themable, WAI-ARIA compliant, mobile friendly component with advance interactive features. The child content can be configured via a DataProvider which should be used for mutable data.

For migration information from the card layout feature from oj-list-view refer to the migration section in the API docs.

Data

The JET CardView gets its data from a DataProvider.

ArrayDataProvider - Use this when the underlying data is an array object or an observableArray. In the observableArray case, CardView will automatically react when items are added or removed from the array. See the documentation for ArrayDataProvider for more details on the available options.

Example of data provider content


  <oj-c-card-view aria-label="Accessible Summary" data="[[dataProvider]]">
  </oj-c-card-view>

Check out the CardView Basic demo

Coming Features

These features will be available in forthcoming versions

  • Context menu
  • First selected item
  • Drag and drop between components
  • Managing scroll position

Keyboard End User Information

Target Key Action
Card Item F2 Enters tabbable mode. This enables keyboard action on elements inside the item, including navigate between focusable elements inside the item. It can also be used to exit tabbable mode if already in tabbable mode.
Esc Exits tabbable mode.
Tab When in tabbable mode, navigates to next focusable element within the item. If the last focusable element is reached, shift focus back to the first focusable element. When not in tabbable mode, navigates to next focusable element on page (outside CardView).
Shift+Tab When in tabbable mode, navigates to previous focusable element within the item. If the first focusable element is reached, shift focus back to the last focusable element. When not in tabbable mode, navigates to previous focusable element on page (outside CardView).
DownArrow Move focus to the item below.
UpArrow Move focus to the item above.
LeftArrow Move focus to the item on the left.
RightArrow Move focus to the item on the right.
Shift+DownArrow Extend the selection to the item below.
Shift+UpArrow Extend the selection to the item above.
Shift+LeftArrow Extend the selection to the item on the left.
Shift+RightArrow Extend the selection to the item on the right.
Space Toggles to select and deselect the current item.
Shift+Space Selects contiguous items from the last selected item to the current item.
Shift+Cmd/Ctrl+DownArrow Reorder the current item down.
Shift+Cmd/Ctrl+UpArrow Reorder the current item up.
Shift+Cmd/Ctrl+LeftArrow Reorder the current item to the left.
Shift+Cmd/Ctrl+RightArrow Reorder the current item to the right.

Accessibility

Application should specify a value for the aria-label attribute with a meaningful description of the purpose of this CardView.

Note that CardView uses the grid role and follows the Layout Grid design as outlined in the grid design pattern

Nesting collection components such as ListView, Table, TreeView, and CardView inside of CardView is not supported.

When reorder feature is enabled, application should specify a live region which contains an announcement to notify assistive technologies that the card reordering happens.

Custom Colours

Using colors, including background and text colors, is not accessible if it is the only way information is conveyed. Low vision users may not be able to see the different colors, and in high contrast mode the colors are removed. The Redwood approved way to show status is to use badge.

Item Context

For all item options, developers can specify a function as the return value. The function takes a single argument, which is an object that contains contextual information about the particular item. This gives developers the flexibility to return different value depending on the context.

The context parameter contains the following keys:

Key Description
data The data of the item. Note this is made available primarily to ease migration. Applications should get the data from the item property instead.
item An object that contains the data and metadata for the item.
isTabbable A boolean indicating whether the item is in tabbable mode or not. This should be used to implement conditional behavior for all tabbable elements, this avoids creating a keyboard trap when tabbing through the CardView.
This can be implemented as a conditional tabindex, for example tabindex="[[!item.isTabbable && '-1']]".
When composing with core pack components, this is not needed, as they are tabbable mode aware.

The following keys are not currently supported:

Key Description
componentElement A reference to the root element of CardView.
datasource A reference to the data source object.
index The index of the item, where 0 is the index of the first item. In the hierarchical case the index is relative to its parent.
key The key of the item (this duplicates item.metadata.key and has been deprecated)
metadata The metadata of the item (this is instead available in item)
parentElement This will be supported by the Hierarchical list component and no longer applies to CardView..

Custom Data Attributes

CardView supports the following custom data attributes.

Name Description Example
data-oj-as Provides an alias for a specific template instance and has the same subproperties as the $current variable. 
<oj-c-card-view id="CardView">
  <template slot="itemTemplate" data-oj-as="item">
  </template>
</oj-c-card-view>
data-oj-clickthrough

Specify on any element inside an item where you want to control whether CardView should perform actions triggered by a click event originating from the element or one of its descendants.

For example, if you specify this attribute with a value of "disabled" on a link inside an item, then CardView will not select or trigger itemAction event to be fired when user clicks on the link.

Note that the currentItem will still be updated to the item that the user clicked on.

Also note you do not need to set this attribute on core pack components such as oj-c-button, as it natively supports disabling clickthrough.

 
<oj-c-card-view id="card-view">
  <template slot="itemTemplate">
    <a href="#" data-oj-clickthrough="disabled"></a>
  </template>
</oj-c-card-view>
data-oj-manage-tabs

CardView does not manipulate the tabindex of the item content. Applications should set the tabIndex of any focusable element based on the isTabbableMode property from the context pass to the itemTemplate.

However, there will be cases where you can't control the tabindex of the content, for example, if you are using components from another team.

In that case, applications can specify this attribute on the element or one of its ancestors so that when the itemTemplate is processed, it will scan and manipulate the tabindex of any focusable elements.

 
<oj-c-card-view id="CardView">
  <template slot="itemTemplate">
    <some-component-with-focusable-elements data-oj-manage-tabs></some-component-with-focusable-elements>
  </template>
</oj-c-card-view>


Usage

Signature:

interface CCardViewElement<K extends string | number,D>

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CCardViewElement } from "oj-c/card-view";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/card-view";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

itemTemplate

The itemTemplate slot is used to specify the template for rendering each item in the CardView. The slot content must be a <template> element.

When the template is executed for each item, it will have access to the binding context containing the following properties:

  • $current - an object that contains information for the current item.
Properties of $current:
Name Type Argument Description
data D The data of the item. Note this is made available primarily to ease migration. Applications should get the data from the item property instead.
isTabbable boolean <optional>
 A boolean indicating whether the item is in tabbable mode or not. Template elements should not be tab-stops when the item is not in tabbable mode, this context can be used to implement conditional behavior for all tabbable child elements.
item Item.<K, D> Contains the data and metadata of the item.

noData

The noData slot is used to specify the content to display when the CardView is empty. The slot content must be a <template> element. If not specified then a default no data message will be displayed.

skeletonTemplate

The skeletonTemplate slot is used to specify the template for rendering each skeleton while waiting for data during initial load as well as load more on scroll. The slot content must be a <template> element. If not specified then the default skeleton will display.

When the template is executed for each skeleton, it will have access to the binding context containing the following properties:

  • $current - an object that contains information for the current skeleton.
Properties of $current:

NameTypeArgumentDescription
loadingStatus'initial' | 'loadMore' Whether the skeletons are rendered for initial load of data or for load more data in CardView
heightSizeoptionalwhen the loadingStatus is ‘loadMore’ this will be the height of the actual card size, when loadingStatus is 'initial' this vale is undefined.
widthSizeoptionalwhen the loadingStatus is ‘loadMore’ this will be the width of the actual card size, when loadingStatus is 'initial' this vale is undefined.

Example of skeletonTemplate slot usage.


<oj-c-card-view
 id="cardview"
       class="demo-card-view"
       aria-label="cardview with custom skeleton"
       data=[[dataProvider]]>
   <template slot="skeletonTemplate" data-oj-as="context">
     <div class="oj-panel oj-sm-padding-0
      :style="[[context.loadingStatus === 'initial' ? { width: '300px', height: '240px' } : { width: context.width, height: context.height } ]]">
         <oj-c-skeleton height ="100%">
         </oj-c-skeleton>
     </div>
   </template>
   <template data-oj-as="item" slot="itemTemplate">
     <div class="oj-panel">
       <demo-profile-card-layout
         name="[[item.data.name]]"
         initials="[[item.data.initials]]"
       >
       </demo-profile-card-layout>
     </div>
   </template>
</oj-c-card-view>

Attributes

columns :"auto"

Specifies the exact number of columns to render. By default, CardView will determine the number of columns based on width of the CardView and the width of the cards.
Supported Values:
Value Description
auto CardView will determine the number of columns based on width of the CardView and the width of the cards
Default Value:
  • auto
Names
Item Name
Property columns
Property change event columnsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-columns-changed

(readonly) current-item :K

The item that currently has keyboard focus
Supports writeback:
  • true
Names
Item Name
Property currentItem
Property change event currentItemChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-current-item-changed

data :(DataProvider.<K, D>|null)

The data source for CardView. Must be of type DataProvider.
Default Value:
  • null
Names
Item Name
Property data
Property change event dataChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-data-changed

focus-behavior :"content"|"card"

Specifies which focus behavior CardView should use for an item that has single focusable element during keyboard navigation. When the focusBehavior is 'card', the focus will be on the root of CardView and it will do logical focus on the card. When the focusBehavior is 'content', the first focusable element within the card will get focus. Note that when set to 'content', there should only be one focusable element within the card. If that's not the case, a warning will be logged and the focus behavior will be reset to 'card'.
Default Value:
  • "card"
Names
Item Name
Property focusBehavior
Property change event focusBehaviorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-focus-behavior-changed

gutter-size :"xs"|"sm"|"md"|"lg"|"xl"

Specifies size of the gutter between columns and rows. Possible values are: 'xs', 'sm', 'md', 'lg' and 'xl'. The default value is 'sm'.
Default Value:
  • "sm"
Names
Item Name
Property gutterSize
Property change event gutterSizeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-gutter-size-changed

initial-animation :"slideUp"|"slideDown"

Specify animation when cards are initially rendered. Possible values are: 'slideUp' and 'slideDown
Default Value:
  • "slideUp"
Names
Item Name
Property initialAnimation
Property change event initialAnimationChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-initial-animation-changed

reorderable :{ items?: 'enabled' | 'disabled' }

The reorder option contains a subset of options for reordering items.

The following options are supported:

  • items: Enable or disable reordering the items within the same CardView using drag and drop or keyboard. Specify 'enabled' to enable reordering. Setting the value to "disabled" or setting the "reorderable" property to null (or omitting it), disables reordering support.
Names
Item Name
Property reorderable
Property change event reorderableChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-reorderable-changed

reorderable.items :"disabled"|"enabled"

Default Value:
  • "disabled"
Names
Item Name
Property reorderable.items

scroll-policy-options :{ fetchSize?: number; scroller?: string }

scrollPolicy options.

The following options are supported:

  • fetchSize: The number of items fetched each time when scroll to the end.
  • scroller: The css selector that locates the element in which CardView uses to determine the scroll position as well as the maximum scroll position where scroll to the end will trigger a fetch. If not specified then the oj-c-card-view element is used.
By default, the next block of rows is fetched when the user scrolls to the end of the CardView/scroller. The fetchSize option determines how many rows are fetched in each block.

Names
Item Name
Property scrollPolicyOptions
Property change event scrollPolicyOptionsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-scroll-policy-options-changed

scroll-policy-options.fetch-size :number

Default Value:
  • 25
Names
Item Name
Property scrollPolicyOptions.fetchSize

scroll-policy-options.scroller :string

Names
Item Name
Property scrollPolicyOptions.scroller

selected :ImmutableKeySet.<K>

The current selected items in the CardView. An empty KeySet indicates nothing is selected. In addition, AllKeySetImpl set can be used to represent select all state.
Supports writeback:
  • true
Names
Item Name
Property selected
Property change event selectedChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-selected-changed

selection-mode :"multiple"|"none"|"single"|"singleRequired"

The type of selection behavior that is enabled on the CardView. This attribute controls the number of selections that can be made via selection gestures at any given time.

If single or multiple is specified, selection gestures will be enabled, and the CardView's selection styling will be applied to all items specified by the selected attribute. If singleRequired is specified, then the behavior is the same as single except that CardView will ensure there is an item selected at all times. Specifically, the user will not be able to de-selected a selected item. And if selection is initially empty, CardView will select the first item. If none is specified, selection gestures will be disabled, and the CardView's selection styling will not be applied to any items specified by the selected attribute.

Changing the value of this attribute will not affect the value of the selected attribute.

Supported Values:
Value Description
multiple Multiple items can be selected at the same time.
none Selection is disabled.
single Only a single item can be selected at a time.
singleRequired Only a single item can be selected at a time. In addition, CardView will also ensure that an item is selected at all time.
Default Value:
  • "none"
Names
Item Name
Property selectionMode
Property change event selectionModeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-selection-mode-changed

Events

ojReorder

Triggered after items are reordered within CardView via drag and drop or keyboard.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
itemKeys Array<K> An array of keys of the items that are moved
referenceKey K | null The key of the item where the moved items will be dropped after. If the moved items were dropped at the very beginning, the referenceKey will be null.
reorderedKeys Array<K> An array of keys matching the new order of items

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
Parameters:
Name Type Description
property The property name to set. Supports dot notation for subproperty access.
value The new value to set the property to.
Returns:
Type
void