The jQuery-UI widget provides the ability for the Site designer to add support for jQuery-UI to a Percussion Site, and to have fine control over the version of jQuery-UI that is used on the published website. This is the recommended technique for adding jQuery-UI to a Site. When Percussion's templating engine sees the jQuery-UI widget on a template or page, the page will be rendered based on the settings configured in the layout properties of the widget.
UPDATING EXISTING SITES TO USE THE JQUERY-UI WIDGET
- For each Site, review the Site Metadata, specifically the 'Additional Head,' 'After Body Start,' and 'Before Body Close' sections. Remove any jQuery-ui references found here.
- In the Layout Tab of the Site, drag a jQuery-ui widget onto the Template.
- Click the Wrench to edit the Layout properties of the widget.
- Specify the version of jQuery-ui that you want the template to use.
- Save the Site.
- Preview a Page that uses the Site, verify that there are no JavaScript errors.
- Correct any JavaScript errors.
- Repeat for all active templates.
- Perform a Full Publish, verify the published website.
LAYOUT PROPERTIES
| Property Name | Default Value | Description |
| jQuery-UI location | Preview/Editor: /cm/jslib/jquery-ui.js Publish: /web_resources/cm/jslib/jquery-ui.js | The location to the jQuery script, should be an absolute published CDN link. https://code.jquery.com/jquery-3.4.1.min.js for example. NOTE that if this link is broken at publish time, the system will provide the out of the box jQuery-UI. |
| jQuery-ui SRI Hash | When using an external script reference to jQuery-UI hosted on a CDN. Update this with the integrity attribute provided in the CDN link. | |
| : | When using an external script reference to jQuery-ui hosted on a CDN. Update this with the crossorigin attribute provided in the CDN link. | |
| No | Yes / No. If yes, the defer attribute will be added to the script tags generated by this widget. When deferring jQuery-ui make sure that any inline or 3rd party scripts that use jQuery-ui are also deferred. | |
| Head | Where in the DOM of the published page should the scripts be injected. Head, After Body Open, or Before Body. jQuery-ui will always be injected before other widgets. When adding to Before Body Close, make sure that inline scripts are wrapped in a DOM ContentLoaded event handler. | |
| Yes | If Yes, the version of jQuery-ui referenced by this Widget will be used on any Pages or Templates that contain the Widget. If No, the out of the box Percussion jQuery-ui version will be used. Can be used to validate the jQuery-ui widget with Preview on existing templates. The jQuery-ui change won't be published until this property is set to Yes. |
UNDERSTANDING PLACEMENT LOCATION
As a framework, the location that jQuery-ui is loaded in a Page can have an impact on other JavaScript plugins or code that depends on jQuery-ui to be initialized in order for that code to run.
WEB RESOURCES ALTERNATIVE
The default jQuery published by Percussion is in the web_resources/cm/jslib/jquery-ui.js file on the Percussion CMS server. As an alternative to the jQuery-ui Widget for designers who are confident that all templates will work with the new jQuery-ui version, this file can be replaced with the desired jQuery-ui version. This avoids the need for multiple versions of jQuery-ui in a sites templates, and on Full Publish all Pages will be updated to the new jQuery-ui version. For designers who prefer a more careful Template by Template approach the jQuery-ui widget would be the better option.
JQUERY-UI CDN LINK VALIDATION
The system contains a validation at publish / preview time on the CDN link. If the system detects that the link is down or broken, the default system jQuery-UI version will be used. This is to help prevent typos in the CDN Link in the Layout properties from accidentally breaking the published website.
If the protocol used in the link to the CDN is https this means that the Percussion server must be able to access the CDN link via HTTPS from the Percussion server at publish time. In environments where outbound http/https access is restricted by firewall rules, a firewall rule would need to be created that whitelists the CDN link. Otherwise link validation will fail, and the system jQuery will be used instead.