Understand UI Components
User interface (UI) components encapsulate a unit of user interface interaction through a defined contract.
The Web Component contract exposes the functionality of a component through the user interface, enabling the component to interact with other parts of the application. Visual Builder supports the Oracle JavaScript Extension Toolkit (JET) components contract, which adds data binding, component metadata, and dependencies on top of the Web Component contract. The Oracle JET components contract exposes a custom Document Object Model (DOM) HTML element with custom properties, events, and methods. The property binding added by Oracle JET supports both one-way (read-only) and two-way (read/write) binding. In general, the component properties are bound to variables, and the component events trigger action chains.
A component can have zero or more slots that can hold one or more children of that component. For example, a toolbar can contain a number of buttons.
You can add components to an application from the Component Palette. You can also use custom JET components, including those supplied by the Component Exchange. See Work with the Component Exchange for details.
For simple use cases, you can use a simple HTML component and corresponding view model implementation.
For details about Oracle JET, see http://www.oracle.com/webfolder/technetwork/jet/index.html. The Oracle JET Cookbook provides detailed information about using all the supported components at http://www.oracle.com/webfolder/technetwork/jet/jetCookbook.html
The Component Contract
A UI component, whether shipped by Visual Builder, provided by a partner, or created by you, must follow the same component contract. This contract allows Visual Builder to expose the functionality of a component declaratively through the Visual Builder user interface. If you need to add functionality to a component, you can expand the capabilities of that component, and the new functionality is then expressed in that component’s interface.
The component contract has four aspects: properties, events, child slots, and methods.
Properties
A component has properties that you can bind to variables or expressions by means of the Visual Builder user interface. These properties can affect the state of a component (for example, the value of an input text field) or affect its rendering (for example, enabled or disabled). A component property has a specific type, which matches the types available for a variable, and may itself be structured or a collection. A property may also be required as part of the component interface.
In addition to a type, a component property may also have additional metadata (as defined in the JET design time metadata for properties), such as a display name or description.
There are two kinds of properties, one-way and two-way.
| Property Type | Description | Can Be Bound To |
|---|---|---|
| One-way (read-only) | The component reads the value of this property. If the expression that the property is bound to changes, the component will be notified of this change. | Expressions (which may contain variables) |
| Two-way (read/write) | The component can read the value of this property and can also write back to that property. If the variable is modified externally, the component will be notified of this change. | Variables |
Events
A component can fire zero or more events (for example, an onClick event for a button). Each event has a payload. The Visual Builder user interface allows the developer to listen for any of these events and to expose the event payload. An action chain can then process the event.
Child Slots
A slot is a placeholder inside a web component that you can fill with your own markup. A component can have zero or more slots that can hold one or more children. Any children not assigned to a specific slot are assigned to the default slot.
Methods
A component can have zero or more methods that can be called on the component to perform an action (for example, to flip a card). These methods may have parameters that are defined as part of the component interface. The Visual Builder user interface provides an action within an action chain that allows the user to call a component method and fill in the parameters using expressions.