Using the Oracle JET Common Model and Collection Framework

The Oracle JET Common Model and Collection API provides a collection-of-records object model that includes classes for bringing external data into an Oracle JET application and mapping the data to the application’s view model.

Topics:

About the Oracle JET Common Model and Collection API

The Oracle JET Common Model and Collection API provides a collection-of-records object model that includes the following classes:

oj.Model: Represents a single record from a data service such as a REST service
oj.Collection: Represents a set of data records and is a list of oj.Model objects of the same type
oj.Events: Provides methods for event handling
oj.KnockoutUtils: Provides methods for mapping the attributes in a oj.Model or oj.Collection object to Knockout observables for use with component ViewModels

oj.Model and oj.Collection include client-side API that provides one way to bring external data into an Oracle JET application. oj.KnockoutUtils provides the map() method to map the attributes in a model object or the attributes of all models in a collection object to the application's view data model.

About Oracle JET Data Binding and Knockout

Knockout provides bindings between components as well as binding data from a ViewModel to components or HTML elements in an Oracle JET application. Knockout is an integral part of Oracle JET's toolkit and is included in the Oracle JET distribution.

The Oracle JET Model and Collection API includes the KnockoutUtils class which contains the map() method to convert the attributes in a model object (or the attributes of all models in a collection object) into Knockout observables for use with components' ViewModels.

The example below maps the data collection to the tasks ViewModel.

renderTaskViews = function(tasksData) {
    this.tasks = oj.KnockoutUtils.map(data);
}

To utilize the data model in Oracle JET applications, Oracle JET provides custom elements which support Knockout variables in the data attribute. For additional information about working with Oracle JET UI components, see Understanding Oracle JET User Interface Basics.

<oj-table  data="[[dataSource]]">
</oj-table>

For additional information about Knockout, see http://www.knockoutjs.com.

Using the Oracle JET Common Model and Collection API

To use a Model or Collection class, an application must extend oj.Model or oj.Collection to create a foundation object to represent a data record or list of records from its data service. The application provides the data service's URL used for fetching and updating task records (when a task record's ID is appended), along with various options giving users the ability to map data service records to their client-side ViewModel and vice versa.

To use the Oracle JET Common Model and Collection API:

Add JavaScript code to your application that extends oj.Model.

The following script shows a simple example of extending oj.Model to create a model object which defines a Department. In this example, the data is returned from the REST service at the indicated URL. The parse callback parses the data and maps the attributes received from the REST service to desired ViewModel attribute names.

var self = this;
self.serviceURL = 'http://RESTServerIP:port/stable/rest/Departments';
self.Department = oj.Model.extend({
        urlRoot: self.serviceURL,
        parse: self.parseDept,
        idAttribute: 'DepartmentId'
    }); 
 
/**
 * Callback to map attributes returned from RESTful data service to desired view model attribute names
 */
self.parseDept = function(response) {
        return {DepartmentId: response['DepartmentId'],
            DepartmentName: response['DepartmentName'],
            LocationId: response['LocationId'],
            ManagerId: response['ManagerId']};
};

Add JavaScript code to your application that extends oj.Collection.
The following code example creates a collection object for its entire data set (or list) of task records and ties that to a specific instance of a task record model. The fetch() method tells the collection to go to the data service and asynchronously retrieve the data services' data set using the given URL, through jQuery AJAX calls. The application's success callback method is invoked when the call successfully returns and the collection has been populated with model records.
```
self.DeptCol = ko.observable();
self.myDept = new self.Department();

// Create a base object "class" for the entire dataset
self.DeptCollection = oj.Collection.extend({
        url: self.serviceURL + "?limit=50",
        model: self.myDept
    });

// Create a specific instance for the departments.  This will be filled with instances of the
// model "department" for each record when the data is retrieved from the data service
self.DeptCol(new self.DeptCollection());
self.datasource(new oj.CollectionTableDataSource(self.DeptCol()));
```
Bind the returned data collection to a Knockout ViewModel to make it ready for consumption by one or more components on the application page.
The following code sample maps the vm Collection object to the element in the view with the ID 'table' using the ko.applyBindings() function.
```
var vm = new viewModel;

$(document).ready(function() {
        ko.applyBindings(vm, document.getElementById('table'));
    });
```

Add code to the application's index.html or main page that consumes the Knockout ViewModel.

The following code examples shows a simple table that is defined with four columns: Department Id, Department Name, Location Id, and Manager Id. The data attribute binds the datasource collection to the ViewModel using Knockout.

<oj-table id="table" summary="Department List" aria-label="Departments Table"
                                        data='[[datasource]]' 
                                        columns='[{"headerText": "Department Id", 
                                                   "field": "DepartmentId"},
                                                  {"headerText": "Department Name", 
                                                   "field": "DepartmentName"},
                                                  {"headerText": "Location Id", 
                                                   "field": "LocationId"},
                                                  {"headerText": "Manager Id", 
                                                   "field": "ManagerId"}]'>
</oj-table>

For a complete list of Oracle JET Common Model and Collection API properties and functions, see the oj.Model and oj.Collection API documentation.