Siebel Object Interfaces Reference > Siebel Object Interfaces Reference > Object Interfaces Reference >

Applet Events

This topic describes applet events. It includes the following topics:

• Overview of Applet Events
• Applet_ChangeFieldValue Event
• Applet_ChangeRecord Event
• Applet_InvokeMethod Event
• Applet_Load Event
• Applet_PreInvokeMethod Event
• WebApplet_InvokeMethod Event
• WebApplet_Load Event
• WebApplet_PreCanInvokeMethod Event
• WebApplet_PreInvokeMethod Event
• WebApplet_ShowControl Event
• WebApplet_ShowListColumn Event

Overview of Applet Events

Siebel CRM calls an applet event in reply to a user interaction. You can manage each event for each applet. You can use an applet event only in high interactivity mode.

The format for an applet event that you use on the browser is Applet_event.

where:

• event is the name of the event.

For example, Applet_ChangeFieldValue. If the event includes the Applet prefix, then you can use it only on the browser.

The format for an applet event that you use on the Siebel Server is WebApplet_event.

where:

• event is the name of the event.

For example, WebApplet_InvokeMethod. If the event includes the WebApplet prefix, then you can use it only on the Siebel Server.

Applet_ChangeFieldValue Event

The Applet_ChangeFieldValue event starts if the user uses an applet to modify data in a field. It does not return any information. For more information, see Applet_ChangeRecord Event.

Format

Applet_ChangefieldValue(fieldname, fieldValue)

Table 24 describes the arguments for the Applet_ChangeFieldValue event.

Usage

Note the following usage of the Applet_ChangeFieldValue event:

• If the user moves to a different record but does not modify a value in the previous record, then the ChangeFieldValue event does not start.
• If the user modifies the value of a field, and if Siebel CRM modifies the value in another field that depends on some way on the value that the user modified, such as a calculated field, then the event starts once for each field whose value Siebel CRM modifies.
• If the user uses a pick applet or popup applet to modify the data that a field contains, then this event does not start.

Used With

Browser Script

Examples

The following example is in Browser Script:

function Applet_ChangeFieldValue (field, value)
{
   try
   {
      switch (field)
      {
         case "Primary Revenue Committed Flag":
         if (value == "Y")
         {
            var thisBC = this.BusComp();
            var sRev = thisBC.GetFieldValue("Primary Revenue Amount");
            var sUpside = thisBC.GetFieldValue("Primary Revenue Upside Amount");
            var total = sRev + sUpside;
            if (total < 500000)
            {
               thisBC.SetFieldValue("Primary Revenue Committed Flag", "N");
               theApplication().SWEAlert("Changing the Committed Flag to NO as
                 $500,000 in Revenue and Upside amount is required");
            }
         }
         break;
      }
   }
   catch(e)
   {
// error handling routine
}

Applet_ChangeRecord Event

Siebel CRM calls the Applet_ChangeRecord event if the user moves to a different record or view. It does not return any information. For more information, see Applet_ChangeFieldValue Event.

Format

Applet_ChangeRecord()

No arguments are available.

Used With

You use the Applet_ChangeRecord event with Browser Script. Note the following:

• To return the value of the field the user navigates to, use the BusComp.GetFieldValue method.
• To return the value of the field the user navigates away from, use the control.GetValue method.

Examples

The following example is in Browser Script:

function Applet_ChangeRecord ()
{
   try
   {
      var thisBC = this.BusComp();
      var sFlag = thisBC.GetFieldValue("Primary Revenue Committed Flag");
      if (sFlag == "Y")
      {
         theApplication().SWEAlert("This record cannot be updated because it has
         been committed");
      }
   }
   catch(e)
// error handling routine

}

Applet_InvokeMethod Event

The Applet_InvokeMethod event can start if any of the following items occur:

• A call to applet.InvokeMethod occurs
• A call to a specialized method occurs
• A user chooses a menu item in a menu that the user defines

For more information, see About Specialized and Custom Methods.

This method does not return any information.

Format

Applet_InvokeMethod(name, inputPropSet)

Table 25 describes the arguments for the Applet_InvokeMethod event.

Usage

This method sends information you specify in the inputPropSet argument to the PreInvokeMethod event. You can use the Applet_InvokeMethod event to display or hide controls, or to set a search specification. To access a business component from this event handler, do the following:

• Use this.BusComp.
• Do not use TheApplication.ActiveBusComp.

Used With

Browser Script

Examples

Some methods can create, modify, or delete records. These actions might call an event at the applet or business component level. If you require Siebel CRM to perform a specific action before or after the method run, then you can use these events. The following example includes custom code in the PreInvokeMethod event and the InvokeMethod applet event. For more information, see Applet_PreInvokeMethod Event.

To set the fields, this code sets and resets the flag and uses the NewRecord server event:

function Applet_PreInvokeMethod (name, inputPropSet)
{
   if (name == "Quote")
   {
      // Add code that Siebel CRM must run BEFORE the special method
      // Set flag to "1"
      theApplication().SetProfileAttr("flag","1");
   }

   return ("ContinueOperation");
}

function Applet_InvokeMethod (name, inputPropSet)
{
   if (name == "Quote")
   {
      // Add code that Siebel CRM must run AFTER the special method
      // Reset the flag to "0"
      theApplication().SetProfileAttr("flag","0");
   }

}

function BusComp_NewRecord ()
{
   if (theApplication().GetProfileAttr("flag")== "1" )
   {
      this.SetFieldValue ("Field1", "Value1");
      this.SetFieldValue ("Field2", "Value2");
      . . . . .
   }

}

Applet_Load Event

Siebel CRM calls the Applet_Load event after it loads an applet and displays the data for that applet. It does not return any information.

Format

Applet_Load()

No arguments are available.

Usage

To hide or manipulate controls or to set properties on an ActiveX Control in a form applet, you can use the Applet_Load event. You can manipulate the following types of controls:

• CheckBox
• ComboBox
• TextBox
• TextArea
• Label

If you must display a dialog box, then do not use the SWEAlert method or the RaiseErrorText method with the Applet_Load event. This technique can cause the browser to fail if Siebel CRM has not fully rendered the Siebel application in the browser.

Used With

Browser Script

Examples

You can use the following example only with code on a form applet:

function Applet_Load ()
{
   // Get the control instance.
   var ctrl = this.FindControl("FirstName");

   // Hide the control
   ctrl.SetProperty("Visible","false");

   // Hide the label
   ctrl.SetLabelProperty("Visible", "hidden");
}

Applet_PreInvokeMethod Event

Siebel CRM calls the Applet_PreInvokeMethod event immediately before it calls a specialized method on an applet. The Applet_PreInvokeMethod event can start if any of the following items occur:

• A call to the InvokeMethod method on an applet occurs.
• A user chooses a custom menu item that you define in Siebel Tools.

This event returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

For more information, see About Specialized and Custom Methods.

Format

Applet_PreInvokeMethod(name, inputPropSet)

The arguments you use with this format are the same as the arguments described in Table 25.

Used With

Browser Script

Examples

function Applet_PreInvokeMethod (name, inputPropSet)
{
   if(name == 'NewRecord')
   {
      if(confirm("Are you sure you want to create a new record?"))
         return ("ContinueOperation");
      else
         return ("CancelOperation");
      return ("ContinueOperation");
   }
}

WebApplet_InvokeMethod Event

Siebel CRM calls the WebApplet_InvokeMethod event after a specialized method on the Web applet runs. WebApplet_InvokeMethod starts only for a predefined method. It does not start for a custom method. For more information, see About Specialized and Custom Methods.

This method does not return any information.

Format

WebApplet_InvokeMethod(methodName)

Table 26 describes the arguments for the WebApplet_InvokeMethod event.

Used With

Server Script

Examples

The following example is in Siebel eScript:

switch (MethodName)
{
   case "NewQuery":
      TheApplication().SetSharedGlobal("EnableButton", "N"); break;
   case "ExecuteQuery":
      TheApplication().SetSharedGlobal("EnableButton", ""); break;
   case "UndoQuery":
      TheApplication().SetSharedGlobal("EnableButton", "");
   break;
}

The following example is in Siebel VB:

Select Case MethodName
Case "NewQuery"
   TheApplication.SetSharedGlobal "EnableButton", "N"
Case "ExecuteQuery"
   TheApplication.SetSharedGlobal "EnableButton", ""
Case "UndoQuery"
   TheApplication.SetSharedGlobal "EnableButton", ""
End Select

Related Topics

For more information, see the following topics:

• Applet_InvokeMethod Event
• Application_InvokeMethod Event
• WebApplet_PreCanInvokeMethod Event

WebApplet_Load Event

Siebel CRM calls the WebApplet_Load event immediately after it loads an applet. It does not return any information.

Format

WebApplet_Load()

No arguments are available.

Usage

To avoid returning a null value, do not call TheApplication.ActiveBusObject from the WebApplet_Load event. Instead, you can use this.BusObject to get a reference to the current business object.

Used With

Server Script

Examples

The following example is in Siebel eScript:

function WebApplet_Load ()
{
   try
   {
      var currBC = this.BusComp();
      with (currBC)
      {
         SetViewMode(OrganizationView);
         ClearToQuery();
         SetSearchSpec("Last Name", "A*");
         ExecuteQuery(ForwardBackward);
      }
   }
   catch (e)
   {
      TheApplication().RaiseErrorText(e.errText);
   }
}

The following example is in Siebel VB:

Sub WebApplet_Load
   Dim iReturn As Integer
   Dim currBC As BusComp
   Set currBC = Me.BusComp
   With currBC
      .SetViewMode OrganizationView
      .ClearToQuery
      .SetSearchSpec "Last Name", "A*"
      .ExecuteQuery
   End With
End Sub

Related Topics

For more information, see the following topics:

• Applet_InvokeMethod Event
• Application_InvokeMethod Event
• WebApplet_PreCanInvokeMethod Event

WebApplet_PreCanInvokeMethod Event

The WebApplet_PreCanInvokeMethod event allows a script to determine if the user possesses the authority to call the applet method. Siebel CRM calls this method in the following situations:

• Before it calls the PreInvokeMethod event.
• If the user steps to a different record.
• If it loads an applet.
• If it calls a different method from Browser Script. For example, the GetProfileAttr method or the SetProfileAttr method.

This method returns CancelOperation or ContinueOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

Format

WebApplet_PreCanInvokeMethod(MethodName, &CanInvoke)

Table 27 describes the arguments for the WebApplet_PreCanInvokeMethod event.

Usage

Using the FirstSelected business component method with the PreCanInvokeMethod event can cause unexpected behavior in a pick applet that Siebel CRM calls from the applet where this event is called.

To enable and disable a method, it can be easier to use the CanInvokeMethod applet user property at the applet level. For an example, see Using a MiniButton Control to Call a Custom Method. For information about the CanInvokeMethod user property, see Siebel Developer's Reference.

Used With

Server Script

Examples

The following example is in Siebel eScript:

function WebApplet_PreCanInvokeMethod (MethodName, &CanInvoke)
{
   if ( MethodName == "CustomMethod" )
   {
      CanInvoke = "TRUE";
      return( CancelOperation );
   }
   return (ContinueOperation);
}

The following example is in Siebel VB:

Function WebApplet_PreCanInvokeMethod (MethodName As String, CanInvoke As String) As Integer
   Dim iReturn As Integer
   iReturn = ContinueOperation
   If MethodName = "Test" Then
      CanInvoke = "TRUE"
      iReturn = CancelOperation
   End If
   WebApplet_PreCanInvokeMethod = iReturn
End Function

WebApplet_PreInvokeMethod Event

Siebel CRM calls the WebApplet_PreInvokeMethod event before it calls any of the following:

• A specialized method for the Web applet.
• A custom method that Siebel CRM calls through the oWebApplet object of the InvokeMethod method.

This method returns ContinueOperation or CancelOperation. For more information, see Caution About Using the Cancel Operation Event Handler.

For more information, see About Specialized and Custom Methods.

Format

WebApplet_PreInvokeMethod(methodName)

The arguments you can use with this format are the same as the arguments described in Table 26.

Used With

Server Script

Examples

The following example is in Siebel eScript:

function WebApplet_PreInvokeMethod (MethodName)
{
   switch (MethodName)
   {
   case "CustomMethod":
      var applet = this;
      var BC = applet.BusComp();
      var ConId = BC.GetFieldValue("Contact Id");
      var WshShell = COMCreateObject("WScript.Shell");
      WshShell.Popup("My Custom Method was called. Here is the ID " + ConId);
      return(CancelOperation);
      break;
   }
   return (ContinueOperation);
}

The following example is in Siebel VB:

Function WebApplet_PreInvokeMethod (MethodName As String) As Integer
   Dim iReturn As Integer
   iReturn = ContinueOperation
   Select Case MethodName
   Case "CustomMethod"
      Dim oBusComp As BusComp
      Set oBusComp = Me.BusComp
      Dim WshShell As Object
      ConId = oBusComp.GetFieldValue("Contact Id")
      Set WshShell = CreateObject("WScript.Shell")
      WshShell.Popup("My Custom Method was called. Here is the ID " & ConId)
      iReturn = CancelOperation
   End Select
   WebApplet_PreInvokeMethod = iReturn
End Function

WebApplet_ShowControl Event

The WebApplet_ShowControl event allows a script to modify the HTML that the Siebel Web Engine creates when it renders a control on a Web page in a Siebel application that runs in standard interactivity mode. You can use the WebApplet_ShowControl event only in a Siebel application that runs in standard interactivity mode. This event does not return any information.

Format

WebApplet_ShowControl (controlName, property, mode, HTML)

Table 28 describes the arguments for the WebApplet_ShowControl event.

Usage of the WebApplet_ShowControl Event

The HTML that the Siebel Web Engine creates depends on the following items:

• The control
• The property displayed
• The mode of the applet

The script can modify the value of the HTML argument. The Siebel Web Engine sends the modified value back to the Web browser.

To render the layout of an applet, Siebel CRM uses a Siebel Web Template (.swt) file. These files are HTML files that contain special variable tags that indicate where to render a control. To render the controls on the Web page, the Siebel Web Engine converts swe tags to HTML. Siebel CRM calls the WebApplet_ShowControl event for each swe tag after the Siebel Web Engine creates the HTML to render the control, but before it sends the created HTML back to the browser. This technique allows the scripts to modify this HTML before Siebel CRM displays it.

To display a control, you can include swe:control variable tags in the following ways:

• Use the swe:control tag by itself:

  <swe:control id="1" property="DisplayName"/>

  If the control ID is mapped to an actual control in the applet, then the Siebel Web Engine renders the DisplayName property of the control at the point where you place this tag in the template file. Siebel CRM starts the event only one time after the Siebel Web Engine creates the HTML for the swe:control tag.

• Use the swe:control tag and the swe:this tag:

  <swe:control id="1">
  .
  .
  .
  <swe:this property="DisplayName"/>
  .
  .
  .
  </swe:control>

  The Siebel Web Engine renders the DisplayName property of the control at the point where you place the swe:this tag in the template file. Siebel CRM uses the outer swe:control tag only to determine if the control ID is mapped to an actual control in the applet. Siebel CRM starts the event two times:

  • After the Siebel Web Engine creates the HTML for the swe:this tag.
  • After the Siebel Web Engine creates the HTML for the outer swe:control tag. This work occurs after Siebel CRM converts to HTML all objects that the code references between the swe:control tag and the /swe:control tag. This conversion includes objects in the swe:this tag.

    To distinguish between these two event calls, the script can examine the value of the property attribute of the tag that Siebel CRM passes as an argument to the event.

Used With

Server Script

Examples

This Siebel eScript script displays negative amounts in red in a read-only form:

function WebApplet_ShowControl (ControlName, Property, Mode, &HTML)
{
   var BC = this.BusComp();
   if( ControlName == "Amount" && Mode == "Base" && Property == "FormattedHTML")
   {
      var amount = ToNumber(BC.GetFieldValue ("Transaction Amount"));
      if (amount < 0)
         HTML = "<FONT Color=Red> " + HTML + " </FONT>";
    }
}

WebApplet_ShowListColumn Event

This event allows a script to modify the HTML that the Siebel Web Engine creates when it renders a list column on a Web page in a Siebel application that runs in standard interactivity mode. You can use the WebApplet_ShowListColumn event only in a Siebel application that runs in standard interactivity. This event does not return any information.

Format

WebApplet_ShowListColumn (columnName, property, mode, HTML)

Table 29 describes the arguments for the WebApplet_ShowListColumn event.

Usage

Usage for the WebApplet_ShowListColumn event is very similar to usage for the WebApplet_ShowControl event, except Siebel CRM uses a list column ID that is mapped to a list column in an applet. For more information, see Usage of the WebApplet_ShowControl Event.

Used With

Server Script

Example

This Siebel VB script displays negative amounts in a list in red font color:

Sub WebApplet_ShowListColumn (ColumnName As String, Property As String, Mode As String, HTML As String)

Dim amount as Double

If ColumnName = "Amount" and Mode = "Base" and Property = "FormattedHTML" Then
   If HTML < 0 Then
      HTML = "<FONT Color=Red> " + HTML + " </FONT>"
   End If
End If
End Sub

The following example is in Siebel eScript:

function WebApplet_ShowListColumn (ColumnName, Property, Mode, &HTML)
{
   if ((ColumnName == 'Amount') && (Mode == "Base") && (Property == "FormattedHTML")) {
         var val - HTML.valueOf();
         if (val < 0)
            HTML = "<FONT Color=Red> " + HTML + " </FONT>";
         }
}