Creating custom controls

Inline style is added to the DOM for every instance of the control inserted inside the document. The best practice is to move your CSS selector to a separate rule file text attached to the skin rule as additional styles.

The benefits include:

• CSS minification
• CSS validation and linting
• Support for RTL
• Easier to maintain
• Support for CSS mixin variables
• Only included once

Inline JavaScript inserted into a custom control is difficult to maintain. The best practice is to move the JavaScript code to a separate rule file text. 

The benefits include:

• JavaScript minification
• JavaScript validation and linting
• Easier maintenance

If the custom control is used in several pages, the recommendation is to load the JavaScript file during the initial portal load by attaching it to the portal harness.

If the custom control is used infrequently, a better approach is to lazy-load the JavaScript file by using the JSP tags <pega:onlyonce> and <pega:static>.

<pega:onlyonce name="pega_ui_react">
<pega:static type="script" app="webwb">
  <pega:bundle name="pzpega_ui_react" />
</pega:static>
</pega:onlyonce>

<!-- only include this component once per page -->
<pega:onlyonce name="pyReactAutocomplete">
<pega:static type="script" app="webwb">
   <pega:file name="py_react_autocomplete.js"/>
   <pega:file name="py_react_autocomplete_ctl.js"/>
</pega:static>

If you need to initialize the custom control or change the behavior of this control on load, it is not possible to rely on the DOMContentLoaded or load events.

When using a single page dynamic container, these events are fired only once when this initial portal is loaded. The events do not fire if the custom control is lazy-loaded or visible when a When condition changes through a refresh section.

When writing a custom control, it is important to correctly handle actions, such as refresh sections, and to correctly release any event listeners when the custom control is no longer in the DOM.

Relying on global event listeners and event bubbling to the body of the document will reduce JavaScript memory leaks.