Implementing client-side events using the BrowserTextControl

Blogged by Björn Meyer on July 11, 2008 and tagged with Sample, .NET Server.

When building a browser-based word processing application using TX Text Control .NET Server, the BrowserTextControl is wrapped in a Windows Control Library. This provides many advantages including the fact that most of the functionality can be wrapped in the user control and must not be implemented from outside using Javascript or any other client-side scripting language.

However, we are building web applications! Today's web applications are built using client-side scripting for different purposes like an AJAX implementation or the client-side communication between different integrated controls.

By implementing the events in the wrapper control, you can trap them inside of the control that is isolated in the web page. The browser is not able to access these events, though.

But trapping such an event using client-side Javascript could be really helpful. Consider the following example:

You implemented a function to save the content of the BrowserTextControl to post it to the server using HTTP POST like described in our documentation. This client-side call should be triggered by the wrapper control when the user clicks a specific button or menu entry. On this action, the wrapper control should fire an event that can be trapped client-side using Javascript to call the implemented save function.

Sounds good! But how to implement that?

Due to an article in the asp.netPRO magazine from Steve C. Orr, an expert I hold in great respect, it is not possible to raise events back to the page:

BTW: I honestly recommend to read this article completely, it perfectly describes the methodology behind this technology.

"[...] Another issue is that communication between client-side script and Windows controls is currently one-way only. That is, JavaScript functions within the page can call methods of the hosted Windows control, but the Windows control cannot raise events back to the page. [...]"

From what we have learned above, this statement is true. Anyway, there is a way to get around this catch-22 situation.

The Internet Explorer accesses the Windows Control Library properties and methods using the implemented COM interface that enables Internet Explorer to execute client-side controls like ActiveX controls, Flash players or our .NET assembly. This doesn't imply that this approach uses COM or ActiveX technology. The Internet Explorer simply uses the existing interface to handle everything that is between <OBJECT> and </OBJECT>. This is the reason why the 'Make assembly COM-Visible' checkbox must be checked in the assembly properties.

To implement a public COM-visible event, it is required to create a COM-interface in the wrapper control:

[ComVisible(true), InterfaceType(ComInterfaceType.InterfaceIsIDispatch)]
public interface BrowserApplicationEvents
{
	[DispId(0)]
	void SaveDocument();
}

This visible interface enables the client-side Javascript to trap our events. Then you need to identify a list of interfaces that are exposed as COM event sources in your wrapper class:

[ComVisible(true), ClassInterface(ClassInterfaceType.AutoDispatch), ComSourceInterfaces(typeof(BrowserApplicationEvents))]
public partial class BrowserAppControl : UserControl
{ ... }

The event itself can be implemented to any event in .NET:

public delegate void SaveDocumentHandler();
SaveDocumentHandler saveDocument;

public event SaveDocumentHandler SaveDocument
{
    add { saveDocument += value; }
    remove { saveDocument -= value; }
}

protected virtual void OnSaveDocument()
{
    SaveDocumentHandler handler;
    handler = saveDocument;

    if (handler != null)
        saveDocument();
}

This event is now publicly accessible for client-side scripting languages:

<script for="BrowserApp" event="SaveDocument" language="javascript">
	alert("In Javascript client-side event, you can call the client-side save method.");
</script>

Feel free to contact me, if you would like to learn more about this approach.

Download the sample code here