Siebel CRM Desktop for Microsoft Outlook Administration Guide > Customizing Siebel CRM Desktop > Overview of Customizing Siebel CRM Desktop >

Customizing Form Handlers

This topic describes how to customize form handlers. It includes the following information:

• Overview of Customizing Form Handlers
• Customizing Form Functions
• Customizing Event Connectors
• Customizing Triggers
• Customizing Defaulting

You can also specify form handlers that do validation. For more information, see Validating the Data That Users Enter.

Overview of Customizing Form Handlers

A form handler is a JavaScript function that CRM Desktop defines in the forms.js file. Each form that displays a top-level object, such as an account or contact, includes a form handler. If the user double-clicks one of these objects, then CRM Desktop does the following work:

• Determines if a form handler exists for this object.
• If a form handler exists, then CRM Desktop calls the function that the form handler specifies.

The form handler uses the following format:

objectType_form()

For example:

contact_form()

You can specify a form handler between the following tags in the definition of the object in the forms_xx.xml file:

<script>>
</script>

For example, the following code specifies a form handler for contacts:

<script><![CDATA[
  include("forms.js", "forms");
  var ctx = {"application": application,"ui": ui,"application_script":   application_script,"form": form};
  var current_form = new forms.contact_form(forms.create_form_ctx(ctx));
  ]]>
</script>

Customizing Form Functions

A form function is a type of function that resides in the form handler function that Siebel CRM Desktop uses for the object. It is specific to the form that contains the object. You can use a form function to validate user entry or to add business logic, such as to enter information in a hidden field, create a link, and so on. For more information, see Functions That You Must Not Modify.

To customize form functions

1. Use a JavaScript editor to open the forms.js file.
2. Locate the following section:

   //FORM FUNCTIONS

3. Add the form functions that your customization requires to the section that you located in Step 2.

   To view example form functions that do validations, see Example of Creating a Custom Validation.

Using Regular Expressions in Form Functions

To use a regular expression in a form function, you use a variable that contains the filtering criteria and a string that Siebel CRM Desktop must examine. You use the following format:

function function_name()
{
var fields = form.item.snapshot;
var filter = regular_expression
return filter.test(fields['field_name']);
}

where:

• function_name identifies the name of your custom function.
• regular_expression contains a string. You use two forward slashes (//) to indicate this regular expression.
• field_name identifies the field that contains the string that you define in the regular expression.

For example, the following example uses a regular expression to make sure the user enters a value of manager in the Job Title field:

function validate_job_title()
{
var fields = form.item.snapshot;
var filter = /manager/g
return filter.test(fields['Job Title']);
}

Customizing Event Connectors

An event connector is a type of form function that can run another function when CRM Desktop triggers a form event or a control event. This topic describes how to add two different example event connectors.

To customize event connectors

1. Use a JavaScript editor to open the forms.js file.
2. Locate the following section:

   //FORM EVENTS

3. Add the event connectors that your customization requires to the section that you located in Step 2.

   To link a function to the form event, you use the following format:

   ctx.form.event_type.connect(function_to_call);

   If you link a control to the form event, you use the following format:

   ctx.events.connect(control_name, control_event, function_to_call);

   For example, the following code connects a form function to a form event:

   ctx.form.on_saving.connect(form_saving);

   In this example, CRM Desktop calls the form_saving function before it saves the record. It connects the on_saving event that resides in each form to a function that resides in the form handler for each object that the form.js file defines. To view another example of this usage, see Adding Postdefault Values to Fields.

   For another example, the following code connects the event that CRM Desktop uses with the sales_method field to the on_sales_method_changed function:

   ctx.events.connect(ctx.form["sales_method"], "changed", on_sales_method_changed);

   This connect uses the following parameters to make the call:

   • Form control name
   • Event for the control
   • Function name

     To view more examples of this usage, see Updating One Field If the User Modifies Values In Another Field, and Linking Fields and Testing Your Hierarchical Picklist.

Customizing Triggers

A trigger is a type of function that Siebel CRM Desktop calls if an event occurs. If CRM Desktop creates or removes a link, and if a trigger exists for this link, then CRM Desktop calls this trigger.

To customize triggers

1. Use a JavaScript editor to open the forms.js file.
2. Locate the form handler you must modify.

   You can add a trigger anywhere in the form handler or in the business_logic.js file in the section that starts with the following code:

   with (scheme.triggers)

3. Add the triggers that your customization requires to the form handler that you located in Step 2.

   You use the following format to add a trigger:

   ctx.triggers.add_simple_trigger(function_name, link_source, link_destination, link_tag, link_operation);

   where:

   • function_name specifies the name of the function that CRM Desktop must call.
   • link_source specifies the object type that CRM Desktop uses as the link source.
   • link_destination specifies the object type that CRM Desktop uses as the link destination.
   • link_tag identifies the tag. The tag you specify depends on the following function that defines the relationship that exists between objects. This function resides in the business_logic.js file:
     • add_direct_link. You set link_tag to direct. For example, to support a user who uses the autocomplete list to create the link from an opportunity object to an account object.
     • add_mvg_link. You set link_tag to mvg. For example, to support a user who uses a multivalue group to create a link between object types.
   • link_operation specifies when CRM Desktop runs the trigger. You can use one of the following values:
     • created. CRM Desktop runs the trigger if the user creates the link. For example, if the user adds a new account to an opportunity.
     • removed. CRM Desktop runs the trigger if the user removes the link. For example, if the user deletes an existing account from an opportunity.

       In the following example, if the user adds an account to an opportunity, then CRM Desktop calls the on_update_account function:

   ctx.triggers.add_simple_trigger(on_update_account, "Opportunity", "Account", "direct", "created");

   For an example that uses a trigger, see Allowing Users to Open Top-Level Objects from the Control Panel.

Customizing Defaulting

Defaulting is a type of form function that automatically enters a value in the field of a form when the user creates a new item. It gets the functions and values for these fields from the business_logic.js file that defines the object, and then uses these functions and values to enter the field values. Defaulting uses the following code:

ctx.form_links_manager.init_new()

This code exists in every form handler. It calls the init_new method that resides in the form_links_manager, which is an object that determines the behavior of a form and specifies the relationship that exists between controls that reside in this form and the fields that these controls reference. The init_new method gets information about an object from the business_logic.js file, including information about how the defaulting options are set for the object. You specify these options in the //Defaulting section of the business_logic.js file. For more information about adding default values, see Adding Default Values to Fields.

To customize defaulting

1. Use a JavaScript editor to open the forms.js file.
2. Locate the following section:

   //Defaulting

3. Add the defaulting that your customization requires to the section that you located in Step 2.

   You use the following format to define defaulting:

   scheme.objects.get_object(object_type).get_field(object_field)["source"] = "string_value";

   where:

   • object_type identifies the type of object where CRM Desktop must enter a default value. For example, to add a default value for an action.
   • object_field identifies the name of a field where CRM Desktop must enter a default value. This field resides in the object type, such as Status.
   • source identifies how CRM Desktop gets the default value that it enters.
   • string_value identifies where CRM Desktop gets the string that it uses for the default value.

Table 15 describes how you set string_value depending on how you set source.