Oracle Jet offers a way in which you can add composite/custom components into the JET framework by making use of the web components library provided by browsers.
Why Use Composite Components
Utilizing composite components enables you to start to creating a more manageable, salable architecture in your project, but above all; it makes your code far cleaner. Instead of having hefty view model files for each one of your views, you can start abstracting logic away from the views and creating reusable code which can be reused across your application whilst making your view model files less confused and cluttered.
An example of this would be a search bar, let’s assume that you have a search bar which you wish to create some logic for to do the searching. You’ll also have to create the HTML and Sass/CSS to go with your search bar. Now let’s assume that your site needs change and suddenly the search bar is needed across maybe 2, 3. So you go ahead and find the search bar source code and copy all of the JS, HTML and Sass/CSS. If you can’t already see the problem with this on a large scale then I’ll give you this for free, it doesn’t work at scale and leads to unorganized bloated code bases.
All of JET’s custom components actually work off the same Web Components library, so it makes sense to follow suit and do the same right? Just be weary, just because you can make something into a component, doesn’t mean you should. Think carefully about when some code should become a component, I will be writing another article soon on this topic and will update once published.
Using The Component Generator
When creating components it can take quite a bit of effort and time setting them up alongside linking all the necessary files together. For this reason I have created a NPM module called ojet-comp which is a CLI (command line interface) tool which allows you to easily add components to your code base. The instructions of how to install and use ojet-comp can be found over at the NPM Repository.
The basic usage is as shown below:
Once this command has been run, it will run you through the tutorial and it will create all of the files that you need to get up and running. Important, make sure that you read all of the documentation regarding setting up your project to run with custom components, this has been detailed in the NPM Repository.
In-case you’ve got stuck, I have created a short tutorial which will run through setting up your project to work with web components and using the ojet-comp component.
Setting up your project
To get up and running, download and install the ojet-cli tool. We will use this to generate a project. Once the ojet-cli is installed, open up the command line and execute the following to create your jet application:
$: ojet create --template=navdrawer
To serve your application, execute the following command:
$: ojet serve
Your application will not display in browser and automatically refresh when you make any changes. Now it’s time to setup the project to add custom components.
Navigate to main.js in /src/js/main.js and add the following line to to the paths object in the require section:
WARNING: Make sure you do not already have a customElements defined, if you do, adding it twice will break your project
Next, install the ojet-comp module if you haven’t already. To do so, execute the following:
$: npm install ojet-comp -g
Then run the module from the root folder of the directory:
This will prompt a wizard which will walk you through creating your component:
Once the wizard is complete, your component is ready to use. Navigate to the view model that you wish to use this in, for this tutorial we will be using the dashboard view model. Add the
'jet-composites/component-name' to the define block of your view model like so:
The last thing to do is to insert the HTML tag to your project, open the dashboard.html file and add the new component you have created, in this case, we can called the component test.
Your page should live reload and render the new custom component to the page:
Customizing Your Component
This component is now ready to be customized and used at your will. The component created can be found at:
It will include the JS, HTML and CSS/Sass files needed to create your application.
A Note About Serving With Sass
If you are serving your project with sass, make sure that you have sass installed on your oracle project be sure to serve execute your ojet serve like so: