JET v4.2.0 Release Notes

v4.2.0 (12 February 2018)


These release notes cover the following topics:

View the Release Notes for the prior release (v4.1.0)

IMPORTANT

With this release, the documentation URL's have changed. Please update any bookmarks you may have to the Developers Guide, JSDocs, and/or Touch/Gesture docs.

New Features included in v4.2.0

oj-chart

The chart element now supports a data provider via the data attribute.

  1. This attribute accepts an object with the following properties:
    • series
    • groups
      • A DataProvider containing ChartGroup objects.
      • Chart data items will be defined on ChartGroup objects via the items property. This property will be an array of ChartDataItem objects, and should define the data items for that specific group in the order of the chart series. When the chart is configured to display hierarchical group data, items should be declared on ChartGroup objects that are leaves.
  2. This attribute can also be defined through use of ChartDataProviderUtils.createChartData(). This method will transform data fetched from a DataProvider into the data shape required by the data attribute.

oj-menu

End icons are now supported for menu items of the oj-menu custom element. Any child element of an item's oj-option tag that specifies the endIcon slot will no longer be removed from the DOM.

Multiple icons are now supported for menu items of the oj-menu custom element. If more than one child element of an item's oj-option tag specifies the startIcon or endIcon slot, the additional child elements will no longer be removed from the DOM.

DeferredDataProvider

DeferredDataProvider is a DataProvider implementation for use cases that require a synchronously created DataProvider that is dependent on asynchronously created data. Please see the linked API doc for further details.

New UI Components

oj-validation-group

The oj-validation-group element is the InvalidComponentTracker replacement. The oj-validation-group element tracks the current validity state of its JET custom element descendents that contain the valid property. You can call the oj-validation-group's showMessages() to show any deferred messages on the tracked components and call focusOn("@firstInvalidShown") to set focus to the first invalid component showing messages.

Search Features

oj-combobox-one

Features previously provided in ojInputSearch are now included as part of oj-combobox-one. Included features are:

  • Replace the default drop down arrow with an end slot
  • Fire ojValueUpdated event on selecting an option or entering a value
  • Ability to filter the drop down list on opening the drop down with the rawValue

Features that we plan to support in a future release are:

  • custom header in the dropdown
  • virtualize the dropdown data
  • show grouped data in the dropdown

Significant JET changes since 4.1.0

This section lists significant consumer-facing changes that have been made to JET since v4.1.0. Where bugs or ERs were used to track the change, they are included below. The following list does not include changes that are internal implementations, or changes made to samples, demos, or test collateral. It is expected that application code will not need to be modified to uptake v4.2.0.


Component Changes

API Changes

oj-color-spectrum

The transient-value attribute is added to oj-color-spectrum. It is the read-only attribute for retrieving the transient value of the color spectrum. It's the replacement for the rawValue option.

oj-combobox-one

  • The oj-combobox-one element now supports an end slot as a direct child. The end slot is for replacing combobox one's drop down arrow and the divider. For example, a magnifying glass icon for a search field can be provided in this slot. When the slot is provided with empty content, nothing will be rendered in the slot. When the slot is not provided, the default drop down arrow icon and the divider will be rendered.
  • The filter-on-open attribute is added to support whether to filter the list with the current display value on opening the drop down. This is to support search use cases. This only applies to the initial opening of the drop down. When the user starts typing, the dropdown filters as usual.
  • The ojValueUpdated event is added to support search use cases. The event is triggered when the value is submitted by the user through pressing the enter key or selecting from the drop down list. The event will be fired even if the value is the same. This will help the application to re-submit the search query for the same value. The event is not triggered if the submitted value fails validation. The event is not triggered on blur or tab out.

oj-data-grid

Editing functionality has been added back for custom elements. The editMode attribute as well as the beforeEdit and beforeEditEnd events are back to the same as they were in the widget syntax and 3.2.0.

EditableValue components

The valid property

The valid property has been added to EditableValue components. It is read-only. The valid property will be in one of the following states:

  • "valid" - the component is valid
  • "pending" - the component is waiting for the validation state to be determined.
  • "invalidHidden" - the component has invalid messages hidden and no invalid messages showing. An invalid message is one with severity "error" or higher.
  • "invalidShown" - the component has invalid messages showing. An invalid message is one with severity "error" or higher.

As the component's valid state changes, the valid property will be updated and if it's a custom element (e.g., oj-input-text) a validChanged event will be sent. For widget components (e.g., ojInputText), the optionChange event is sent for the 'valid' option. You need to make sure any optionChange listeners you write will not break when we send optionChange events for new options, like the valid option. You should be checking for the specific option you are expecting to have changed (e.g., ui.option === "rawValue" if you are listening for rawValue option changes). This is a general rule for any JET component's optionChange listeners, not just a rule for EditableValue components.

The valid property is never set to "pending" in this release. It will be set in a future release.

As with all properties in JET components that have enumerated list of values, new values may be added to the valid property list in future releases. If so, we will keep the convention where if it is valid, it will start with "valid". If it is invalid, it will start with "invalid". If it is pending, it will start with "pending".

display-options

The display-options attribute determines where auxilliary content should be displayed in relation to the component, like messages can be shown inline or in a notewindow. For custom elements there is no application-wide or page-wide setting for this. You need to set display-options on each JET Form control.

Composites

To address an issue with the attached method being only called once when the composite View is first inserted into the DOM, we have deprecated the attached/detached methods for the following:

  • connected: Called once when the composite View is first inserted into the DOM and each time the composite is reconnected to the DOM after becoming disconnected.
  • disconnected: Functionally equivalent to detached and called each time the composite is disconnected from the DOM.

oj.ColorAttributeGroupHandler

We are deprecating oj.ColorAttributeGroupHandler.createAttrDiv and oj.ColorAttributeGroupHandler.processAttrDiv, which were meant to be for internal use only.

oj-diagram

The expanded attribute, which has been unavailable on the oj-diagram element since v4.0, is now exposed with a new API that utilizes the KeySet API. The expand and collapse methods available on widgets will not be exposed on the oj-diagram element. Applications can instead modify the KeySet on the expanded attribute to expand/collapse nodes.

oj-listview

scroll-position

The new scroll-position attribute allows application to get and set the current horizontal and vertical scroll position of ListView, based on either x/y coordinates, or relative to an item identified by key/index.

first-selected-item

The new read-only first-selected-item attribute allows application to get the locally available data of the first selected item in ListView.

getDataForVisibleItem

The getDataForVisibleItem method has been enhanced to allow applications to pass in key of the item as a parameter also, in addition to index.

oj-status-meter-gauge, oj-rating-gauge

Status meter gauge and Rating gauge now support a read only transient-value attribute for retrieving the transient value from these gauges during hover or drag actions.

oj-sunburst

The expanded attribute, which has been unavailable on the oj-sunburst element since v4.0, is now exposed with a new API that utilizes the KeySet API.

IteratingDataProvider, FetchByKeys, and FetchByOffset interfaces

The IteratingDataProvider, FetchByKeys, and FetchByOffset interfaces are deprecated and will be removed in the next major release. They are being replaced by a single DataProvider interface. Implementations of the old interfaces should be updated to use the DataProvider interface. Implementations of the IteratingDataProvider interface that don't need the fetchByKeys, containsKeys and/or fetchByOffset methods can use the FetchByKeysMixin and FetchByOffsetMixin classes to fill in the missing method implementations.

Theme Changes

New css class to support text-align right on custom elements

Added new css class oj-form-control-text-align-right to support text-align right for inputText and inputNumber in custom elements.

  • class = "oj-form-control-text-align-right"

Framework Changes

Component Metadata

  • Fixed an issue where Event names in native JET component metadata JSON files were missing the 'oj' prefix - for example, "beforeExpand" (incorrect) instead of "ojBeforeExpand".
  • Fixed an issue where Component names in native JET component metadata JSON files were inconsistently being specified in 'camelCase', which conflicts with the 'kebab-case' used for Composite component names - for example, "ojButton" (incorrect) instead of "oj-button" (correct).
  • Fixed an issue to ensure that sub-properties in native JET component metadata JSON files are always represented as nested JSON objects.
  • Fixed an issue whereby property alias names were not getting picked up in native JET component metadata JSON files - for example, "readOnly" property name should actually be "readonly", as this is the alias exposed in the Custom Element syntax.

Event Binding

JET now supports one-way attribute data binding for event listeners on native HTML elements, in addition to JET elements, by prefixing 'on-' to the event name and by importing the ojknockout module. The benefit compared to using the native on[eventname] attribute (without hyphen) is that the specified event listener will receive three parameters:

  • event: The DOM event.
  • data: When in an iteration context (e.g. inside an oj-bind-for-each), this parameter is equal to bindingContext['$current']; otherwise, it is equal to bindingContext['$data'].
  • bindingContext: The entire data binding context that is applied to the element.

The other benefit is that you can invoke functions that are defined in your viewmodel and thus have access to your model state. The HTML on[eventname] functions just execute at the top-level JS scope and thus only run inline JS or functions that are accessible from the window object.

Library Changes

There are no library changes in this minor release.

Tooling Changes

There are no changes to the JET tooling for this minor release.

Known Issues

The following table calls out specific known issues, with workarounds where available.

Category Bug # Description Workaround (if available)
ojListView N/A When data bound to ListView has changed, ListView will try to scroll back to the item before data changed, or to the end if the item cannot be found. To workaround this issue, clear the key of the value returned by the scrollPosition attribute after you performed the data change operation:
myListView.scrollPosition.key = null;
iOS N/A JET hybrid mobile apps created using an earlier JET release may have additional spacing at the top of the page when deployed to iOS 11 devices.
Change the viewport meta tag in index.html to the following:
<meta name="viewport" content="viewport-fit=cover, width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1.0, user-scalable=no"/>
iOS ios-sim 210 ios-sim version 5.1.0 may be installed locally by cordova-ios and serving the app to iOS simulator reports:
"Error: Cannot read property 'replace' of undefined"
cd hybrid/platforms/ios/cordova; npm install ios-sim@latest
iOS ios-deploy 275 Deployment to iOS device succeeds, but the app fails to launch and an error is reported in the terminal.
Upgrade to the latest version of ios-deploy (sudo npm install -g ios-deploy) and use a developer signing identity. Otherwise, launch the app manually on the device.
npm npm 16901 Versions of npm 5, less than 5.6 do not install the oraclejet module when scaffolding a JET hybrid app. Building the app reports:
Warning: ENOENT: no such file or directory, open 'node_modules/oraclejet/package.json' Use --force to continue
Use npm 5.6 or higher, or use the latest version of npm 4. [sudo] npm install -g npm@latest-4
Form Controls 26669973 If specifying a NumberConverter with a value attribute that is a literal value, the value will not coerce to a number. It will remain a string. E.g.,
<oj-input-text id="inp" value="5" converter="[[myNumberConverter]]">
document.getElementById("inp").value
will return "5".
Expression-bind the value instead of using a literal value. We expect this is how the vast majority of users use the form controls anyway. E.g.,
<oj-input-text id="inp" value="{{myValue}}" converter="[[myNumberConverter]]">
document.getElementById("inp").value
will return a number.
JET Custom Elements N/A In place modification of Array properties do not cause [property]Changed events to be fired. Array properties should be updated by using ko observables, updating a copy of the Array property after calling .slice(), or refreshing the component afterwards to ensure the component is notified of changes.
JET Custom Elements N/A The knockout text binding is not currently supported on JET custom elements. The knockout text binding should be used on a child span element or comment node of the JET custom element instead.
JET Custom Elements 26571960 Setting the disabled attribute on a JET custom element regardless of value, will disable the component in IE11. The disabled attribute can only be set in the inital DOM for JET custom elements. Any updates to data bound attribute will continue to notify the component of changes, but all subsequent element.setAttribute('disabled', ...) calls will be ignored. The application should use the disabled property setter insetad after the component has been initialized.
JET Custom Elements N/A Returning false from event listeners does nothing. Following the DOM event listener API, the application should call event.preventDefault() to prevent to cancel the default behavior.
JET Custom Elements JET-16992 Data binding and set/getProperty methods are only supported for component properties. We plan on supporting data binding for all element properties in a future release.
JET Custom Elements N/A In Firefox, Internet Explorer and Edge browsers, the following message may appear in the browser console: Custom Elements: `Element#attachShadow` was not patched. This message is being generated by the custom-elements polyfill and can be safely ignored. This message has been removed in version 1.0.4 of the custom-elements polyfill.
JET Custom Elements 27364188 oj-bind-for-each is not allowed as a child of table, tbody or tr tags. N/A.
ojThematicMap 26784591 Data change animations for custom element thematic map does is not currently supported. N/A.