JET v8.1.0 Release Notes

17 February 2020

To view Release Notes from a prior release of JET, select the specific below

These release notes cover the following topics:

• Things you need to know first
• New Features included in v8.1.0
• Significant changes that have been made to JET since 8.0.0
  • Component Changes
  • API Changes
  • Theme Changes
  • Public Style Class Changes
  • Framework Changes
  • Library Changes
  • Tooling Changes
• Known Issues

Things you need to know first

• A new chapter is available in the JET Developers Guide for learning about the JET Audit Framework. Build custom configuration files, create your own rules sets!

• A new JET Massive Open Online Course (MOOC) is open for registration now!

• Typescript definition files for RequireJS plugins, have a new location

• This release of Oracle JET, is a minor release comprised mainly of bug fixes. It is designed to be drop in compatible with other v8.x major releases.

New Features included in v8.1.0

New UI Components and Component Features

oj-diagram

• oj-diagram.overview now supports fit-area and preserve-aspect-ratio attributes allowing an application to control aspect ratio of the overview content. Please see the API doc for the new attributes and the Overview demo for sample usage.
• The component also supports new values "centerContent" and "fixed" for the panning attribute. Please see the API doc for the new values and the Overview demo for sample usage.

Component Changes

oj-select-one has been deprecated

oj-select-one has been deprecated in favor of oj-select-single. Please refer to the API doc and demos of oj-select-single for additional information.

API Changes

No API changes in this release.

Theme Changes

There are no theme changes in this release.

Public Style Class Changes

oj-label-accesskey

JET's Accessibility team discourages accesskeys, so this styleclass has been deprecated.

oj-flex-items-pad

The oj-flex-items-pad class is deprecated. People found this class confusing, and it has limited applicability as it only controls a specific value of horizontal padding. The replacement is to place oj-sm-margin-2x-horizontal on the children/descendants where the padding was ending up.

Framework Changes

New oraclejet/dist/types/requirejs-plugins.d.ts file

Every JET application built using Typescript needs a declaration file that defines the RequireJs plugins used by JET (css, text, ojL10n) for Typescript. So far, the JET tooling has taken the responsibility of injecting an index.d.ts file with the aforementioned type definitions into applications scaffolded from Typescript templates. Since these type definitions are needed by every JET application built using Typescript, we decided to provide them in a central location as part of the type definitions we distribute. The definitions can be found in @oracle/oraclejet/dist/types/requirejs-plugins.d.ts which will be referenced in the tsconfig.json generated by the JET tooling going forward.

Library Changes

Required changes to support IE

These changes were introduced in JET v8.0.0, but are included here as a reminder

The JET code is being modernized to take advantage of the JavaScript features of modern browsers. However in order for this code to work on IE11, the JET code is also provided transpiled down to ES5. The majority of Oracle JET applications will have to make the changes to support IE11.
There are two exceptions:

• Hybrid applications that only run on phones or tablets.
• Applications that use the CDN to access the JET code. The bundles-config.js takes care of the required changes.

Note: Please consider using the CDN. The performance should be better and the configuration is simpler.
Note: This modernization is for the core JavaScript language and not browser DOM APIs.

Web Apps that Bundle JET with r.js

If your bundles include JET library code, you should create two sets of bundles, one for modern browsers and one for IE11. The ES5 bundles must map ojs to the *_es5 directories and include paths to the 'corejs' and 'regenerator-runtime' polyfills. It must also exclude the fake module named 'polyfills'.

Changes needed to the require.config()

• Detect whether ES5 code is required.
  The UserAgent is used to detect IE11. Only IE11 requires ES5.

  function _ojIsIE11() {
    var nAgt = navigator.userAgent;
    return nAgt.indexOf('MSIE') !== -1 || !!nAgt.match(/Trident.*rv:11./);
  };
  var _ojNeedsES5 = _ojIsIE11();
                    

• Pick correct ES5 or ES6 JET code
  JET ES6 code will be found in the default directories. ES5 for IE11 is found the min_es5 and debug_es5 directories.

  requirejs.config({
    paths: {
      ojs: 'libs/oj/v8.1.0/min' + (_ojNeedsES5 ? '_es5' : '')
    }
  });
                    

• Add paths for polyfills
  Two polyfill libraries are required. One to polyfill the all of the ES6 runtime improvements. The second one contains runtime support for generator functions.

  requirejs.config({
    paths: {
      corejs: 'libs/corejs/shim.min',
      'regenerator-runtime': 'libs/regenerator-runtime/runtime'
    }
  });
                    

• Define polyfills require module
  Define 'polyfills' module to pull in the polyfills only on IE11.
  Note: if all of the application modules depend either directly or indirectly on the JET library, this define might not be required.

  if (_ojNeedsES5) {
    define('polyfills', ['corejs', 'regenerator-runtime']);
  } else {
    define('polyfills', []);
  };
                    

• Polyfill legacy promise module
  Previous versions used a standalone promise polyfill. The logic is now either supported directly by modern browsers or is a part of a larger polyfill for IE11. If any application modules have a direct dependency on the requirejs 'promise' module, it should be removed. If that is not possible at this time, Add this define as a polyfill.
  Note: if all of the application modules depend either directly or indirectly on the JET library, this define might not be required.

  define('promise', ['polyfills'], function () {
    Promise.polyfill = function () {};
    return Promise;
  });
                    

oj.js removed

The oj.js library that contained all the JET code for use outside AMD has been removed.

Updated versions

No library updates in this release.

Tooling Changes

OJET CLI Release Notes

See the GitHub repository

Visual Studio Code Extension for JET Core

The VS Code extension for JET Core development has reached general availability! This extension provides support for code completion, code snippets, application audits, and much more. Read More...

New oraclejet/dist/types/requirejs-plugins.d.ts file

The new requirejs-plugins.d.ts file mentioned in the Framework Changes section centralizes the type definitions needed to make the RequireJs plugins used by JET (css, text, ojL10n) work with Typescript. Typescript applications scaffolded with v8.1.0 of ojet will have a tsconfig.json that will point to requirejs-plugins.d.ts. Typescript applications scaffolded prior to v8.1.0 will have to follow the steps below:

1. Add "./node_modules/@oracle/oraclejet/dist/types/requirejs-plugins.d.ts" to the "include" array of the application's tsconfig.json
2. Delete ALL type definitions for the RequireJs plugins used by JET (css, text and ojL10n) within the application. The definitions will primarily be found in the index.d.ts file added to web components by the tooling. If the generated index.d.ts file hasn't been modified since creation, it can safely be deleted. Failure to remove all the RequireJs plugin type definitions in the application will result in a build error caused by Typescript encountering duplicate type definitions.

Typescript build hooks

In an effort to provide Typescript applications with more Typescript customization options, we added four new hooks: before_app_typescript, before_component_typescript, after_app_typescript and after_component_typescript. The before_*_typescript hooks will provide a reference to the tsconfig object that will be passed on to the Typescript compiler and can be used to update, add or remove any of the compiler options. The after_*_typescript hooks will provide an entry point for applications that need further processing (compiling the generated *.jsx using babel for example) after the Typescript compilation has completed. Typescript applications scaffolded with v8.1.0 of ojet will have them under scripts/hooks. Typescript applications scaffoled prior to v8.1.0 will have to follow the tooling migration guidelines to uptake the new hooks.

JET Audit Framework (JAF)

Have you tried out JAF yet? It provides the ability to evaluate your JET apps and get valuable feedback from a JET perspective (think lint for JET!) JAF is easy to use.

• JET Audit Framework

The JAF ecosystem is growing rapidly and currently the JET builtin rulepack contains 55 rules for evaluating JET apps. In addition there are 4 more rulepacks (containing 37 rules) that target related JET code with a specific focus.

1. EXCH rulepack for evaluation of Web component metadata
2. SPOC rulepack for internal security audits of JET source
3. CSP rulepack for Content Security Policy compliance
4. DEMO rulepack for audit of the JET Cookbook demos.

Highlights of recent changes:

New Rules:

• oj-html-wctag-$props Checks that properties referred to in $properties are defined.
• oj-js-dis-ctor Checks for usage of calling a class constructor without new, which will fail in 8.x
• oj-js-no-ext-final Checks for invocation of JET class constructors marked as final without use of 'new' in JET 8.x (or higher). Such classes will work in 7.x, but fail in 8.x.
• oj-cca-compjson-bp-obj Reports on non-compliance of best practices for web component metadata.
• oj-cca-compjson-bp-jetver .. .. .. .. .. .. ..
• oj-cca-compjson-bp-dsplyname .. .. .. .. .. .. ..
• oj-cca-compjson-bp-ar .. .. .. .. .. .. ..
• oj-html-attr-prefix-expr Reports on colon-prefixed attributes that are not expressions.
• oj-html-attr-prefix-ro Reports on colon-prefixed attributes that are read-write expressions instead of read-only expressions.
• oj-html-bindif-test Checks that an test attribute is set to a read-only expression
• oj-html-bindforeach-data Checks that a data attribute is set to a read-only expression
• oj-js-noconsole Reports on usage of console.log for removal before shipping
• oj-html-attr-2def Reports on tags with both prefixed and non-prefixed versions of the same attribute.
• oj-html-attr-req Checks for required attributes not specified on a web component tag.
• oj-html-dlg-title Checks for use of attribute 'title' (should use 'dialog-title').
• oj-html-wctag-id Checks that web component "id" attributes are prefixed and point to an expression.
• oj-html-wctag-for Checks that web component 'for' attributes are prefixed and point to an expression.
• oj-html-wctag-$arialabelledby Checks that web component 'aria-labelledby' attributes are prefixed and point to an expression.
• oj-html-5-tag-depr/oj-html-5-attr-dep Report on usage of tags and attributes deprecated in HTML5.

New features

Scaffolding of a configuration file for a JET CLI (ojet) created/maintained application can now be performed using the ojaf command-line flag --init. (or -i).

The JS rules for deprecated/deleted members/methods are now configurable

New command line flags

--jetlist (displays the list of JET versions supported
--jetver (overrides the config to target a specific JET release
--groups (overrides the config to target specific groups of rules)

For Rule Writers

• A rule may now disable itself on startup based on the environment (refer to the register() method).
• New registered types "webcomp", "globtag", and "elem" are now available.

Configuration

• New configuration directive @include. Useful for refactoring large configuration files.
• New value for config property "format" - "line". This is similar to existing "prose", but flattens out the report style of 'prose' into single lines. This allows use of ojaf in a VS Code terminal window, to provide hyperlinks to jump straight to a file at the correct position by ctrl-clicking on the filepath in the message.
• New configuration property "lineFormat". Permits a template to be defined for custom display of issues when "format" : "line" is used.
• New template values %mid, %pos1, %pos2 for configuration proseFormat and lineFormat templates.
• New configuration property "tabs" allows specification of custom tab settings on a per file type basis.
• The JS rules for deprecated/deleted members/methods are now configurable.

Known Issues

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

Category	Bug #	Description	Workaround (if available)
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	N/A	Using the long press gesture in iOS Safari 13 may result in unexpected text selection in the page.	Users that run into this while interacting with a JET component should try modifying their gestures to avoid triggering a long press in iOS.
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	npm version 5 does not install the oraclejet module when scaffolding a JET hybrid app and building the app reports: Warning: ENOENT: no such file or directory, open 'node_modules/oraclejet/package.json' Use --force to continue	[sudo] npm install -g npm@latest-4
Chrome and Safari on Touch	N/A	In some cases, dragging an object marked as draggable on touch devices may result in simultaneous scrolling of the containing page.	The issue is caused by changes in Safari and Chrome that now treat document level touch event listeners as passive. The workaround for the issue is to add an empty, non-passive 'touchmove' event listener to an ancestor of the draggable element. E.g. ancestorElement.addEventListener('touchmove', function(event){}, { passive: false });