Last Updated Jan 2020 for JET 8
Once you get into any serious usage of JET Custom Components it becomes useful to understand the lifecycle of any component in some detail, this is particularly true if, for example, your components UI needs to be dynamically adjusted at runtime. Fortunately the lifecycle is simple to understand and work with, although, as we will see it has changed over time.
In the following table I outline all of the events and lifecycle methods that can be called, within your component viewModel, as a Custom Component is rendered in a view. Note that all of the methods mentioned are optional, you don't need to create them for the component to work (with the exception of the basic Constructor for the object of course).
Note that this table has been updated as of JET 8.0.0 and deprecated events and lifecycle methods have a strikethough and an explanation as to what to use instead
1 | Constructor called | The component viewModel constructor will be passed a context object (see below) |
---|---|---|
2 | activated lifecycle method executed | The activated lifecycle method is called and passed the standard context object. At the point in time that this method executes, the base component element will exist in the HTML DOM, however it will not yet have any child nodes1 so you cannot manipulate the UI at this stage. You can return a promise from this method which will delay the rest of the component initialisation until it is complete. |
The attached lifecycle method is called and passed the standard context object. At this phase, the view defined by the Composite Component bootstrap script will have been processed and the Composite Component element will now have child elements in the DOM that you can locate and manipulate if necessary. If you need to set up any viewModel values that will be used by knockout bindings in the generated view, this is your last chance to do so. Replaced by the connected method |
||
3 | connected lifecycle method executed | The connected lifecycle method is called and passed the standard context object. At this phase, the view defined by the Composite Component bootstrap script will have been processed and the Composite Component element will now have child elements in the DOM that you can locate and manipulate if necessary. If you need to set up any viewModel values that will be used by knockout bindings in the generated view, this is your last chance to do so. Unlike the deprecated attached method, this method is called every time that the element is connected to the DOM, not just the first time |
4 | bindingsApplied lifecycle method executed | The bindingsApplied lifecycle method is called and passed the standard context object. At this phase, the Knockout applyBindings has been called on the subtree and any data-bind or other Knockout directives will have been applied. Thus it would be too late to change a DOM element to add a data-bind at this stage. |
|
||
5 | disconnected lifecycle method executed | The disconnected lifecycle method is called with a reference to the Composite element object every time the component is detached from the browser DOM. This gives you the opportunity to do clean up if required (esp. any listeners that the component may have registered). |
As well as these lifecycle methods and events, you can also receive property-changed events throughout the lifetime of the component via the propertyChanged() callback that we covered in Article IV.
As shown above, most of the lifecycle objects (except disconnected), as well as the viewModel constructor are passed a common context object. This object contains the following properties:
The connected and disconnected events are slightly special in two ways:
First of all they are paired, in that for each connected call you will also at some point get a disconnected call. This is useful if you need to do something such as add a listener to the document as a whole; you can add it on connected and then remove it to clean up again in disconnected.
Secondly, these methods may be called multiple times throughout the lifespan of a component instance, all depending on where the component is and how it is being used. (For example if the component was in a pop-up dialog). Be aware of this and take care that you do not carry out any expensive operations in either of these lifecycle callbacks.
In versions of JET prior to 3.0 it is possible to override the lifecycle function names used by the lifecycle callbacks (bindingsApplied, activate and so forth). This was accomplished by updating the defaults property of oj.Composite. This feature has been deprecated and should not be used, changing these values would make your CCAs incompatible with every other application that does not use the same names which defeats the whole object of a component standard. It goes without saying that you should not use this capability.
This article is covers the basic custom component lifecycle. There are two related further topics that will be discussed in later articles in this series:
In this article we encountered the slotCount property of the lifecycle context object. Therefore it makes sense to take a look next at very powerful feature of the Web Components / Composite Component Architecture - slotting.
If you've just arrived at JET Custom Components and would like to learn more, then you can access the whole series of articles on the topic from the Custom JET Component Learning Path