Overview
IMPORTANT: While Oracle CPQ does not endorse or guarantee the use of JavaScript customizations, we recognize that some customers have extended the Oracle CPQ. To support critical use cases, JavaScript API ("CPQJS") includes methods for accessing attributes, actions, and other elements on the JET Configuration and JET Transaction UIs. Customers should consider carefully the relative benefits of JavaScript customizations in light of the associated risks. Customizations may conflict with new Oracle CPQ platform features, data may be corrupted or lost, maintenance and support may be difficult, cross-browser support must be verified, performance may be impaired, and testing is required for each upgrade.
Many of the most commonly customized features are now available in Oracle CPQ and no longer require custom JavaScript. Sticky headers, column freezing, responsiveness, and filtering of line items are now supported by the Oracle CPQ JET UI. Hiding of Actions and Transaction Arrays (in Release 18D JET Transaction UI) are also now available. Customers should remove all JS associated with these features when implementing the new JET Transaction and Configuration UI. In upcoming releases additional features that previously required JS customization will be available with platform-support.
The new JET UI first introduced in Release 18C supports customization of the UI using JS and CSS, but with some differences in structure and approach. Customers with JavaScript customizations to their transaction UI may experience conflicts when the new JET UI is enabled due to these differences. Customizations can be refactored to address these differences. However, customers should consider carefully the relative benefits of JavaScript customizations in light of the associated risks. Customizations may conflict with new Oracle CPQ platform features, data may be corrupted or lost, maintenance and support may be difficult, cross-browser support must be verified, performance may be impaired, and testing is required for each upgrade.
This document explains the key structural differences vs. CPQ's Legacy UI, and reviews the new methods provided in Release 19C that enable JavaScript to access elements of the JET UIs.
For details on styling of JET UIs using CSS, see Oracle CPQ JET CSS: Branding and Styling (Doc ID 2462711.1).
Differences between Legacy and JET UI JavaScript Customization
In CPQ's Legacy UI, JavaScript customizations of Commerce UIs are commonly implemented in several ways:
- Modifications to the Oracle CPQ JavaScript Framework files (bm-framework.js, commerce.js, config.js)
- Inclusion of JavaScript in an HTML attribute
- JavaScript added to the Header or Footer
Modifications to Oracle CPQ JavaScript Framework files will require refactoring because these files are no longer loaded in the JET UI.With JET single, combined and minified files (transactionMain.js and configMain.js) are loaded which can be inspected using web development tools such as Firefox and Chrome Developer tools, but cannot be directly modified and should not be referenced in custom JavaScript.
Previous customizations to the Oracle CPQ JavaScript Framework will need to be re-implemented in either an HTML attribute or in the site Header/Footer.
Inclusion of JavaScript in an HTML attribute or addition to the site Footer will continue to work with the JET UI, but may require syntactic revision. JavaScript in the site Header will work only under certain circumstances, as detailed below. For this reason, inclusion in an HTML attribute or in the site Footer will provide a more reliable approach.
When implementing JavaScript in an HTML attribute, best practice is to store the script in File Manager and reference this in the HTML attribute directly or in a default BML function for the HTML attribute. This simplifies discovery and search for JavaScript implemented on a site.
The HTML and DOM (Document Object Model) for the JET UI differ from the Legacy Commerce and Configuration UIs. JET also differs from the Legacy UI in the JS functions or methods available. JavaScript customizations may need to be refactored to reflect these differences. Developers working on JET UI customizations should familiarize themselves with the differences between the Legacy and JET UI DOM structures.
Rather than IDs, the JET UI DOM uses variable names for references, and all components are prefaced by ‘oj'.
The JET UI architecture in Oracle CPQ uses a client-side data model, REST to communicate with the server, and JavaScript to render UI components. Manipulating data or calling actions via the UI components can introduce data inconsistency and timing problems that could break functionality. Instead, the CPQJS API introduced in Oracle CPQ Release 19C provides direct access to the data and methods, including access to hidden attributes not previously accessible in the JET DOM.
For improved performance, UI components are only rendered when the user opens the containing panel or tab. However, values can be set or retrieved even for non-rendered attributes using the CPQJS API.
Administrators may access these methods using custom JavaScript contained in a separate file or in a read-only HTML attribute. Reference the methods with the namespace "CPQJS" as in the examples below.
CPQJS.setAttributeVal('myAttributeVarName','New Value');
CPQJS.onTableLoaded('lineItemGrid', setRowColors);
Important Considerations:
- Be aware of timing.
- Use
setTimeoutto defer a script until current threads are completed or use theCPQJSReadyfunction. - To run scripts after the layout is fully loaded, call scripts from an HTML attribute that appears on the layout. This must be on a panel/tab that is visible by default. Scripts in the footer can be called earlier through the use of the
CPQJSReadfunction. - Avoid overuse of JavaScript, as it can affect performance.
- Enlist an experienced JavaScript developer to implement customizations on the JET UIs.
|
Method |
Arguments |
Notes |
|---|---|---|
|
actionExists |
varName |
Returns true if action exists |
|
attributeExists |
varName |
Returns true if attribute exists |
|
getAttributeVal |
varName, index |
Gets the specified attribute value |
|
isConfig |
Returns true if Configuration page |
|
|
isJet |
Returns true if JET page |
|
|
onActionComplete |
varName, handler |
Calls a function when an action completes (use function name without parentheses) Handler will receive an object with:
|
|
onAttributeChange
|
varName, handler |
Calls a function on attribute change (use function name without parentheses) Handler will receive an object with:
|
|
openPopup |
content, title |
Opens a popup with specified content and title |
|
performAction |
varName |
Calls an action |
|
setAttributeState |
varName {state: value} |
Notes:
|
|
setAttributeVal |
varName, value, [index] |
Sets the specified attribute value |
|
Method |
Arguments |
Notes |
|---|---|---|
|
actionExists |
varName |
Returns true if action exists |
|
attributeExists |
varName |
Returns true if attribute exists |
|
getAttributeVal |
varName, [index] |
Gets the specified attribute value |
|
getTableInfo |
varName |
Returns the following info:
Example: CPQJS.getTableInfo('lineItemGrid') Returns an object containing the listed values, including an array of row keys and indexes of selected rows Note: Beginning in 20B, the selection syntax for the Line Item Grid has changed (arrays stay the same).
Customers using getTableInfo should re-test the functionality, and may need to refactor their custom JavaScript. |
|
isCommerce |
Returns true if Commerce page |
|
|
isJet |
Returns true if JET page |
|
|
onActionComplete |
varName, handler |
Calls a function when an action completes (use function name without parentheses) Handler will receive an object with:
|
|
onAttributeChange |
varName, handler |
Calls a function on attribute change (use function name without parentheses) Handler will receive an object with:
|
|
onTableLoaded |
varName, handler |
Calls a function when the specified table is loaded (use 'lineItemGrid' for the transaction LIG). Handler receives an object with {varName} This will be triggered each time the table is loaded, which can happen repeatedly (during filtering, for example). Ensure functions are lightweight and idempotent (can safely run repeatedly). |
|
openPopup |
content, title |
Opens a popup with specified content and title |
|
performAction |
varName |
Calls an action |
|
setAttributeState |
varName {state: value} |
Notes:
|
|
setAttributeVal |
varName, value, [index] |
Sets the specified attribute value |
|
tableExists |
id |
Returns true if table exists |
UI components are rendered progressively after the DOM Ready event has been fired. Because of this, scripting may need to be called after elements are rendered, or deferred using setTimeout.
In a used case where custom embedded charts or analytics are implemented in the JET UI using JavaScript as part of an HTML attribute, the analytic may depend on the values of other attributes. setTimeout may be needed to ensure the values are loaded before processing values to generate the HTML attribute.
The following JavaScript can be added to an existing script to delay running the function by a specified amount of time (1 millisecond in the example below).
<script>
setTimeout(function(){
REPLACE WITH PRE-EXISTING SCRIPT
},1);
</script>
Custom JavaScript in the Oracle CPQ Header and Footer
JavaScript or custom HTML may be inserted into the HEAD, Header HTML or Footer HTML via the Oracle CPQ Admin ‘Header & Footer' page. The latter two are also referred to as ‘Custom Header’ and ‘Custom Footer’. However, depending on both the UI (JET versus Legacy) and the Navigation (ALTA versus Legacy) these customizations may not work, as shown below. Insertion in the Custom Footer is the recommended approach as these customizations will be applied in all circumstances. Use the CPQJSReady function to affect the timing if needed.
|
UI |
Navigation |
HTML Head |
Header HTML |
Footer HTML |
|---|---|---|---|---|
|
Legacy UI |
Legacy Navigation |
Included |
Included |
Included |
|
Legacy UI |
Alta Navigation |
Included |
Not included |
Included |
|
JET UI |
Legacy Navigation |
Not included |
Included |
Included |
|
JET UI |
Alta Navigation |
Not included |
Not included |
Included |
Beginning in Oracle CPQ Update 21B, the CPQJSReady function can be used as an alternative to setTimeout. This allows scripts to be placed in the footer, instead of forcing the use of an HTML attribute or using setTimeout.
For Example:
window.CPQJSReady && CPQJSReady(function() {
// Initialize JS
});
Enable Right-to-Left (RTL) for the JET Transaction or Configuration Layouts
To enable right-to-left (RTL) for the JET transaction or configuration layouts, customers can add this script to the page via the header or footer. This will work when the user's language is set to Hebrew or Arabic.
<script type="text/javascript">
//if user lang is Hebrew or Arabic, set HTML dir to RTL if not already set
if (document.getElementsByTagName("HTML")[0].getAttribute("dir")==null)
{ var _BM_LAYOUT_DIR = ( _BM_USER_LANGUAGE == "iw_IL" || _BM_USER_LANGUAGE == "ar_SA" ) ? "rtl":"ltr";
document.getElementsByTagName("HTML")[0].setAttribute("dir", _BM_LAYOUT_DIR); }
</script>
Coexistence of JET with Legacy Configuration or Transaction UI
Especially during development and testing, customers may wish to display JET Configuration or Transaction UI to some users while displaying the Legacy UI to other users. Conditional logic may need to be added to existing JavaScript to render each UI properly.
Notes
For additional information, refer to the following documents:
