Embedding Carapace Objects in a Web Page

Microsoft's browser InternetExplorer can display COM objects and ActiveX controls using the <OBJECT> tag. This means the Carapace Emulator -- which is an ActiveX control -- can appear on Web pages. Click here for an example web page which contains the Carapace Emulator.

Similarly, ordinary COM objects created with Carapace script can be embedded on a web page. This is useful since the scripted object can then modify the web page eg. modify buttons, fill tables etc.

There are 3 parts to manipulating the web page from a COM object:

• include the object on the web page
• give the object access to the page
• modify the page content

Including an Object on a Web Page

The OBJECT HTML tag is used to include a COM object on a web page eg.

<OBJECT
    CLASSID="CLSID:E3F4F5F6-C297-11D3-81CA-0050048C7269"
    ID="MyObject"
    >
</OBJECT>

In order for that object to modify the HTML page, the object must be given a reference to the containing HTML page.

Giving the Object access to the Web Page

All access to the web page is via the OLE container -- eg. via InternetExplorer. A Carapace COM object which offers the following interface will be given a reference to the OLE container.

Interface:

The set method is called automatically by the web page when embedding the object. The script can then call the get method to retrieve the Unknown reference to the container. The container method on this Unknown object is then used to get the Dispatch interface onto the container -- when InternetExplorer is the OLE container, this dispatch interface is IHTMLDocument2 which gives access to the entire Document Object Model (DOM).

This dispatch interface can then be used to modify the contents of the web page.

set

Set the container reference ie. store the reference to the OLE container. This is the IUnknown pointer to the container.

This must be the first function on the interface.

Arguments:

Return type: the empty List ()

get

Get the container reference. If present this should return the IUnknown pointer for the container.

This must be the second function on the interface.

The dispatch interface onto the OLE container can then be retrieved from this Unknown pointer using the container method eg.

    (set dispatch (unk.container))

When Microsoft's web browser InternetExplorer is the OLE container, this dispatch interface is the IHTMLDocument2 one which gives access to the entire Document Object Model (DOM).

Arguments: none

Return type: Unknown or the empty List ()

Modifying the Web Page Content

Having obtained the Dispatch interface for the OLE container, this can now be used to modify the web page. For instance, if InternetExplorer is used, this dispatch interface is IHTMLDocument2 which is described in the type library called Microsoft HTML Object Library (Ver 4.0).

For example, if browser is this Dispatch interface, the following script fragment sets the background colour:

    (browser.bgColor "lightgreen")

    function buttonColour (id, col)
    {
        btn = document.all[id];

        btn.style.backgroundColor = col;
    }

    (browser.execScript "buttonColour('connect', 'red')")

Hint:

To do anything complicated on the web page from Carapace script, the simplest way is to write a JavaScript function to manipulate the page and then to invoke it from within the Carapace object using the execScript dispatch method.