Creating a simple Oracle JET VComponent

Introduction

Oracle JavaScript Extension Toolkit (Oracle JET) simplifies the process of building modern web applications through its comprehensive set of open-source JavaScript libraries. A major feature of Oracle JET is the use of VComponents, which enable developers to create modular, maintainable, and high-performance applications using the Virtual DOM (VDOM) architecture. In this blog post, I will walk you through the process of creating a VComponent in Oracle JET step by step.

Prerequisites

Before you start creating a VComponent in Oracle JET, ensure that you have the following tools and resources:

1. Node.js and npm (Node Package Manager) installed on your development machine.
2. Oracle JET CLI (Command Line Interface) installed globally using the command: npm install -g @oracle/ojet-cli
3. An Oracle JET application created using the command: npx @oracle/ojet-cli create componentDemo --template=basic --vdom

Step 1: Create a new VComponent

npx @oracle/ojet-cli create component demo-component 

This command will generate a new VComponent named ‘demo-component‘ with the necessary files, including a TypeScript file (demo-component.tsx) and a CSS file (demo-component-styles.css).

Step 2: Define the VComponent’s structure and appearance

Open the demo-component.tsx file, and you’ll find a basic structure for your VComponent. You can now define the component’s structure and appearance using JSX syntax. For example, you can create a simple counter component.

import { customElement, ExtendGlobalProps } from "ojs/ojvcomponent";
import { h, Component, ComponentChild } from "preact";
import componentStrings = require("ojL10n!./resources/nls/demo-component-strings");
import "css!./demo-component-styles.css";

type Props = {
  initialValue?: number;
  value?: number;
  incrementBy: number;
};

type State = {
  counter: number;
}

/**
 * 
 * @ojmetadata version "1.0.0"
 * @ojmetadata displayName "A user friendly, translatable name of the component"
 * @ojmetadata description "A translatable high-level description for the component"
*/

@customElement("demo-component")
export class DemoComponent extends Component < ExtendGlobalProps < Props >, State> {
 
  static defaultProps: Partial < Props > = {
    initialValue:0,
    value:null,
    incrementBy: 1
};

private _increment = () => {
  this.setState({
    counter: this.state.counter + this.props.incrementBy
  });
};

private _decrement = () => {
  this.setState({
    counter: this.state.counter - this.props.incrementBy
  });
};

private _reset = () => {
  this.setState({
    counter: this.props.initialValue
  });
}

private getValue(){

  let currentValue;
  if(this.state.counter===undefined){
    this.setState({
    counter: this.props.initialValue
  })}
  currentValue = this.state.counter;
  return currentValue;
}

render(props: Props, state: State): ComponentChild {
  const current = this.getValue();
  return (
    <div>
      <button class="red" onClick={this._decrement}>-</button>
      <>{current}</>
      <button class="green" onClick={this._increment}>+</button>
      <button onClick={this._reset}>reset</button>

    </div>
  );  }
}

In this example, we define a simple counter VComponent with two buttons for incrementing and decrementing the count. We also define a Props interface to define the initial count value and a State interface to manage the component’s state.

Step 3: Style the VComponent

Open the demo-component-styles.css file to apply custom styling to your VComponent. For instance, you can add the following CSS rules to style the counter component:

button {
  background-color: #007bff;
  color: white;
  border: none;
  padding: 8px 16px;
  margin: 0 8px;
  cursor: pointer;
}

button.red {
  background-color: red;
  
}
button.green {
  background-color: green;
  
}

Step 4: Use the VComponent in your application

To use your newly created VComponent, open the TypeScript file of the view where you want to include it, such as src/ts/views/dashboard.tsx. First, import the VComponent:

import { DemoComponent } from 'demo-component/loader'

Next, include the VComponent within the render method of the view by adding the custom JSX element. Remember to pass the required properties. In our example, we need to pass the initialValue, and the incrementBy prop to the demo-component:

import { h, Component } from "preact";
import { customElement, GlobalProps } from 'ojs/ojvcomponent';
import { DemoComponent } from 'demo-component/loader'
export function Content() {
  return (
    <div class="oj-web-applayout-max-width oj-web-applayout-content">
        <DemoComponent initialValue={11} incrementBy={1}/>
    </div>
  );
};

Step 5: Run and test the application

Now that you have created and included the VComponent in your application, it’s time to run and test it. In your terminal, navigate to your Oracle JET application’s root folder and execute the following command: ojet serve

The application will open in your default web browser. Navigate to the view where you included the demo-component, and you should see the counter VComponent with its buttons functioning as expected.

Conclusion

Creating a VComponent in Oracle JET is a straightforward process that allows developers to leverage the benefits of the Virtual DOM architecture, resulting in improved performance and maintainability of web applications. By following these steps, you can create your own custom VComponents to build complex and efficient web applications with Oracle JET.