Developing Applications With Oracle JET

About Composite Components8-2Creating Composite Components8-6Best Practices for Composite Component Creation9Recommended Standard Patterns and Coding Practices8-14CSS and Theming Standards8-19Testing Composite Components8-21Adding Composite Components to Your Page8-21Using the Common Model and Collection APITypical Workflow for Binding Data in Oracle JET9-1About Oracle JET Data Binding9-1Using the Oracle JET Common Model and Collection Framework9-2About the Oracle JET Common Model and Collection API9-2About Oracle JET Data Binding and Knockout9-3Using the Oracle JET Common Model and Collection API9-3Integrating REST Services9-5About Oracle JET Support for Integrating REST Services9-5Passing Custom AJAX Options in Common Model CRUD API calls9-5Supplying a customURL Callback Function9-6Replacing oj.sync or oj.ajax Functions9-7Creating a CRUD Application Using Oracle JETDefining the ViewModel108-149-89-8Reading Records9-15Creating Records9-15Updating Records9-18Deleting Records9-22Validating and Converting InputTypical Workflow for Validating and Converting Input10-1About Oracle JET Validators and Converters10-2About Validators10-2Oracle JET Validators10-3Oracle JET Component Validation Attributes10-3Oracle JET Component Validation Methods10-4About ConvertersUsing Oracle JET Converters10-410-5Using Oracle JET Converters with Oracle JET Components10-5Understanding Oracle JET Converters Lenient Parsing10-9Understanding Time Zone Support in Oracle JET10-9viii

Using Custom Converters in Oracle JET10-12Using Oracle JET Converters Without Oracle JET Components10-16Using Oracle JET Validators11Using Oracle JET Validators with Oracle JET components10-18Using Custom Validators in Oracle JET10-21Working with User AssistanceTypical Workflow for Working with User Assistance11-1Understanding Oracle JET's Messaging APIs on Editable Components11-2Oracle JET Editable Component Messaging Attributes11-3Oracle JET Component Messaging Methods11-3Understanding How Validation and Messaging Works in Oracle JET EditableComponents11-4Understanding How an Oracle JET Editable Component Performs NormalValidation11-5Normal Validation Process When User Changes Value of an EditableComponent11-5Normal Validation Process When Validate() is Called on EditableComponent11-6Understanding How an Oracle JET Editable Component Performs DeferredValidation11-7Deferred Validation Process When an Oracle JET Editable Component isCreated11-7Deferred Validation Process When value Property is ChangedProgrammatically11-7Using Oracle JET MessagingNotifying an Oracle JET Editable Component of Business Validation ErrorsUsing the messages-custom AttributeUsing the showMessages() Method on Editable ComponentsUnderstanding the oj-validation-group ComponentTracking Validity of a Group of Editable Components Using 11Configuring an Editable Component's oj-label Help Attribute11-13Configuring an Editable Component's help.instruction Attribute11-15Controlling the Display of Hints, Help, and Messages11-16Developing Accessible ApplicationsTypical Workflow for Developing Accessible Oracle JET Applications12-1Oracle JET and Accessibility12-1Using the Accessibility Features of Oracle JET Components12-2Creating Accessible Oracle JET Pages12-3ix

Configuring WAI-ARIA Landmarks12-3Configuring High Contrast Mode12-5Understanding Color and Background Image Limitations in High ContrastMode12-6Adding High Contrast Mode to Your Oracle JET Application12-6Adding High Contrast Images or Icon Fonts12-7Testing High Contrast Mode12-7Hiding Screen Reader Content13Internationalizing and Localizing ApplicationsTypical Workflow for Internationalizing and Localizing Oracle JET Applications13-1About Internationalizing and Localizing Oracle JET Applications13-1Internationalizing and Localizing Oracle JET Applications13-3Using Oracle JET's Internationalization and Localization Support13-3Enabling Bidirectional (BiDi) Support in Oracle JET13-5Setting the Locale Dynamically13-6Working with Currency, Dates, Time, and Numbers13-9Working with Oracle JET Translation Bundles13-9About Oracle JET Translation Bundles13-9Adding Translation Bundles to Oracle JET1412-813-12Theming ApplicationsTypical Workflow for Theming an Oracle JET Application14-1CSS Files Included With Oracle JET14-1DOCTYPE Requirement14-2ThemeUtils14-3Setting Text Direction14-3Customizing Themes Using the Tooling14-3Sass Files, Variables, and Tools14-5SCSS File Organization and Naming Convention14-6SCSS Variables14-6Using Variables to Control CSS Content14-7Understanding Right-to-Left Behavior14-8Understanding Oracle JET Theming For Compatibility14-9SCSS Tools14-12Working with Images14-12Image Considerations14-12Icon Fonts14-13Image Files14-14x

15Securing ApplicationsTypical Workflow for Securing Oracle JET Applications15-1About Securing Oracle JET Applications15-1Oracle JET Components and Security15-2Oracle JET Security and Developer Responsibilities15-2Oracle JET Security Features15-2Oracle JET Secure Response Headers15-4Using oj.OAuth in Your Oracle JET Application15-20Initializing oj.OAuth15-20Verifying oj.OAuth Initialization15-21Obtaining the OAuth Header15-21Using oj.OAuth with Oracle JET Common Model15-22Embedding oj.OAuth in Your Application's ViewModel15-22Adding oj.OAuth as a Plugin in Your ViewModel15-23Integrating oj.OAuth with Oracle Identity Management (iDM) ServerAbout Securing Hybrid Mobile Applications171815-25Managing Authentication in JET Hybrid Mobile Apps15-25Managing App Configuration for JET Hybrid Mobile Apps15-25Dealing With Cross-Origin Resource Sharing (CORS)1615-2415-26Configuring Data Cache and Offline SupportAbout the Oracle Offline Persistence Toolkit16-1Installing the Offline Persistence Toolkit16-2Optimizing PerformanceTypical Workflow for Optimizing Performance of Oracle JET Applications17-1About Performance and Oracle JET Applications17-1Adding Performance Optimization to an Oracle JET Application17-2Testing and DebuggingTypical Workflow for Testing and Debugging an Oracle JET Application18-1Testing Oracle JET Applications18-1Testing Applications18-2Testing Hybrid Mobile Applications18-2Using oj.BusyContext API in Automated Testing18-3Debugging Oracle JET ApplicationsDebugging Web Applications18-718-7xi

Debugging Hybrid Mobile Applications19Packaging and Deploying ApplicationsTypical Workflow for Packaging and Deploying Applications19-1Packaging and Deploying Web Applications19-1Packaging Web Applications19-2Deploying Web Applications19-2Packaging and Publishing Hybrid Mobile Applications19-2About Packaging and Publishing Hybrid Mobile Applications19-3Packaging a Hybrid Mobile App on Android19-3Packaging a Hybrid Mobile App on iOS19-4Packaging a Hybrid Mobile App on Windows19-6How to Create the Build Configuration File to Package Your App onWindows19-6How to Build Your App for Windows19-7Removing Build Output and Extraneous Files from Your JET Application’s SourceATroubleshootingBOracle JET v4.2.0 Tooling MigrationC18-819-8Migrating a v3.x.0 Application to v4.2.0B-1Migrating a v4.0.0 Application to v4.1.0B-3Oracle JET ReferencesOracle Libraries and ToolsC-1Third-Party Libraries and ToolsC-1xii

PrefaceDeveloping Applications with Oracle JET describes how to build responsive web andhybrid mobile applications using Oracle JET.Topics: Audience Documentation Accessibility Related Resources ConventionsAudienceDeveloping Applications with Oracle JET is intended for intermediate to advancedJavaScript developers who want to create pure client-side, responsive web or hybridmobile applications based on JavaScript, HTML5, and CSS3.Documentation AccessibilityFor information about Oracle's commitment to accessibility, visit the OracleAccessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx acc&id docacc.Access to Oracle SupportOracle customers that have purchased support have access to electronic supportthrough My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx acc&id info or visit http://www.oracle.com/pls/topic/lookup?ctx acc&id trsif you are hearing impaired.Related ResourcesFor more information, see these Oracle resources: Oracle JET Web Site JavaScript API Reference for Oracle JavaScript Extension Toolkit (JET) Oracle JavaScript Extension Toolkit (JET) Keyboard and Touch Reference Oracle JavaScript Extension Toolkit (JET) Styling Referencexiii

PrefaceConventionsThe following text conventions are used in this document:ConventionMeaningboldfaceBoldface type indicates graphical user interface elements associatedwith an action, or terms defined in text or the glossary.italicItalic type indicates book titles, emphasis, or placeholder variables forwhich you supply particular values.monospaceMonospace type indicates commands within a paragraph, URLs, codein examples, text that appears on the screen, or text that you enter.xiv

What’s New in This Guide for Release4.2.0For Oracle JET Release 4.2.0 this guide has been updated in several ways. Thefollowing table lists the sections that are new or changed since Oracle JET Release4.1.0.For changes made to Oracle JavaScript Extension Toolkit (JET) for this release, seethe product Release Notes.ChapterLinkChapter 2 Getting Started Getting Started withwith Oracle JETOracle JET ApplicationApplication Development DevelopmentChanges MadeChapter updated to reflect the following changes: Install Gradle and Configure Gradle Proxy Settingsupdated to describe the requirement to install Gradleseparately from Android Studio if you use CordovaAndroid 6.4.0 or later.Loading Oracle JET from CDNupdated for new JET version number.Chapter 6 Understanding Understanding Oracle JET About Binding and Control Flow added to describe theOracle JET UserUser Interface BasicsOracle JET syntax for data binding.Interface BasicsChapter 7 Working withOracle JET UserInterface ComponentsWorking with Oracle JETUser InterfaceComponentsChapter updated to reflect the following changes: Choosing a Table, Data Grid, or List View updated todescribe new oj-list-view component features.Understanding Data Requirements for List Viewsupdated to describe the array data source,oj.ArrayDataProvider, for oj-list-view.Understanding Data Requirements for Nav Listsupdated to describe the array data source,oj.ArrayDataProvider, for oj-navigation-list .Understanding Data Requirements for Tab Barsupdated to describe the new array data source,oj.ArrayDataProvider, for oj-tab-bar .Working with oj-form-layout added to describe theresponsive layout.Working with File Picker updated to reflect theJavaScript and HTML code example changes.Understanding oj-combobox-one Search added todescribe new search functionality using the ojcombobox-one element.Working with Comboboxes updated to describe thenew data provider functionality.Working with Select updated to describe the new dataprovider functionality.xv

What’s New in This Guide for Release 4.2.0ChapterLinkChanges MadeChapter 8 Working withOracle JET CompositeComponentsWorking with Oracle JETComposite ComponentsCSS and Theming Standards added to describe bestpractices for styling composite components.Chapter 11 Working withUser AssistanceWorking with UserAssistanceUnderstanding the oj-validation-group Component added todescribe the newoj-validation-group .Chapter 16 ConfiguringData Cache and OfflineSupportConfiguring Data Cacheand Offline SupportChapter added to describe the offline-persistence-toolkit.This toolkit is primarily intended for hybrid mobileapplications created using Oracle JET, but it can be usedwithin any JavaScript client application that requirespersistent storage and/or offline data access.Appendix Oracle JETv4.2.0 Tooling MigrationOracle JET v4.2.0 Tooling Version update.Migrationxvi

1About Oracle JavaScript Extension Toolkit(JET)Oracle JET is a collection of Oracle and open source JavaScript libraries engineeredto make it as simple and efficient as possible to build client-side web and hybrid mobileapplications based on JavaScript, HTML5, and CSS.Oracle JET is designed to meet the following application needs: Add interactivity to an existing page. Create a new end-to-end client-side web application using JavaScript, HTML5,CSS, and best practices for responsive design. Create a hybrid mobile application that looks and feels like a native iOS, Androidor Windows application.Topics: The Oracle JET Architecture What's Included in Oracle JETYou can also view videos that provide an introduction to Oracle JET in the Oracle JETVideos collection.The Oracle JET ArchitectureOracle JET supports the Model-View-ViewModel (MVVM) architectural design pattern.In MVVM, the Model represents the application data, and the View is the presentationof the data. The ViewModel exposes data from the Model to the view and maintainsthe application's state.1-1

Chapter 1The Oracle JET ArchitectureTo support the MVVM design, Oracle JET is built upon a modular framework thatincludes a collection of third-party libraries and Oracle-provided files, scripts, andlibraries.The Oracle JET Common Model and Collection Application Programming Interface(API) implements the model layer. The API includes the following JavaScript objects: oj.Model: Represents a single record data from a data service such as a RESTfulweb service oj.Collection: Represents a set of data records and is a list of oj.Model objects ofthe same type oj.Events: Provides methods for event handling oj.KnockoutUtils: Provides methods for mapping the attributes in an oj.Model oroj.Collection object to Knockout observables for use with component viewmodels.To implement the View layer, Oracle JET provides a collection of UI componentsimplemented as HTML5 custom elements, ranging from basic buttons to advanceddata visualization components such as charts and data grids.Knockout.js implements the ViewModel and provides two-way data binding betweenthe view and model layers.Oracle JET FeaturesOracle JET features include: Messaging and event services for both Model and View layers Validation framework that provides UI element and component validation and dataconverters Caching services at the Model layer for performance optimization of paginationand virtual scrolling Filtering and sorting services provided at the Model layer Connection to data sources through Web services, such as Representational StateTransfer (REST) or WebSocket1-2

Chapter 1The Oracle JET Architecture Management of URL and browser history using Oracle JET oj.Router and ojModulecomponents Integrated authorization through OAuth 2.0 for data models retrieved from RESTServices Resource management provided by RequireJS API compatibility with Backbone.js Model, Collection, and Events classes, exceptfor Backbone.js Underscore methods. JavaScript logging Popup UI handlingHybrid Mobile Application Development Toolkit FeaturesOracle JET includes support for hybrid mobile applications that run on iOS, Android,and Windows mobile devices within the Apache Cordova container.Apache Cordova enables you to use web technologies such as HTML5, CSS, andJavaScript to develop applications that you can deploy to mobile devices. Using theCordova JavaScript APIs to access native device services, major mobile platformssuch as Android, iOS, and Windows can be supported from a common code base.The following image shows the same application code rendered on an iOS, Android,and Windows mobile device. Oracle JET automatically applies the native theme whenyou configure the application for the desired platform.To support hybrid mobile development, Oracle JET includes the following features: Native themes that you can use with Cordova to create hybrid mobile applicationsthat emulate the look and feel of native iOS, Android, and Windows mobile devices Tooling that enables you to scaffold and build Cordova-based hybrid applicationsusing Oracle JET directly from the command line Code samples, applications, and demos that you can use to create hybrid mobileapplications using Oracle JET best practices1-3

Chapter 1What's Included in Oracle JET Mobile UI behaviors and interactive gestures such as animation, sticky headers,pull to refresh, and swipe to revealOracle JET Visual Component FeaturesOracle JET visual components include the following features and standardscompliance: Compliance with Oracle National Language Support (NLS) standards (i18n) fornumeric, currency, and date/time formatting Built-in theming supporting the Oracle Alta UI style specifications Support for Oracle software localization standards, l10n, including:–Lazy loading of localized resource strings at run time–Oracle translation services formats–Bidirectional locales (left-to-right, right-to-left) Web Content Accessibility Guidelines (WCAG) 2.0. In addition, componentsprovide support for high contrast and keyboard-only input environments. Gesture functionality by touch, mouse, and pointer events where appropriate Support for Oracle test automation tooling Responsive layout frameworkWhat's Included in Oracle JETThe Oracle JET zip distribution includes Oracle JET libraries and all third partylibraries that the toolkit uses.Specifically, Oracle JET includes the following files and libraries: CSS and SCSS files for the Alta theme Minified and debug versions of the Oracle JET libraries Data Visualization Tools (DVT) CSS and JavaScript Knockout and Knockout Mapping libraries jQuery libraries RequireJS, RequireJS text plugin, and RequireJS CSS plugin js-signals es6-promise polyfill Hammer.jsOracle JET components use Hammer.js internally for gesture support. Do not addto Oracle JET components or their associated DOM nodes. Oracle JET dnd-polyfill HTML5 drag and drop polyfill proj4js library webcomponentsjs polyfill1-4

2Getting Started with Oracle JET ApplicationDevelopmentUse Oracle JET to create web and hybrid mobile applications. The toolkit providescustomizable Alta themes for desktop platforms and mobile devices. The toolkit alsoincludes Oracle JET components, Starter Templates, UI design patterns, tooling, anda mechanism to load content from the Oracle Content Delivery Network (CDN).Topics Typical Workflow for Getting Started with Oracle JET Application Development Prerequisites for Developing Applications with Oracle JET Getting Started with Oracle JET Web Application Development Getting Started with Oracle JET Hybrid Mobile Application Development Working with the Oracle JET Starter Templates Loading Oracle JET from CDNTypical Workflow for Getting Started with Oracle JETApplication DevelopmentFamiliarize yourself with the third party tools that Oracle JET uses before you startdevelopment. Depending on your installation method, you may also need to installprerequisite packages. After you’ve created your application, you can customize yourconfiguration or load Oracle JET from the Oracle Content Delivery Network (CDN).To get started developing Oracle JET applications, refer to the typical

About Composite Components 8-2 Creating Composite Components 8-6 Best Practices for Composite Component Creation 8-14 Recommended Standard Patterns and Coding Practices 8-14 CSS and Theming Standards 8-19 Testing Composite Components 8-21 Adding Composite Components to Your Page 8-21 9 U