Table of Contents

Article

Upgrading an application to render in HTML5 Document Type

Applications built in Pega 7 are rendered in the HTML5 Document Type (standards mode) by default. This ensures cross-browser and cross-platform compatibility and use of the latest HTML markup.

Pega 7 includes a number of features that are available only to applications rendered in HTML5 Document Type (standards mode).

This article describes why and how to upgrade your pre Pega 7 application to render in HTML5 Document Type (standards mode). It provides an overview of the upgrade process and includes links to detailed information.

About HTML5 Document Type (standards mode)

Upgrading applications to render the user interface using the HTML5 Document Type:

  • ensures compatibility across browsers, including mobile browsers
  • enables the browser to control the behavior of many UI components
  • reduces the need for complex Java script 
  • provides advanced semantics and markup, including input types for date, color, and range pickers, pattern matching, validation, etc.
  • improves performance
  • offers CSS3 styling options

Rendering your application in HTML5 Document Type also ensures that you can take advantage of all of the new features in Pega 7. This includes responsive, contemporary layouts that separate content from presentation and a powerful skin that enables you to style your application with ease and efficiency.

Overview of rendering an existing application in HTML 5 Document Type (standards mode)

If your pre Pega 7 application is guardrail compliant:

  • select Include HTML5 document type on the Definition tab of the Application rule to render the application in HTML5 Document Type

If your pre Pega 7 application is not guardrail compliant:

  • Select DesignerStudio > User Interface >HTML5 Application Readiness. Use this landing page, in conjunction with this document to guide you through the process of upgrading settings, if necessary, for:

Upgrade the Application settings

  1. AccessDesigner Studio >User Interface >HTML5 Application Readiness.
  2. Select the Applications tab. By default, the HTML5 Document Type setting for the current application displays.To select additional applications in the default application stack, click the Application link, select the application, and then click Apply.
  3. For each application, if the HTML5 Document Type setting is disabled, click the application name link to open the Application rule.
  4. On the Definition tab of the Application rule, select the Include HTML 5 document type checkbox in the UI Settings area.
  5. Click Save. If your pre Pega 7 application is guardrail compliant, it now renders in HTML5 Document Type. If the application is not guardrail compliant, upgrade the necessary harnesses and UI elements, as described below.

Upgrade Harnesses

The Harnesses tab of the HTML5 Application Readiness page lists harnesses that use a Document Type of None (quirks mode) and harnesses with custom CSS or JavaScript. To render your application user interface using the HTML5 Document Type, upgrade the harnesses listed here.

This section provides an overview of upgrade steps. 

Change the Document Type setting for the harness

The Document Type setting on the harness overrides the HTML5 Document Type setting in the Application rule. Harnesses with a Document Type of None (quirks mode) render in quirks mode.

For the harnesses listed in the Harnesses not configured to render in HTML5 Document Type area, set the Document Type to HTML5 (standards mode) or Inherit from applicationrule.

As a best practice, set the Document Type to Inherit from application rule. The harness will render using the Application rule UI Settings, in this case, HTML5 Document Type.

  1. On the HTML5 Application Readiness page, select the Harnesses tab.
  2. In the Harnesses not configured to render in HTML5 Document Type area, click the Harness Name.
  3. Select the Advanced tab and change the Document Type from None (quirks mode) to one of the following:
    • Inherit from application rule: this harnesses renders using the Document Type set on the Advanced tab of the Application rule, in this case HTML5 Document Type (standards mode).
    • HTML 5 (standards mode): this harness renders in standards mode, regardless of the Document Type set in the Application rule
  4. Save the harness.

Upgrade harnesses containing custom JavaScript

As a best practice, avoid supplementing or overriding the JavaScript that supports the harness form.

The following is an overview of the steps you may take to upgrade a harness containing custom JavaScript. 

To upgrade harnesses that contain custom JavaScript:

  1. On the HTML5 Application Readiness page, select the Harnesses tab.
  2. In the Harnesses with custom CSS and custom JavaScript area, click the Harness Name to open the harness.
  3. To view the custom JavaScript or CSS, select the Scripts and Styles tab.
  4. Click in the Name field and then click  to open the text file rule.
  5. Update the harness to remove custom JavaScript. For example, instead of using JavaScript to handle events, use an auto-generated control configured with events and actions. For an example of a control that performs multiple actions, see How to use the AutoComplete control to build a list (6.2 SP2).

Upgrade harnesses with custom CSS

As a best practice, do not include hand-coded CSS in the harness. Instead, define multiple formats  and custom styles in the application skin and reference them in the harness. This enables reuse and cascading change throughout your application skin.

The following is an overview of the steps you may take to upgrade a harness containing custom CSS. 

  1. On the HTML5 Application Readiness page, select the Harnesses tab.
  2. In the Harnesses with custom CSS and custom JavaScript area, click the Harness Name to open the harness.
    In the harness, select the Scripts and Styles tab and then click Open Rule to open the custom stylesheet.
  3. Review the custom stylesheet, noting styles for which you can create multiple formats and those that require a custom format in the skin.
  4. Open and modify the skin.
  5. Update the harness to reference newly defined formats and custom styles.
  6. Save and test the harness.

Upgrade UI Elements

On the HTML5 Application Readiness page, select the UI Elements tab and upgrade sections, controls, properties, and flow actions to render in HTML5 Document Type.

Non-Auto-Generated sections

  1. In the Non-Auto-Generated sections area, select the name of the section.

     
  2. Select the HTML tab, and then select the Auto-Generated HTML checkbox.
  3. Save the section.

Sections using deprecated controls

  1. In the Sections using deprecated controls area, select the name of the section to open the section.

     
  2. In the section, click the Update Controls button to automatically update deprecated controls in the section simultaneously. A number of controls are included in the automatic update. See Upgrading deprecated and outdated controls for a complete list.

    You can include additional controls in the automatic update. See Adding controls to the automatic Update Controls feature in Upgrading deprecated and outdated controls.
  3. Save the upgraded section.
     

If an automatic upgrade is not available for a control, such as List-to-List or DataGrid, you can manually update the section to use auto-generated controls. For details, see Upgrading deprecated controls to use auto-generated controls.

If you import a pre Pega 7 Product rule, a RAP (Rule-Admin-Product rule), into Pega 7, you must revalidate and save all sections contained in the RuleSet. Sections containing deprecated controls will not display in the HTML5 Application Readiness page until you revalidate and save. To do this, select DesignerStudio > SystemTools > Validate > Revalidateand Save.

 

Properties referencing deprecated controls

Update properties that reference deprecated controls to reference auto-generated controls instead.

See Upgrading properties that reference deprecated controls to use auto-generated controls for more information.

  1. In the Properties referencing deprecated controls area, select the name of the property to open the property.
  2. On the General tab, replace deprecated controls with auto-generated controls. For example, if the property references the non-auto-generated TextArea Control, replace it with the auto-generated pxTextArea control.

  3. Save the property.

For more information, see, Upgrading properties that reference deprecated controls to use auto-generated controls.

Flow actions referencing HTML rule

Open flow actions that reference an HTML rule to define their presentation and update the flow actions to reference section rules to determine their presentation instead. Referencing section rules is the default for PRPC 6.1 and later.

  1. In the Flow Actions referencing HTML rule area of the UI Elements tab, click the name of the flow action to open the flow action rule.
  2. Select the HTML tab, and then click beside the HTML Reference field to open the HTML rule.
  3. Convert the HTML into an auto-generated section and then save the section.
  4. Drag the section to the Layout tab of the Flow Action.
  5. On the HTML tab, change the HTML Generation to Reference Section.
  6. Save and test the updated flow action.

Sections using inline styles

Inline styles may cause display issues when rendered in HTML 5 Document Type. As a best practice, replace inline styles with styles available in the skin. You can add formats and define custom styles in the skin. See Displaying a modal dialog in a custom format created in the skin and the PRPC Help for more information.

  1. In the Sections using inline styles area of the UI Elements tab, click the name of the section containing inline styles to open the section. A warning displays in the section:
  2. Locate the element using the inline style, and then click the magnifying glass to open the Properties panel and examine the inline style definition.
  3. Open the skin; seeDetermining which skin an application is using.
  4. Determine if the style that will replace the inline style exists in the skin. If the style does not exist in the skin, you can create an additional format or a define custom style in the skin.
  5. Save the skin, and then apply the new format or style to the UI element.

See Displaying a modal dialog in a custom format created in the skin and the PRPC Help for more information.

Refresh and Test

  1. Click Actions > Refresh in the upper right to refresh the form and ensure that you have completed all of the upgrades.
  2. If you are testing in Internet Explorer, verify that Compatibility View is disabled. To do this, open the Internet Explorer tools menu, access Compatibility View Settings, and clear the Display all websites in sites in Compatibility View and Display intranet sites in Compatibility View checkboxes.

Consider that the implementation and CSS classes for elements may differ, depending upon whether the application is rendered in HTML5 Document Type - standards mode or in quirks mode.

For example, in HTML5 Document Type – standards mode, modal dialogs honor the design time width of the layout, while, in quirks mode, modal dialogs shrink to the minimum width and height possible. Drag and drop is not supported in modal dialogs rendered in standards mode. If your application contains modal dialogs and is rendered in both standards and quirks modes, generate test cases for each.

Additional Information

Upgrading deprecated and outdated controls

Upgrading properties that reference deprecated controls

Upgrading Work Area controls to Dynamic Containers

Published October 7, 2013 — Updated February 10, 2016


100% found this useful

Have a question? Get answers now.

Visit the Pega Support Community to ask questions, engage in discussions, and help others.