CRM On Demand Technical Tips and Tricks: Javascript API - Classes, Context, The Screen, Chaining Plus the Titlebar

techtips.jpg

This post is part of a series of technical articles we are writing on the Javascript API. In this series, we will cover:

  1. Custom buttons.
  2. Storing your code.
  3. Classes, context, the screen, chaining plus the titlebar.
  4. CRUD. Create, Read, Update and Delete records. In our first two blog articles in this series you learned the canonical “hello world” program, creating a custom button that when clicked alerted that it was clicked and then disabled the button. Then two options for storing your code were provided.

In this blog article we’ll discuss working with the JavaScript API more, including working with classes, context, the screen, chaining plus the titlebar.

Classes

Javascript doesn’t have classes!

Ok. So why discuss classes here?

Even though Javascript doesn’t have classes, there are ways to effectively simulate classes. The Oracle CRM On Demand JavaScript API does something like this class simulation, and classes “look” as you’d expect them too. They have properties and methods, just like other languages such as C++, Java, and Python.

Three main classes are provided in the API. These are the Button, TitleBar and Context classes.

Buttons

We’ve already seen buttons in use in the first blog posting of this series. Buttons have unique IDs assigned to them, either:

  • by you the developer,
  • by Oracle for the standard buttons,
  • or automatically when creating a new button and not specifically assigning it an ID.

Buttons are always shown on a TitleBar. If a button isn’t assigned to a TitleBar, then it can’t be displayed.

Besides having properties and methods associated with it, a button also has event handlers. For instance, you can create an event handler for calling a function when the button is clicked by the end user. For a complete set of events associated with buttons, see the section “Defining an Event Handler for a Button” in the Oracle CRM On Demand JavaScript API document. See the section “Methods for the Button Object”, in the same document, for all the methods associated with buttons. These methods include the ability to get and set properties of a button like the text of the button or an image to put on a button.

In our hello world example in the first blog posting, the “click” event calls the do_hello_world method.

button.on("click", do_hello_world);

As you can see, assigning a method to an event on a button is very simple using the .on function call for buttons.

TitleBar

As mentioned above, every button must be assigned to a TitleBar if you want to be able to show the button. The TitleBar objects are very minimalist in the JavaScript API, having only one function call. This is the getButton function.

Again in our first blog posting we used a TitleBar object.

// Create the custom button on the main Account detail title bar button = oraclecrmod.createButton({ id:"do_hello_world_id", text:"Say Hello", parent:oraclecrmod.getTitleBar("AccountFormTB") });

Notice that the TitleBar is found and then assigned to the specific button during the creation of the button instance. To specifically assign the getButton function call, the following code checks that the button that is returned from the getButton call has the ID as we expect.

var tb = oraclecrmod.getTitleBar(“AccountFormTB”); var b1 = oraclecrmod.createButton({ id:"do_hello_world_id", text:"Say Hello", parent:tb }); var b2 = tb.getButton(“do_hello_world_id”); if(b2.getId() == b1.getId()) { alert(“looks good!”); } else { alert(“Hmmm. Something is wrong. This should never happen!”); }

Context

The Context class provides information about the current context of CRM On Demand including the current record type (Account, Contact, etc), the page type (detail page, edit page, home page, etc), and the logged in user. Only one context object is available to you and is found as oraclecrmod.ctx. Again, for complete details see the “Methods for the Context Object” in the Oracle CRM On Demand JS API document.

In our hello world example we also used the context object.

// Only add custom button on Account Detail Page if(oraclecrmod.ctx.object == "Account" && oraclecrmod.ctx.isDetailPage()) { function do_hello_world() { ...

Notice that this checks to see if we are on the account object and that it is a detail page. Then if so, create the <tt>do_hello_world</tt> method.

The Screen

If you want to get or set field values on either an edit or new page, the Screen object is your friend. It only has three methods:

  • getField, for retrieving a specific field on the screen
  • getValue, for getting the value of a field
  • setValue, for setting the value of a field

For instance, if you have a custom field called “customer_rating” then if that customer_rating field is on the screen it can be changed via javascript code.

var f = oraclecrmod.getField(“customer_rating”); if(f.getValue() == “H”) { f.setValue(“High”); } else if(f.getValue() == “M”) { f.setValue(“Medium”); } else if(f.getValue() == “L”) { f.setValue(“Low”); }

As you can see, this code simply changes the values to High, Medium or Low from values of H, M and L.

Chaining

JQuery is perhaps the most popular third party JavaScript library in the world. It was one of the first open source JavaScript libraries that used chaining, leading to its widespread adoption.

Chaining allows code to run multiple methods within a single statement. With our hello world code you can see chaining in action.

oraclecrmod.getButton("do_hello_world_id").disable();

Notice that on one line of code we are calling the getButton and the disable function calls. Without chaining the code would look like this:

var b = oraclecrmod.getButton("do_hello_world_id"); b.disable();

Note only is the chaining code more compact, much of the time it’s actually easier to understand. With the chaining code you basically can “read” the code like reading a book. In this case it reads “on the oraclecrmod object, get the button called do_hello_world_id and disable that button”.

Also note that if no <tt>do_hello_world_id</tt> button exists, then the disable function is never called. It behaves as one would expect it to.

While our code chained together two methods, there’s really no limit to how many methods can be chained. A good rule of thumb is to only chain if it makes it easier to read the code. If additional chaining of a given line makes it more difficult to read, then you’re going to far. In that case it might be best to put the code on multiple lines.

In the final article in this API series, we’ll discuss CRUD; Creating, Reading, Updating and Deleting records.

Don’t forget to subscribe to our quarterly update and get valuable information on CRM Best Practices, User Adoption, CRM On Demand Tips & Techniques, and our upcoming R26 series.