Skip to main content

Creating custom controls

Avoiding inline style

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

Avoiding inline JavaScript

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" />

<!-- 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"/>
Note: Writing JavaScript core directly into the UserWorkform HTML fragment is not best practice and increases maintenance cost.

Avoiding reliance on document loaded events

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.

Check your knowledge with the following interaction.

If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice