Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Customizing sections and controls with JavaScript

Updated on December 13, 2022
Applicable to Theme Cosmos applications

You can extend the functionalities of your application by adding custom JavaScript to the source code of a non-autogenerated section or a custom control. For example, you can add JavaScript to a section to launch a client-side validation of a specific field when the section is rendered.

Caution: Pega does not provide support services and troubleshooting for custom JavaScript code, such as scripts that override the default application behavior.
Before you begin: Ensure that the section or control that you want to modify with custom JavaScript is non-autogenerated. For more information, see Creating non-autogenerated sections and Creating non-autogenerated custom controls.
  1. In Dev Studio, open a custom section or control that you want to modify.
  2. If the section is based on a template, in the section editor header, click convert to full section editor, and then confirm the conversion.
  3. On the HTML tab, in the text field, add your custom scripts in one of the following formats:
    • An inline JS script tag
    • A JS file
    • An HTML fragment
      Note: Use the <pega:include> JSP tag to run the HTML fragment that contains your custom script when the system runs the HTML rule of the section or control. You can use the <pega:include> JSP tag to incorporate HTML fragments, JS files, and other HTML rules into the HTML of your non-autogenerated section or custom control.

      For example, the following JSP tag inserts the MyValidate HTML fragment into the currently processed stream: <pega:include name='MyValidate' type='Rule-HTML-Fragment'></pega:include>.

    For example: This script validates input for a number control:
    /* Integer control: No dots allowed */
    function validateinput(e) {
      if ( && === "number") {
        if ("validationtype").indexOf("integer") > -1) {
          /* remove all non-number characters (i.e. dots) */
 =[^0-9]/g, '');
    document.addEventListener("input", validateinput);
  4. On the rule form, click Save.
  5. Create or open an autogenerated section to include your custom section or control.
    For more information, see Creating sections.
  6. On the Design tab, perform one of the following tasks to include your section or control in the main section:
    Embedding the non-autogenerated section
    1. Expand the Structural list.
    2. Drag the Embedded section onto the work area.
    3. In the Section include modal dialog box, in the Section field, select By name, and then provide the non-autogenerated section's name.
    Including the custom control
    1. Expand one of the lists with controls:
      • Data capture
      • Pickers
      • Actions
      • Data display
    2. Pick and drag any control onto the work area.
    3. Click the View properties icon of the control.
    4. In the Cell properties window, near the control name, click Change.
    5. In the Custom list, select Other.
    6. In the list next to the control name, search for or enter your custom control's name.
  7. Click Submit.
  8. On the section form, click Save.
  • Creating non-autogenerated sections

    Create non-autogenerated sections with custom scripts to supplement the standard Pega Platform JavaScript with extra functionalities. For example, you can add custom client-side validation scripts to your section.

  • Creating non-autogenerated custom controls

    Improve the look and feel of your UI by performing advanced styling and adding custom behaviors to non-autogenerated controls. For example, with custom controls that use third-party JavaScript libraries you can render a wide range of versatile components, such as widgets and graphs.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us