Share via

Exposing Custom Events in Behavior Script Components

  • Article

Behavior script components, like Automation script components, can expose custom events that are fired inside the script component and can be handled in the containing document. An event is declared in the <public> element as in the following:

Example

<public>
   <event name="onResultChange" />
</public>

The event can then be fired by calling the fireEvent method in script:

<script language="JScript">
   // Other code here.
   fireEvent("onResultChange");
   // Other code here.
</script>

A behavior can override an element's default behavior by exposing an event of the same name as one that is already defined for the element. For example, a behavior that exposes an onclick event can override the element's default onclick event.

Getting and Setting Custom Event Information

Your custom script component event can get access to the DHTML event object, which maintains event-specific information. You can use this object to:

  • Change existing event object properties, such as keyCode, that have been set by in the calling event.

  • Create new (expando) properties of the event object in order to pass information about your event back to the containing event.

In your script component code, call the createEventObject method to create a new instance of an event object, and then set one or more properties on the new event object. When you call the fireEvent method, you can pass the new event object with the event name.

To create a new expando property, simply name it when assigning its value in your script. The following shows how you can create a new property called myprop for the event object:

oEvent = createEventObject();
oEvent.myprop = "a new value"

Note

You can create expando properties only if you are using Microsoft® JScript® (or JavaScript). This feature is not supported in Microsoft® Visual Basic® Scripting Edition (VBScript).

Example

The following script component fragment is derived from a calculator script component sample. The sample defines a custom onResultChange event that is fired to the containing document whenever the result changes. Event-specific information (the actual calculation result) is passed via the expando property called result.

Note

A CDATA section is required to make the script in the <script> element opaque. For details, see Script Component Files and XML Conformance.

<public>
   <event name="onResultChange" />
</public>

<implements type="Behavior">
   <attach event="onclick" handler="doCalc"/>
</implements>

<script language="JScript">
<![CDATA[
function doCalc()
{ 
   // Code here to perform calculation. Results are placed into
   // the variable sResult.
   oEvent = createEventObject();
   oEvent.result = sResult;
   fireEvent("onResultChange",oEvent);
}
]]>
</script>

The following shows what the containing page looks like. When the onResultChange event fires, the results of the calculation are extracted from expando property result of the DHTML window.event object and displayed in the resultWindow <DIV> element.

<HTML>
<HEAD>
<xml:namespace prefix="LK" />
<style>
   LK\:CALC {behavior:url(calc.wsc)}
</style>
<script language="JScript">
function showResults(){
   resultWindow.innerText=window.event.result;
}
</script>
</HEAD>

<LK:CALC id="myCalc" onResultChange="showResults()">
<TABLE>
<TR>
   <DIV ID=resultWindow 
      STYLE="border: '.025cm solid gray'" 
      ALIGN=RIGHT>0.</DIV>
</TR>
<TR>
   <TD><INPUT TYPE=BUTTON VALUE=" 0 "></TD>
   <TD><INPUT TYPE=BUTTON VALUE="+/-"></TD>
   <TD><INPUT TYPE=BUTTON VALUE=" . "></TD>
   <TD><INPUT TYPE=BUTTON VALUE=" + "></TD>
   <TD><INPUT TYPE=BUTTON VALUE=" = "></TD>
<TR>
</TABLE>

</LK:CALC>
</HTML>

See Also

Concepts

Exposing Properties and Methods in Behavior Script Components