Element: <oj-waterfall-layout>

Oracle® JavaScript Extension Toolkit (JET)
9.1.0
F30737-01

Signature:

class ojWaterfallLayout<K extends (string | number), D>

Note: This component is not supported in the following themes: Alta

QuickNav

Slots

Attributes

Methods

Type Definitions

JET Custom Elements

JET components are implemented as custom HTML elements. In addition to the component attributes documented in this page, JET components also support standard HTML global attributes like id and aria-label.

The JET data binding syntax can be used to define both component and global attributes through the use of dynamically evaluated expressions. All attributes (component and global) support attribute-level binding by prefixing the attribute name with ":" (e.g. :id="[...]"). When using attribute-level binding, all expression values are treated as strings. Additionally, component attributes support property-level binding by using the attribute name directly with no ":" prefix. When using property-level binding, the expressions should evaluate to the types documented by the corresponding attributes. Property-level binding is strongly recommended over attribute-level binding for component attributes.

A detailed description of working with custom HTML elements can be found in: JET Custom Element Usage.


Version:
  • 9.1.0
Since:
  • 9.0.0
Module:
  • ojwaterfalllayout

Module usage

See JET Module Loading for an overview of module usage within JET.

Typescript Import Format
//To typecheck the element APIs, import as below.
import {WaterfallLayoutElement} from "ojs/ojwaterfalllayout";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojwaterfalllayout";
Generic Parameters
ParameterDescription
KType of key of the dataprovider
DType of data from the dataprovider

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.


JET WaterfallLayout

Description: The JET WaterfallLayout displays data as cards in a grid layout based on columns. Cards inside WaterfallLayout usually don't have a fixed height but the width of each columns are the same.

//WaterfallLayout with a DataProvider
<oj-waterfall-layout data="[[dataProvider]]">
</oj-waterfall-layout>

DataProvider

WaterfallLayout can work with any non-hierarchical DataProvider as long as the data type for its key is of type string or number.

An error will be logged and no data will be rendered if the data type for key is not one of the above types. This requirement enables WaterfallLayout to optimize rendering in all scenarios.

Accessibility

Touch End User Information

Target Gesture Action
Card Tap Focus on the item.

Keyboard End User Information

Target Key Action
Card LeftArrow Move focus to the previous item according to the data order.
RightArrow Move focus to the next item according to the data order.
F2 Enters Actionable mode. This enables keyboard action on elements inside the item, including navigate between focusable elements inside the item.
Esc Exits Actionable mode.
Tab When in Actionable 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 Actionable Mode, navigates to next focusable element on the page (outside of the component).
Shift+Tab When in Actionable 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 Actionable Mode, navigates to previous focusable element on the page (outside of the component).

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 WaterfallLayout. The slot content must be a <template> element.

The content inside the template must have a single Element as the root node. It cannot have multiple root nodes, incluidng Text and Comment nodes. The root node also cannot be a JET Binding Element, you must wrap it with an Element node. If the content do contain multiple nodes, WaterfallLayout will take the first Element node it encountered and ignore the rest.

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

Properties of $current:
Name Type Description
data Object The data for the current item being rendered
index number The zero-based index of the current item
key any The key of the current item being rendered

Attributes

data :DataProvider.<K, D>

The data for WaterfallLayout. Must be of type DataProvider. Please refer to the DataProvider section for key data type requirement.
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

scroll-policy :loadAll|loadMoreOnScroll

Specifies the mechanism used to scroll the data inside the WaterfallLayout. Possible values are: "loadMoreOnScroll", and "loadAll". When "loadMoreOnScroll" is specified, additional data is fetched when the user scrolls to the bottom of the WaterfallLayout. Note that the component must have a height specified or inside a height constraint element so that the component element is scrollable. When "loadAll" is specified, WaterfallLayout will fetch all the data when it is initially rendered.
Supported Values:
Value Description
loadAll Fetch and render all data.
loadMoreOnScroll Additional data is fetched when the user scrolls towards the bottom of the grid.
Default Value:
  • "loadMoreOnScroll"
Names
Item Name
Property scrollPolicy
Property change event scrollPolicyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-scroll-policy-changed

scroll-policy-options :Object.<string, any>|null

scrollPolicy options.

The following options are supported:

  • fetchSize: The number of items fetched each time when scroll to the end.
  • maxCount: Maximum rows which will be displayed before fetching more rows will be stopped.
  • scroller: The element which WaterfallLayout 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-waterfall-layout element is used.
When scrollPolicy is loadMoreOnScroll, the next block of rows is fetched when the user scrolls to the end of the component. 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

(nullable) scroll-policy-options.fetch-size :number

The number of items to fetch in each block.
Default Value:
  • 25
Names
Item Name
Property scrollPolicyOptions.fetchSize

(nullable) scroll-policy-options.max-count :number

The maximum total number of items to fetch.
Default Value:
  • 500
Names
Item Name
Property scrollPolicyOptions.maxCount

(nullable) scroll-policy-options.scroller :Element

The element which WaterfallLayout uses to determine the scroll position as well as the maximum scroll position.
Default Value:
  • null
Names
Item Name
Property scrollPolicyOptions.scroller

scroll-position :Object.<string, any>

The current scroll position of WaterfallLayout. The scroll position is updated when the vertical scroll position (or its scroller, as specified in scrollPolicyOptions.scroller) has changed. The value contains the y scroll position, the key of the item closest to the top of the viewport, as well as vertical offset from the position of the item to the actual scroll position.

The default value contains just the scroll position. Once data is fetched the 'key' and 'offsetY' sub-properties will be added. If there is no data then the 'key' sub-properties will not be available.

When setting the scrollPosition property, applications can change any combination of the sub-properties. If both key and y sub-properties are set at once then key will take precedent. If offsetY is specified, it will be used to adjust the scroll position from the position where the key of the item is located.

If a sparse object is set the other sub-properties will be populated and updated once WaterfallLayout has scrolled to that position.

Also, if scrollPolicy is set to 'loadMoreOnScroll' and the scrollPosition is set to a value outside of the currently rendered region, then the value of scrollPosition will be ignored.

Lastly, when a re-rendered is triggered by a refresh event from the DataProvider, or if the value for data attribute has changed, then the scrollPosition will by default remain at the top.

Properties:
Name Type Argument Description
y number <optional>
 The vertical position in pixels.
key K <optional>
 The key of the item. If DataProvider is used for data and the key does not exists in the DataProvider or if the item has not been fetched yet, then the value is ignored.
offsetY number <optional>
 The vertical offset in pixels relative to the item identified by key.
Default Value:
  • {"y": 0}
Supports writeback:
  • true
Names
Item Name
Property scrollPosition
Property change event scrollPositionChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-scroll-position-changed

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty. The return type will be the same as the type of the property as specified in this API document. If the method is invoked with an incorrect property/subproperty name, it returns undefined.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Since:
  • 4.0.0
Returns:
Type
any
Example

Get a single subproperty of a complex property:

let subpropValue = myComponent.getProperty('complexProperty.subProperty1.subProperty2');

setProperties(properties) : {void}

Performs a batch set of properties. The type of value for each property being set must match the type of the property as specified in this API document.
Parameters:
Name Type Description
properties Object An object containing the property and value pairs to set.
Since:
  • 4.0.0
Returns:
Type
void
Example

Set a batch of properties:

myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});

setProperty(property, value) : {void}

Sets a property or a subproperty (of a complex property) and notifies the component of the change, triggering a [property]Changed event. The value should be of the same type as the type of the attribute mentioned in this API document.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Since:
  • 4.0.0
Returns:
Type
void
Example

Set a single subproperty of a complex property:

myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");

Type Definitions

ItemTemplateContext

Properties:
Name Type Description
data Object The data for the current item being rendered
index number The zero-based index of the current item
key any The key of the current item being rendered