Technical Articles relating to Oracle Development Tools and Frameworks

  • JET
    September 28, 2017

JET Custom Components Changes in JET 4.0

Duncan Mills

With the JET 4.0 release you'll be glad to see that we have unification between the world of your custom components and the JET components themselves.  Both are now "Web Components"-like and use the same syntax for basic operations such as binding to observables (using the [[...]] and {{...}} notation) and executing component methods.  As well as making your page source more concise, this is going to be much more maintainable too.  

There are many great topics to cover in JET 4.0 but for now, focusing on custom components specifically, there are a couple of important things to talk about; component standards and new JET Command Line Interface (CLI).

Components and the CLI

With this release, realizing the importance of composite components, we're made it really easy for you to create them.  Now, rather than having to write each of the component artefacts from scratch and put them in the right place you can have all the hard work done for you with a single command issued from the CLI. 

In order for this to work, you need to first install the JET CLI of course. If you've not done that yet then do so now:

(sudo) npm install -g @oracle/ojet-cli

To create a component, just navigate to the root of your JET project and issue the new create component command (let's assume a component name of "my-component"). So from a standing start you might do this:

ojet create myjet4project --template=basic
cd myjet4project
ojet create component my-component

And that's it! If you now go and look inside the /src/js directory of your project you'll see a new folder jet-composites and a folder with the same name as the component under that. You'll also see a tests directory has been created:


So as you can see from the generated contents above you have a great starting point to build up your component from. Note that in a future article I'll cover writing tests for your components in detail.

It's key to notice here as well, that the new component is generated into a folder called jet-composites. That leads us nicely into the topic of standards

Component Standardisation

Although I covered some basic standards back in Part II of the Learning Path, it's now becoming more and more important to follow certain rules to ensure maximum compatibility now and for the future.

Component Location

As we've seen, the CLI generates the artefacts for a new component into a sub-directory under the jet-composites folder which in turn is in the src/js root. There is no option to have the CLI put the files anywhere else, and this was a deliberate decision on our part. The point here relates to the component ecosystem as a whole. Once you get into scenarios of sharing and re-using components you'll soon descend into chaos if every producer and consumer are just using random conventions in filesystem layout. It becomes very difficult for cross component references and generally makes the consumption of components that much harder.

Now, it would be possible to put some complex configuration step into our applications to try and normalise all the different ways in which components are structured and loaded, but frankly a simple convention is a much easier approach to take. Therefore, here's the convention that we'll be using within Oracle and I strongly recommend that you adopt too: Jet Composite components live in a flat directory structure under src/js/jet-composites. In a future article I'll discuss some alternate patterns based on storing components on a CDN, but for now, follow this convention for maximum compatibiltiy.

Component Naming

I have previously discussed the naming rules for composite components, specifically the requirement to include a hyphen as well as following the other W3C rules on WebComponent naming. These rules are not optional! However, we also need to talk about namespacing. Because we have a pattern of all components living as peer directories under the jet-composites/ root, there is obviously a danger of different developers coming up with the same name. We need to avoid this.

Again this is a problem best solved by convention over configuration, it's just made a little more cumbersome by the fact that we don't have a nice package mechanism such as the one available in Java. The standard that I'd recommend therefore is to simply define the first segment of your component name (the bit before the first hyphen) to be a suitable organisation identifier. For example you work for ACME inc. and want to create a coyote tracking component, then naturally your component name would be <acme-coyote-tracker>.

Attribute Naming

Again, although I've mentioned it before I want to stress that your components should not redefine any of the global HTML attributes as custom properties. This is key in JET 4.0 where we've tightened up the checking and you may find that your components cease to work if you have.

Here's the list of attributes you should not re-define:

  • aria-*
  • accesskey
  • class
  • contenteditable 
  • contextmenu
  • dir
  • draggable
  • dropzone
  • hidden
  • id
  • lang
  • spellcheck
  • style
  • tabindex
  • title
  • translate

These attributes can still be applied to your component by your consumers when they use your element tag, and you will be able to obtain the values that are supplied from the composite element passed in the context to your constructor and lifecycle methods. What you can't do is to define these as properties of your own in the component.json, doing so may lead to hard to diagnose errors - you have been warned.

As well as the attributes above you should not re-define any of the global on* events either. For the full list, head over here

Future Content

If you simply can do without your regular dose of JET CCA goodness then never fear, I have a couple of articles in the pipeline including the important topic of unit testing your components.  However, feel free to comment below is there is a component based topic that you'd like to see discussed in detail. 

CCA Series

If you've just arrived at JET composite components and would like to learn more, then you can access the whole series of articles on the topic from the Composite Component Architecture Learning Path

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.