2Overview of the JavaScript API
Overview of the JavaScript API
This chapter provides an overview of the public JavaScript application programming interface (API) available with Oracle CRM On Demand. It contains the following topics:
Overview of Customizing Buttons
You can use the methods of the JavaScript API to customize buttons in the Oracle CRM On Demand UI as follows:
To create custom buttons
To hide and show buttons
To disable and enable buttons
To change the look and feel of preconfigured and custom buttons
To change the behavior of preconfigured and custom buttons
To add tooltips for preconfigured and custom buttons
More information about the various ways in which you can customize buttons is given in the following topics. For information about the types of pages on which you can customize buttons, see Contexts in Which You Can Customize Buttons.
Creating Custom Buttons
The JavaScript API provides methods to create new custom buttons, for example, on record Detail pages, on related information applets, or on applets on My Homepage. To create custom buttons, you can use the createButton() method.
To retrieve both preconfigured buttons and custom buttons, you use the getButton() method. For more information about these methods, see Methods for the oraclecrmod Object.
Examples of Uses for Custom Buttons
Some examples of the uses for custom buttons are as follows:
A custom button on Account record pages to validate the DUNS number
A custom button to validate entered data and return error messages and details of fields that must be corrected
A custom button to change the owner record or assign a book.
Hiding and Disabling Buttons
The JavaScript API provides methods to hide buttons and show buttons that were previously hidden. This feature is useful for situations when preconfigured buttons in Oracle CRM On Demand are not required by the user. You can hide buttons unconditionally or hide buttons based on some specified condition, for example, based on user roles.
You can use methods to disable buttons so that they are grayed out, and to enable buttons that were previously disabled. For information about all of these methods, see Methods for the Button Object.
Creating Tooltips for Buttons
The JavaScript API allows you to specify tooltip text when you create a custom button and provides a method to specify tooltip text for multiple existing buttons in a single call.
You can use methods to get and set tooltip text for a button and to get and set the tooltip format, which can be HTML or plain text. For information about these methods, see Methods for the Button Object.
Changing the Look and Feel of a Button
The JavaScript API provides methods to change the look and feel of a button. You can do the following:
Set or change the display text for a button.
Set or change the image for a button by providing a URL to the image.
You can use methods to get information about the text and image for a button. For information about these methods, see Methods for the Button Object.
Changing the Behavior of Buttons
The JavaScript API enables you to specify the onclick event handling for a custom button or modify the onclick event handling of a custom button or preconfigured button (such as New, Save, and Cancel), and thereby change its behavior.
You can change the click event handling of custom and preconfigured buttons to do the following:
Set or retrieve on-screen values.
Create, read, update, and delete (CRUD) off-screen records.
For information about registering and removing event handlers, see Methods for the Button Object and Defining an Event Handler for a Button.
Getting and Setting On-Screen Values
You can use getter and setter methods to retrieve and set the values of fields on the current page when a user clicks a button. For all fields, language dependent code (LDC) values are retrieved, however for picklists, there are also additional getter and setter methods to retrieve and set language independent code (LIC) values. For information about these methods, see Methods for the Field Object and Getting and Setting LIC Values of Picklists.
Creating, Reading, Updating, and Deleting Records
You can use methods to perform the following operations on off-screen records when you click a button:
Create record. You can create a record and specify the record type, its fields, and their values.
Read record. You can retrieve the fields from a record. You can specify the record type, record row ID, and a list of field names to be returned with their values.
Update record. You can update a record identified with a specific row ID. You can specify the field names and values to update the record.
Delete record. You can delete a record identified with a specific row ID.
For all of these create, read, update, and delete (CRUD) operations, you must have access to the record. If you do not, then the operation fails. You must implement a callback function to handle the results of the CRUD operation, when they become available. For information about the CRUD methods, see Methods for CRUD Operations.
Error Handling
For methods of the JavaScript APIs that return an object or value, null is returned when an issue occurs. However, the methods for CRUD operations are an exception as they return an error object.
When using the JavaScript API you must implement your own error handling, which gives you the flexibility to either show the error, or capture and handle it. For more information about error handling, see Errors and Error Handling.
Contexts in Which You Can Customize Buttons
Using the JavaScript API you can customize buttons in the following contexts:
On the Homepage for a record type, such as Account, Contact, Lead, and so on
On the Detail page for a record type
On the Edit Page for a record type
On related information (child) applets for record types, for example, the Account Related Information applet on contact records
On applets on My Homepage
On Administration pages
On pop-up windows, including the following:
Quick create windows (new record form) available from the action bar
Single-association Lookup windows
Multiassociation Lookup windows
Multi-select picklist pop-up windows
Currency pop-up windows
Customizing buttons on any other page is not supported. Menu buttons are also not supported, and you cannot add custom buttons to the action bar.
Customizing buttons on both standard and customized page layouts is supported, and you can create custom buttons on customized page layouts. Different page layouts can have the same buttons with different behavior.
In the related information sections for records (child applets), button customizations will appear in both the tab view and the expanded view. For example, if you disable a button for a child applet, then it appears disabled in both the tab view of the related records and on the expanded view for the child record.
You can use methods to determine the context in which your code runs, including the page type and information about the currently logged-in user. For more information about these methods, see Methods for the Context Object.
Color Coding of Fields and Rows
You can use methods of the JavaScript API to highlight fields and rows in different colors in the Oracle CRM On Demand UI when particular conditions are met. You can change the colors of the following:
In Detail pages, the background color and text color of field labels and field values.
In Edit pages, the background color and text color of field labels and the background color of field values.
In List pages (and related item lists), the background color and text color of field values. Also, the background color for entire rows.
As an example, on account records the Account Name field might be used for highlighting key accounts. On the Account Detail page the color of the Account Name field could change, for example, to green, when the sales representative changes the value of the Account Revenues field to a threshold value. On the Account List page, rows for key account records would be highlighted in green.
For a code sample, see Code Sample for Color Coding of Fields and Rows.
The color coding that is set using the JavaScript API takes precedence over system or theme colors. For example, if you set a required field to another text color, the color coding overrides the red text color for the required field.
Color Coding of Fields in Detail and Edit Pages
To support color coding in Detail and Edit pages, a Form object is required and a custom handler must be registered for the form. For information about methods of the Form object, see the table in JavaScript API Reference, and for an example of a custom handler, see Example of a Custom Handler for a Form Object.
The custom handler is automatically executed when the form initially loads or refreshes due to any other actions on the screen such as inline editing. In the custom handler you can use methods of the Field object to get and set colors for the labels and values of fields, see the table in JavaScript API Reference.
Color Coding of Fields and Rows in Lists
To support color coding in lists (on List pages and in related item lists), a List object and ListRow object are required respectively for the list, and specific rows in the list. A custom handler must be registered for the List object and this handler is automatically executed on initial page load, on paging, and when a field on any of the rows is edited inline. For information about methods of the List object, see the table in Methods for the List Object, and for an example of a custom handler, see About the Custom Handler for a List Object.
In the custom handler you can use:
Methods of the ListRow object to get and set the background color of rows, see the table in Methods for the ListRow Object.
Methods of the Field object to get and set colors for the values of fields within rows, see the table in JavaScript API Reference.
For information about finding the field names that you must use when working with these methods, see Finding Field Names.
For information about finding list names, see Finding List Names.
Restrictions That Apply to Color Coding of Fields
Using the JavaScript API, you can set the color coding of entire concatenated fields. However, the color coding of constituent fields of a concatenated field is ignored, as partial coloring of a field is not possible. For example, you might have the Account Name field included in a concatenated field. The field value text color of Account Name may be coded to red, but the Account Name part of the concatenated field will not be red unless the field value text color for the whole concatenated field is coded as red.
There is no display text for check boxes, or for visual indicator fields such as Star Rating and Stoplight fields, therefore attempts to set text colors on these fields are ignored.