Namespace: OffcanvasUtils

Oracle® JavaScript Extension Toolkit (JET)
7.1.0

F18183-01

QuickNav


PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

OffcanvasUtils

Version:
  • 7.1.0
Since:
  • 1.1.0
Module:
  • ojoffcanvas

Module usage

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

Javascript Import Format
define(['ojs/ojoffcanvas'], function(OffcanvasUtils) {
 // Application should call API on OffcanvasUtils 
})
Typescript Import Format
//This namespace exports multiple static methods or members. To import 
import * as OffcanvasUtils from "ojoffcanvas";

//Now you can access the methods as OffcanvasUtils.methodName and so on

JET In Typescript

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

Description

This class provides functions used for controlling offcanvas regions. Offcanvas regions can be used in either static (simply displaying and hiding in response to user interactions) or responsive (using media queries to dynamically move application content between the main viewport and offcanvas regions) contexts. The OffcanvasUtils methods can be used to directly control the display of an offcanvas region in both the static and responsive cases.

Note for performance reasons, if the Offcanvas content is expensive to render, you should wrap it in an oj-defer element (API doc oj.ojDefer) to defer the rendering of that content.
See the Offcanvas - Deferred Rendering demo for an example.

Events

Event Description Example
beforeClose Triggered immediately before the offcanvas is closed. It can be canceled to prevent the content from closing by returning a false in the event listener. $(".selector").on("ojbeforeclose", function(event, offcanvas) {});
beforeOpen
Triggered immediately before the offcanvas is open. It can be canceled to prevent the content from opening by returning a false in the event listener. $(".selector").on("ojbeforeopen", function(event, offcanvas) {});
close
Triggered after the offcanvas has been closed. $(".selector").on("ojclose", function(event, offcanvas) {});
open
Triggered after the offcanvas has been open (after animation completes). $(".selector").on("ojopen", function(event, offcanvas) {});

Styling

The following CSS classes can be applied by the page author as needed.

Class Description
oj-offcanvas-outer-wrapper Applied to the outer most element of the offcanvas.
oj-offcanvas-page Applied to the outer wrapper of the page level offcanvas.
oj-offcanvas-inner-wrapper Deprecated. Please remove the inner wrapper.
oj-offcanvas-start Applied to the offcanvas on the start edge.
oj-offcanvas-end Applied to the offcanvas on the end edge.
oj-offcanvas-top Applied to the offcanvas on the top edge.
oj-offcanvas-bottom Applied to the offcanvas on the bottom edge.
oj-offcanvas-overlay-shadow Add this marker class to an overlay offcanvas to show a drop shadow when it is open.

Touch End User Information

Target Gesture Action
Offcanvas Swipe Close the offcanvas by swiping in the close direction.

Keyboard End User Information

Target Gesture Action
Close button Enter If offcanvas has a close button, navigate to the button and press Enter to close the offcanvas.
Outer wrapper Tab or Shift+Tab When focus is on the outer wrapper, Tab or shift+Tab moves the focus to the next or previous tab stop on the page. If autoDismiss is true, it also closes the offcanvas.

Methods

(static) close(offcanvas) → {Promise.<boolean>}

Hides the offcanvas by sliding it out of the viewport. This method fires an ojbeforeclose event which can be vetoed by attaching a listener and returning false. If the close is not vetoed, this method will fire an ojclose event once animation has completed.
Parameters:
Name Type Description
offcanvas Object An Object contains the properties in the following table.
Properties:
Name Type Description
offcanvas.selector string JQ selector identifying the offcanvas
See:
Returns:
A promise that is resolved to boolean true when all transitions have completed. The promise is rejected if the ojbeforeclose event is vetoed.
Type
Promise.<boolean>

(static) open(offcanvas) → {Promise.<boolean>}

Shows the offcanvas by sliding it into the viewport. This method fire an ojbeforeopen event which can be vetoed by attaching a listener and returning false. If the open is not vetoed, this method will fire an ojopen event once animation has completed.

Upon opening a offcanvas, focus is automatically moved to the first item that matches the following:

  1. The first element within the offcanvas with the autofocus attribute
  2. The first :tabbable element inside the offcanvas
  3. The offcanvas itself
Parameters:
Name Type Description
offcanvas Object An Object contains the properties in the following table.
Properties:
Name Type Argument Description
offcanvas.selector string JQ selector identifying the offcanvas.
offcanvas.content string JQ selector identifying the main content.
offcanvas.edge 'start' | 'end' | 'top' | 'bottom' <optional>
the edge of the offcanvas, valid values are start, end, top, bottom. This property is optional if the offcanvas element has a "oj-offcanvas-" + class specified.
offcanvas.displayMode 'push' | 'overlay' <optional>
how to show the offcanvas, valid values are push or overlay. Default: defined by theme.
offcanvas.autoDismiss 'focusLoss' | 'none' <optional>
close behavior, valid values are focusLoss and none. If autoDismiss is default(focusLoss) then any click outside the offcanvas will close it.
offcanvas.size string <optional>
size width or height of the offcanvas: width if edge is start or end and height if edge is to and bottom. Default to the computed width or height of the offcanvas.
offcanvas.modality 'modal' | 'modeless' <optional>
The modality of the offcanvas. Valid values are modal and modeless. Default: modeless. If the offcanvas is modal, interaction with the main content area is disabled like in a modal dialog.
See:
Returns:
A promise that is resolved to boolean true when all transitions have completed. The promise is rejected if the ojbeforeopen event is vetoed.
Type
Promise.<boolean>

(static) setupPanToReveal(offcanvas) → {void}

Setup offcanvas for pan to reveal. This method adds a touch listener to handle revealing the offcanvas as user pans on the outer wrapper. The following events are fired by this method: ojpanstart - fired when pan to reveal gesture initiated by the user. The event includes the direction and distance of the pan. If it is vetoed then pan to reveal is terminated ojpanmove - fired as user continues the pan gesture. The event includes the direction and distance of the pan. ojpanend - fired when pan to reveal gesture ends. The event includes the direction and distance of the pan. If it is vetoed then the offcanvas will be closed.
Parameters:
Name Type Description
offcanvas Object An Object contains the properties in the following table.
Properties:
Name Type Argument Description
offcanvas.selector string JQ selector identifying the offcanvas
offcanvas.edge 'start' | 'end' | 'top' | 'bottom' <optional>
the edge of the offcanvas, valid values are start, end. This property is optional if the offcanvas element has a "oj-offcanvas-" + class specified.
offcanvas.size string <optional>
size width of the offcanvas. Default to the computed width of the offcanvas.
See:
Returns:
Type
void

(static) setupResponsive(offcanvas) → {void}

Setup offcanvas for the responsive layout. This method adds a listener based on the media query specified in offcanvas.query. When the media query matches the listener is called and offcanvas behavior is removed. When the media query does not match the listener is called and off canvas behavior is added.
Parameters:
Name Type Description
offcanvas Object An Object contains the properties in the following table.
Properties:
Name Type Argument Description
offcanvas.selector string JQ selector identifying the offcanvas
offcanvas.edge 'start' | 'end' | 'top' | 'bottom' <optional>
the edge of the offcanvas, valid values are start, end, top, bottom. This property is optional if the offcanvas element has a "oj-offcanvas-" + class specified.
offcanvas.query string | null the media query determine when the offcanvas is fixed inside the viewport.
See:
Returns:
Type
void

(static) tearDownPanToReveal(offcanvas) → {void}

Removes the listener that was added in setupPanToReveal. Page authors should call tearDownPanToReveal when the offcanvas is no longer needed.
Parameters:
Name Type Description
offcanvas Object An Object contains the properties in the following table.
Properties:
Name Type Description
offcanvas.selector string JQ selector identifying the offcanvas
See:
Returns:
Type
void

(static) tearDownResponsive(offcanvas) → {void}

Removes the listener that was added in setupResponsive. Page authors should call tearDownResponsive when the offcanvas is no longer needed.
Parameters:
Name Type Description
offcanvas Object An Object contains the properties in the following table.
Properties:
Name Type Description
offcanvas.selector string JQ selector identifying the offcanvas
See:
Returns:
Type
void

(static) toggle(offcanvas) → {Promise.<boolean>}

Toggles the offcanvas in or out of the viewport. This method simply delegates to the open or close methods as appropriate.
Parameters:
Name Type Description
offcanvas Object An Object contains the properties in the following table.
Properties:
Name Type Argument Description
offcanvas.selector string JQ selector identifying the offcanvas.
offcanvas.content string JQ selector identifying the main content.
offcanvas.edge 'start' | 'end' | 'top' | 'bottom' <optional>
the edge of the offcanvas, valid values are start, end, top, bottom. This property is optional if the offcanvas element has a "oj-offcanvas-" + class specified.
offcanvas.displayMode 'push' | 'overlay' <optional>
how to show the offcanvas, valid values are push or overlay. Default: defined by theme.
offcanvas.autoDismiss 'focusLoss' | 'none' <optional>
close behavior, valid values are focusLoss and none. If autoDismiss is default(focusLoss) then any click outside the offcanvas will close it.
offcanvas.size string <optional>
size width or height of the offcanvas: width if edge is start or end and height if edge is to and bottom. Default to the computed width or height of the offcanvas.
offcanvas.modality 'modal' | 'modeless' <optional>
The modality of the offcanvas. Valid values are modal and modeless. Default: modeless. If the offcanvas is modal, interaction with the main content area is disabled like in a modal dialog.
See:
Returns:
A promise that is resolved to boolean true when all transitions have completed
Type
Promise.<boolean>