Work with Oracle JET User Interface Components

7 Work with Oracle JET User Interface Components

Oracle JET provides a variety of user interface (UI) components that you can configure for use in your app. The Oracle JET Cookbook includes an example of each component for working with collections, controls, forms, visualizations, and other features.

About Oracle JET User Interface Components

Oracle JET currently has two sets of UI components. The first set with components that use the oj- namespace are packaged in @oracle/oraclejet and date back to the initial releases of Oracle JET. The newer Core Pack components, introduced in January 2023 with release 14.0.0 of Oracle JET, use the oj-c- namespace and are packaged in @oracle/oraclejet-core-pack.

Core Pack components represent the future of JET. The JET team are rewriting all the existing JET UI components from scratch using Preact, a modern virtual DOM rendering library that uses React design and composition principles. The JET 14 release delivers the first set of these newer Core Pack components. This component set will grow over the coming years until all existing components have been re-created as Core Pack components. The JET team will also be introducing new UI components to the Core Pack component set during the same period.

JET's existing set of UI components, now referred to as Legacy components, has served the JET community and its app developers well for the last 10 years. The Legacy components, using the oj- namespace, will run side-by-side with the newer Core Pack components, using the oj-c- namespace in the same JET apps. The APIs are similar, if not identical in many cases. The newer Core Pack was created with the intention of allowing for updates and changes to APIs that don't make sense going forward, without disrupting your existing application code. As a developer, you can choose when you want to move to the new components as part of your regular development cycle.

You might ask why you should move to these components at all. The main reason is performance. Rendering performance is significantly improved with the Core Pack components. While a new component set will not automatically change the overall performance of your app, the render time can definitely make your apps look and feel more responsive to your customer. The second reason to use the Core Pack component set is that all future new components will be delivered as part of it. We will not be developing new Legacy UI components (oj-) in the future.

Each new Core Pack component includes an example implementation in the Oracle JET Cookbook and an entry in the API documentation. A badge identifies these implementations and entries.

JET Cookbook and API Doc Entries for Core Pack

For details about how to work with the Core Pack components, any short-term limitations, and migration information, see Core Pack in the API documentation.

Work with Collections

Use Oracle JET data collection components to display data in tables, data grids, list views, or trees.

The Oracle JET data collection components include oj-table, oj-data-grid, oj-tree, and oj-list-view, and you can use them to display records of data. oj-table and oj-data-grid both display data in rows and columns, and your choice of component depends upon your use case. Use oj-tree-view to display hierarchical data such as a directory structure and oj-list-view to display a list of data. The toolkit also includes pagination and row expanders that display hierarchical data in a data grid or table row.

The Oracle JET Cookbook's Collections category and API Reference for Oracle® JavaScript Extension Toolkit (Oracle JET) include complete demos and examples for using the collection components.

Note:

If you programmatically control the display of a collection component, such as oj-table, review Manage the Visibility of Added Component.

Choose a Table, Data Grid, or List View

Oracle JET provides the oj-table, oj-data-grid, and oj-list-view components to display data in rows and columns. This section helps you decide which component to use in your app.

The oj-table component displays records of data on a row basis. It's best used when you have simple data that can be presented as rows of fields, and it should be your first choice as it provides a simpler layout to represent the data and also supports most of the common features, unless you require advanced features. A selection in the table provides you with the row of data and all of the fields in that row or record. The sizing of the table is based on the content itself. The height and width of the cells is adjusted for the content included. You can write templates using oj-table elements such as tr, td, th, and so on. Also consider making use of the oj-table component’s layout attribute that enables you to change column sizing based on fixed values or content size. See the oj-table component’s Column Layouts demo in the Oracle JET Cookbook.

The oj-data-grid is designed to provide grid functionality. It provides the ability to select individual or ranges of cells of data. It's best used when you need to display totals or tallies of data across columns or rows of data. The oj-data-grid is designed to be much more flexible in its layout and functionality than the oj-table component. It's a low-level component that you can shape in your app to how you want the data to be displayed. The overall size of the data grid is not determined by its content, and the developer specifies the exact height and width of the container. The data grid acts as a viewport to the contents, and unlike a table its size is not determined by the size of the columns and rows. With this custom HTML oj-data-grid element, you can host the template content inside it.

The oj-list-view element displays a list of data or a list of grouped data. It is best used when you need to display a list using an arbitrary layout or content. You can also use oj-list-view to display hierarchical data that contains nested lists within the root element.

The table below provides a feature comparison of the oj-table, oj-data-grid, and oj-list-view components.

Feature	oj-table	oj-data-grid	oj-list-view
Column/Row sizing	Controlled by content or fixed by CSS styles. All CSS sizing strings are supported for width and height.	Controlled by cell dimensions. Does not support percent values for width and height.	No
User-resizable column	Yes	Yes	No
User-resizable row	No	Yes	No
Row reordering	No	Yes	No
Column sorting	Yes	Yes	No
Column selection	Yes	Yes	No
Row sorting	No	Yes	No
Row selection	Yes	Yes	Yes
Cell selection	No	Yes	No
Marquee selection	No	Yes	No
Row header support	No	Yes	No
Freeze columns	Yes Use the `frozenEdge` property to freeze a column to the start or end of the table.	No	No
Pagination	Yes	Yes	Yes
Scrolling (high water mark / infinite scrolling)	Yes, when end of table reached (or document size). See note at the end about virtual scrolling.	Yes, when data grid column / row count reached (see note about virtual scrolling option)	Yes, when end of list reached (or document size) See note at the end about virtual scrolling.
Custom cell templates	Yes	Yes	No
Custom row templates	Yes	No	Yes
Custom cell renderers	Yes	Yes	No
Custom row renderers	Yes	No	Yes
Row expander support	Yes	No	No
Cell stamping	Yes	Yes	No
Cell merging	No	Yes	No
Render aggregated cubic data	No	Yes	No
Custom footer template	Yes (provides access to column data for passing to a JavaScript function)	Yes	No
Cell content editing	Yes	Yes	No
Content filtering	Yes	Yes	No
KeySet API support	Yes	No	Yes

Note:

True virtual scrolling is available as a feature of oj-data-grid. Modern design principles should be considered and implemented before implementing virtual scrolling. It is much more desirable to present the end user with a filtered list of data that will be more useful to them, than to display thousands of rows of data and expect them to scroll through it all. True virtual scrolling means that you can perform scrolling in both horizontal and vertical directions with data being added and removed from the underlying DOM. High water mark scrolling (with lazy loading) is the preferred method of scrolling, and you should use it as a first approach.

In the case of oj-table and oj-list-view, you can set scroll-policy-options.scroller to specify the document size as the maximum scroll position before the next data fetch occurs. This is particularly useful when your app runs in a mobile device where the table or list occupies the entire screen.

KeySet objects are used to represent the selected items in a component. The collection components generally uses an array for the selected items or an object that defines the range of selected items. You can modify these components to use a KeySet object that handles the representation of selected items. Note that the Data Grid component does not currently support KeySet object referencing for the selected items. The oj-list-view component can use KeySet to determine the selected items. The oj-table component can use KeySet to determine the selected items for the rows or columns. If both values are specified, then row will take precedence and column will be reset to an empty KeySet.

About DataProvider Filter Operators

The DataProvider interface is used to get runtime data for JET components that display list of items. DataProvider implementations use filter operators for filtering.

You can specify two types of filters:

Attribute Filter: Provides filters with the functionality of attribute operator filtering.

interface AttributeFilter<D> extends AttributeFilterDef<D>{
  filter(item: D, index?: number, array?: Array<D>): boolean;
}
type Filter<D> = AttributeFilter<D> | CompoundFilter<D>;

type RecursivePartial<T> = {
  [P in keyof T]?:
    T[P] extends (infer U)[] ? RecursivePartial<U>[] :
    T[P] extends object ? RecursivePartial<T[P]> :
    T[P];
};

interface AttributeFilterDef<D> {
  readonly op: AttributeFilterOperator.AttributeOperator;
  readonly attribute?: keyof D;
  readonly value: RecursivePartial<D>;
}
 
type AttributeFilterAttributeExpression = '*';

Compound Filter: Provides filter operators for compound operations.

interface CompoundFilter<D> extends CompoundFilterDef<D>, BaseFilter<D> {
}

interface CompoundFilterDef<D> {
  readonly op: CompoundFilterOperator.CompoundOperator;
  readonly criteria: Array<AttributeFilterDef<D> | CompoundFilterDef<D>>;
}

Filter definition which filters on DepartmentId value 10:

{op: '$eq', value: {DepartmentId: 10}}

Filter definition which filters on DepartmentId value 10 and DepartmentName is Hello:

{op: '$eq', value: {DepartmentId: 10, DepartmentName: 'Hello'}}

Filter definition which filters on subobject Location where State is California and DepartmentName is Hello:

{op: '$eq', value: {DepartmentName: 'Hello', Location: {State: 'California'}}}

For additional detail and the complete list of operators that you can use with Attribute filters, see the AttributeFilterDef API documentation.

For additional detail and the complete list of operators that you can use with Compound filters, see the CompoundFilterDef API documentation.

Work with Controls

Oracle JET includes buttons, menus, and container elements to control user actions or display progress against a task. For HTML elements such as simple lists, you can use the standard HTML tags directly on your page, and Oracle JET will apply styling based on the app's chosen theme.

For example, you can use the oj-button element as a standalone element or include in oj-buttonset , oj-menu, and oj-toolbar container elements.

Navigation components such as oj-conveyor-belt, oj-film-strip, and oj-train use visual arrows or dots that the user can select to move backward or forward through data.

To show progress against a task in a horizontal meter, you can use the oj-progress-bar element. To show progress against a task in a circle, you can use the oj-progress-circle element.

The Oracle JET Cookbook's Controls category and API Reference for Oracle® JavaScript Extension Toolkit (Oracle JET) include complete demos and examples for using Oracle JET controls.

Work with Forms

Oracle JET includes classes to create responsive form layouts and components that you can add to your form to manage labels, form validation and messaging, input, and selection. The input components also include attributes to mark an input as disabled or read-only when appropriate.

The Oracle JET Cookbook's Forms category and API Reference for Oracle® JavaScript Extension Toolkit (Oracle JET) includes complete demos and examples for using forms.

Important:

When working with forms, use the HTML div element to surround any Oracle JET input components. Do not use the HTML form element because its postback behavior can cause unwanted page refreshes when the user submits or saves the form.

Work with Layout and Navigation

Use the Oracle JET oj-accordian, oj-collapsible, oj-dialog, oj-drawer-*, oj-flex*, oj-masonry-layout, oj-navigation-list, oj-panel, oj-popup, oj-size*, and oj-tab-bar components and patterns to control the initial data display and allow the user to access additional content by expanding sections, selecting tabs, or displaying dialogs and popups.

The Oracle JET Cookbook's Layout and Navigation category and API Reference for Oracle® JavaScript Extension Toolkit (Oracle JET) include complete demos and examples for using the layout and navigation components.

For information about the flex layout (oj-flex*) and responsive grid (oj-size) classes, see Design Responsive Apps.

Work with Visualizations

The Oracle JET visualization components include charts, gauges, and other components that you can use and customize to present flat or hierarchical data in a graphical display for data analysis.

Choose a Data Visualization Component for Your App

The visualization components include charts, gauges, and a variety of other visualizations including diagrams, timelines, thematic maps, and so on that you can use for displaying data. You may find the following usage suggestions helpful for determining which visualization to use in your app.

Charts

Charts show relationships among data and display values as lines, bars, and points within areas defined by one or more axes.

Chart Type	Description	Usage Suggestions
Area	Displays series of data whose values are represented by filled-in areas. Areas can be stacked or unstacked. The axis is often labeled with time periods such as months.	Use to show cumulative trends over time, such as sales for the last 12 months. Area charts require at least two groups of data along an axis. If you are working with multiple series and want to display unstacked data, use line or line with area charts to prevent values from being obscured.
Bar	Displays data as a series of rectangular bars whose lengths are proportional to the data values. Bars display vertically or horizontally and can be stacked or unstacked.	Use to compare values across products or categories, or to view aggregated data broken out by a time period.
Box Plot	Displays the minimum, quartiles, median, and maximum values of groups of numerical data. Groups display vertically or horizontally. You can also vary the box width to make the width of the box proportional to the size of the group.	Use to analyze the distribution of data. Box plots are also called box and whisker diagrams.
Bubble	Displays three measures using data markers plotted on a two-dimensional plane. The location of the markers represents the first and second measures, and the size of the data markers represents the proportional values of the third measure.	Use to show correlations among three types of values, especially when you have a number of data items and you want to see the general relationships. For example, use a bubble chart to plot salaries (x-axis), years of experience (y-axis), and productivity (size of bubble) for your work force. Such a chart enables you to examine productivity relative to salary and experience.
Combination	Displays series of data whose values are represented by a combination of bars, lines, or filled-in areas.	Combination charts are commonly configured as lines with bars for lines with stacked bars. For example, you can use a line to display team average rating with bars to represent individual team member ratings on a yearly basis.
Funnel	Visually represents data related to steps in a process as a three-dimensional chart that represents target and actual values, and levels by color. The steps appear as vertical slices across a horizontal cone-shaped section. As the actual value for a given step or slice approaches the quota for that slice, the slice fills.	Use to watch a process where the different sections of the funnel represent different stages in the process, such as a sales cycle. The funnel chart requires actual values and target values against a stage value, which might be time.
Line	Displays series of data whose values are represented by lines.	Use to compare items over the same time. Charts require data for at least two points for each member in a group. For example, a line chart over months requires at least two months. Typically a line of a specific color is associated with each group of data such as the Americas, Europe, and Asia. Lines should not be stacked which can obscure data. To display stacked data, use area or line with area charts.
Line with Area	Displays series of data whose values are represented as lines with filled-in areas.	Use for visualizing trends in a set of values over time and comparing those values across series.
Pie	Represents a set of data items as proportions of a total. The data items are displayed as sections of a circle causing the circle to look like a sliced pie.	Use to show relationship of parts to a whole such as how much revenue comes from each product line. Consider treemaps or sunbursts if you are working with hierarchical data or you want your visual to display two dimensions of data.
Polar	Displays series of data on a polar coordinate system. The polar coordinate system can be used for bar, line, area, combination, scatter, and bubble charts. Polygonal grid shape (commonly known as radar) is supported for polar line and area charts.	Use to display data with a cyclical x-axis, such as weather patterns over months of the year, or for data where the categories in the x-axis have no natural ordering, such as performance appraisal categories.
Pyramid	Displays values as slices in a pyramid. The area of each slice represents its value as a percentage of the total value of all slices.	Use to display hierarchical, proportional and foundation-based relationships, process steps, organizational layers, or topics interconnections.
Range	Displays a series of data whose values are represented either as an area or bar proportional to the data values.	Use to display a range of temperatures for each day of a month for a city.
Scatter	Displays two measures using data markers plotted on a two-dimensional plane.	Use to show correlation between two different kinds of data values, such as sales and costs for top products. Scatter charts are especially useful when you want to see general relationships among a number of items.
Spark	Display trends or variations as a line, bar, floating bar, or area. Spark charts are simple and condensed.	Use to provide additional context to a data-dense display. Sparkcharts are often displayed in a table, dashboard, or inline with text.
Stock	Display stock prices and, optionally, the volume of trading for one or more stocks. When any stock or candlestick chart includes the volume of trading, the volume appears as bars in the lower part of the chart.

Gauges

Gauges focus on a single value, displayed in relation to minimum, maximum, or threshold values.

Gauge Type	Description	Usage Suggestions
LED	Graphically depicts a measurement, such as a key performance indicator (KPI). Several styles of shapes are available, including round or rectangular shapes that use color to indicate status, and triangles or arrows that point up, left, right, or down in addition to the color indicator.	Use to highlight a specific metric value in relation to its threshold.
Rating	Displays and optionally accepts input for a metric value.	Use to show ratings for products or services, such as the star rating for a movie.
Status Meter	Displays a metric value on a horizontal, vertical, or circular axis. An inner rectangle shows the current level of a measurement against the ranges marked on an outer rectangle. Optionally, status meters can display colors to indicate where the metric value falls within predefined thresholds.

Other Data Visualizations

Other data visualizations include maps, timelines, Gantt charts and various other components that don’t fit into the chart or gauge category.

Data Visualization Component	Description	Usage Suggestions
Diagram	Models, represents, and visualizes information using a shape called a node to represent data, and links to represent relationships between nodes.	Use to highlight both the data objects and the relationships between them.
Gantt	Displays bars that indicate the start and end date of tasks.	Use to display project schedules.
Legend	Displays a panel which provides an explanation of the display data in symbol and label pairs.	Consider using the legend component when multiple visualizations on the same page are sharing a coloring scheme. For an example using `ojLegend` with a bubble chart, see Use Attribute Groups With Data Visualization Components.
NBox	Displays data items across two dimensions. Each dimension can be split into multiple ranges, whose intersections result in distinct cells representing data items.	Use to visualize and compare data across a two-dimensional grid, represented visually by rows and columns.
PictoChart	Uses stamped images to display discrete data as a visualization of an absolute number or the relative size of different parts of a population.	Common in infographics. Use when you want to use icons to: visualize a discrete value, such as the number of people in a sample that meets a specified criteria. highlight the relative sizes of the data, such as the number of people belonging to each age group in a population sample.
Sunburst	Displays quantitative hierarchical data across two dimensions, represented visually by size and color. Uses nodes to reference the data in the hierarchy. Nodes in a radial layout, with the top of the hierarchy at the center and deeper levels farther away from the center.	Use for identifying trends for large hierarchical data sets, where the proportional size of the nodes represents their importance compared to the whole. Color can also be used to represent an additional dimension of information. Use sunbursts to display the metrics for all levels in the hierarchy.
Tag Cloud	Displays textual data where font style and size emphasizes the importance of each data item.	Use for quickly identifying the most prominent terms to determine their relative importance.
Thematic Map	Displays data that is associated with a geographic location.	Use to show trends or patterns in data with a spatial element to it.
Time Axis	Displays a range of dates based on specified start and end dates and a time scale.	Use when you want to fulfil certain Gantt use cases. This component is intended to be stamped inside Table or Data Grid components.
Timeline	Displays a set of events in chronological order and offers rich support for graphical data rendering, scale manipulation, zooming, resizing, and objects grouping.	Use to display time specific events in chronological order.
Treemap	Displays quantitative hierarchical data across two dimensions, represented visually by size and color. Uses nodes to reference the data in the hierarchy. Nodes are displayed as a set of nested rectangles.	Use for identifying trends for large hierarchical data sets, where the proportional size of the nodes represents their importance compared to the whole. Color can also be used to represent an additional dimension of information Use treemaps if you are primarily interested in displaying two metrics of data using size and color at a single layer of the hierarchy.

For examples that implement visualization components, see the Oracle JET Cookbook at Data Visualizations.

Note:

To use an Oracle JET data visualization component, you must configure your app to use RequireJS. For details about adding RequireJS to your app, Use RequireJS in an Oracle JET App.

Use Attribute Groups With Data Visualization Components

Attribute groups allow you to provide stylistic values for color and shape that can be used as input for supported data visualization components, including bubble and scatter charts, sunbursts, thematic maps, and treemaps. In addition, you can share the attribute values across components, such as a thematic map and a legend, using an attribute group handler.

Using attribute groups is also one way that you can easily provide visual styling for data markers for a given data set. Instead of manually choosing a color for each unique property and setting a field in your data model, you can use an attribute group handler to get back a color or shape value given a data value. Once an attribute group handler retrieves a color or shape value given a data value, all subsequent calls that pass in the same data value will always return that color or shape.

Oracle JET provides the following classes that you can use for adding attribute groups to your data visualization components:

ColorAttributeGroupHandler: Creates a color attribute group handler that will generate color attribute values.

Colors are generated using the values in the .oj-dvt-category-index* tag selectors.
ShapeAttributeGroupHandler: Creates a shape attribute group handler that will generate shape attribute values.

Supported shapes include square, circle, human, triangleUp, triangleDown, diamond, and plus.

You can see the effect of applying attribute groups to a bubble chart in the following figure. In this example, the shape of the markers (round, diamond, and square) indicates the year for which the data applies. The color differentiates the brand. The example also uses the Legend data visualization component to provide a legend for the bubble chart.

Description of ui_attr_groups.png follows

Description of the illustration ui_attr_groups.png

The bubble chart's legend uses the same attribute group handlers for color and shape.

The Oracle JET Cookbook provides the complete code for implementing bubble charts at Bubble Charts.

You can also initialize an attribute group with match rules which consist of a map of key value pairs for categories and the matching attribute values. For example, if you wanted to specify colors for specific categories instead of using the default colors, you could define the color attribute group with match rules.

var colorHandler = new ColorAttributeGroupHandler({"soda":"#336699",
                                                      "water":"#CC3300",
                                                      "iced tea":"#F7C808"});

For detailed information about ColorAttributeGroupHandler, see the ColorAttributeGroupHandler API documentation. For more information about ShapeAttributeGroupHandler, see the ShapeAttributeGroupHandler API documentation.