View source | Discuss this page | Page history | Printable version   

How to create a Callout

Contents

Objective

The objective of this article is to show you how to create a new callout. A callout is a piece of Javascript code associated with a particular field on a tab. This code is executed whenever the field changes. It is a type of Ajax substitute, changing parts of a tab/window without the need of refreshing it.

It works by calling the FIC when a field with an associated callout is changed. The FIC (Form Initialization Component) refreshes the needed fields based on the callout logic.

This how-to will implement the following new functionality: When entering a new product, one has the option of entering the Search Key for the product, the Name and the Category it belongs to. But what if our client wants the search key to be constructed automatically by taking the product's name, removing all spaces, appending the underscore (_) and the category name it belongs to.

For example, this way the Search Key of a product that has the Name Bon Fountain and belongs to the Water Product Category would become BonFountain_Water. Let's see how this could be done using a callout.

The steps involved in creating a new callout are:

  1. Create the source file(s) of the callout (usually a java file).
  2. Define the new callout within the application dictionary (menu Application Dictionary > Setup > Callout).
  3. Associate this callout with a table column (Application Dictionary > Table and Column: Callout field withinin Column tab).
  4. Compile the window/tab(s) where this Column is used.

IMPORTANT NOTE: Developments related to points (1) and (2) must belong to a module that is not the core module. Please follow the How to create and package a module section to create a new module. For the development related to point (3) about modifying a core located column, a new template is needed. You can read the How to change an existing Window article to obtain more information.

Bulbgraph.png   This article assumes you have created both module and template according to the howtos just mentioned.


Creating the Callout

Existing callouts are located in src/org/openbravo/erpCommon/ad_callouts.

The right way to create a callout is by extending the SimpleCallout class. This class simplify the callout code, hide some of the internals of the callout and keep you focused on the operations required. To access database data DAL is used.

Theory

To develop a new callout based on this class you only have to create a new java class that extends SimpleCallout and overwrite the following method:

 protected void execute(CalloutInfo info) throws ServletException;

In this method you can develop the logic of the callout and use the info object of class CalloutInfo to access window fields, database and other methods. The most important are:

It is important to keep coherence with each expected data type (String, BigDecimal, ...)

See the following class as an example of a class that currently uses SimpleCallout: SL_Project_Service. This callout simply takes the numeric value of two fields, calculates the sum and writes it into another field. This is the interesting part of the code that performs the logic:

 @Override
 protected void execute(CalloutInfo info) throws ServletException { 
 
     BigDecimal serviceSerCost = info.getBigDecimalParameter("inpservsercost");
     BigDecimal serviceOutCost = info.getBigDecimalParameter("inpservoutcost"); 
 
     BigDecimal serviceTotalCost = serviceSerCost.add(serviceOutCost);
 
     info.addResult("inpservcost", serviceTotalCost);
 }

Extend a Callout

It is possible to implement a callout that extends from another callout. For more information visit this How to create a callout that extends from another callout tutorial.

Bulbgraph.png   This feature is available from version 3.0PR16Q4

Product Search Key Calculation using SimpleCallout

Let's define the tasks that need to be performed by the callout:

  1. Retrieve the name of the product as entered by the user
  2. Retrieve the ID of the category selected from a dropdown by the user
  3. Get the name of the product category inside the database using the product category ID retrieved
  4. Strip spaces out of the product and category names
  5. Construct the Search Key
// the package name corresponds to the module's manual code folder 
// created above
package org.openbravo.howtos.ad_callouts;
 
import javax.servlet.ServletException;
 
import org.openbravo.utils.FormatUtilities;
import org.openbravo.erpCommon.ad_callouts.SimpleCallout;
import org.openbravo.base.secureApp.VariablesSecureApp;
// classes required to retrieve product category data from the 
// database using the DAL
import org.openbravo.dal.service.OBDal;
import org.openbravo.model.common.plm.ProductCategory;
 
// the name of the class corresponds to the filename that holds it 
// hence, modules/modules/org.openbravo.howtos/src/org/openbravo/howtos/ad_callouts/ProductConstructSearchKey.java.
// The class must extend SimpleCallout
public class ProductConstructSearchKey extends SimpleCallout {
 
  private static final long serialVersionUID = 1L;
 
  @Override
  protected void execute(CalloutInfo info) throws ServletException {
 
    // parse input parameters here; the names derive from the column
    // names of the table prepended by inp and stripped of all
    // underscore characters; letters following the underscore character
    // are capitalized; this way a database column named
    // M_PRODUCT_CATEGORY_ID that is shown on a tab will become
    // inpmProductCategoryId html field
    String strProductName = info.getStringParameter("inpname", null);
    String strProductCategoryId = info
                    .getStringParameter("inpmProductCategoryId", null);
 
    // inject the result into the response
    info.addResult("inpvalue", getConstructedKey(info.vars, strProductName, strProductCategoryId));
  }
 
  protected String getConstructedKey(VariablesSecureApp vars,
        String strProductName, String strProductCategoryId) {
 
    // Retrieve the product category name
    final ProductCategory productCategory = OBDal.getInstance().get(ProductCategory.class,
            strProductCategoryId);
    String strProductCategoryName = productCategory.getName();
 
    // construct full key
    String generatedSearchKey = FormatUtilities.replaceJS(strProductName
                .replaceAll(" ", ""))
                + "_" + strProductCategoryName.replaceAll(" ", "");
 
    // return generated key
    return generatedSearchKey;
  }
}

Defining the Callout within the Application Dictionary

NOTE: You need to have ONLY your module as "In Development" at this stage.

Using the role System Administrator navigate to Application Dictionary || Setup || Callout. Create a new record as indicated by the screenshot below:

Bulbgraph.png  

The name of the callout should not have spaces or illegal javascript characters.

HTDCallout1.png


Save and navigate to the Callout Class tab of the same window. You will notice that the Java Class Name was automatically generated for you, however, not correctly since the name could not match the Callout name you have provided. Correct it in line with your callout package/class name. See screenshot below:


HTDCallout2.png


Now Openbravo knows that a callout exists and is implemented by the class you have just specified.

Bulbgraph.png  

Remember to perform

ant export.database

in order to persist your changes in your module.

Associating the Callout with a Column

NOTE: You need to have ONLY your template as "In Development" at this stage.

Using the role System Administrator navigate to Application Dictionary || Tables and Columns and find the M_Product DB Table. This is the underlying table of the main tab of the Product window.

Go to Column tab, find the Name record and edit it. Find the Callout dropdown that should at this point be empty. Select our Product_Construct_SearchKey callout and save the record:


HTDCallout3.png


Do the same for the Product Category record since a change in any of them should also regenerate the Search Key.

Bulbgraph.png  

Remember to perform

ant export.database

and

ant export.config.script

in order to persist your changes in your template.

Compiling the Window

Finally, for the callout to take effect, the window that uses it needs to be recompiled and deployed to Tomcat. If using Eclipse, use the eclipse.compile ant task and enter Product into the dialog that pops up. If manually compiling Openbravo, use the

ant smartbuild 

or

ant compile.development -Dtab=Product

IMPORTANT NOTE: once the compilation has finished, restart Apache Tomcat server.

See more on Build Tasks.

Now it is time to test the result!


The Result

Using the role Openbravo Admin (or your defined 'administrator' role), navigate to the Master Data Management || Product window. Enter a new product with Name = Bon Fountain and leave the Name field. Notice how the Search Key changes. Then, change the Product Category to something else and see how the change is reflected inside the Search Key field.


HTDCallout4.png


Save.

You have now successfully created your first new callout and seen how it came to life within Openbravo. Congratulations!

Retrieved from "http://wiki.openbravo.com/wiki/How_to_create_a_Callout"

This page has been accessed 36,671 times. This page was last modified on 2 November 2020, at 06:14. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.