All interfaces for accessing the Dynamic HTML (DHTML) Object Model are based on IDispatch and are the basis of access to the object model that is also used by scripts. It is therefore important that anyone using the interfaces to manipulate the object model also be familiar with the structure and functionality as defined in the Dynamic HTML overview and in the object model references included in MSHTML.
The Interfaces and Scripting Objects section of the MSHTML Reference shows how objects within the DHTML Object Model map to the interfaces. For example, using this map, you can see that the IHTMLDocument2 interface maps to the document object. Further examination of the interface shows how the properties of the document object are available through get_ and put_ methods. The object's methods map to methods available in the interface, and events can be hooked up using standard OLE Automation connection points.
Examples of how to use the object model interfaces are demonstrated in the colbtn, Driller, and WalkAll samples in the Internet Client Software Development Kit (SDK).
Usually, anything that can be done using script within the document can also be performed using the interfaces to manipulate the object model. It is therefore recommended that before writing code to use the object model interfaces, developers should prototype the functionality using script within an HTML document.
The following HTML example shows how to navigate the all collection of the document and obtain the tag name of each element in the document using script. The equivalent Microsoft® Visual C++® code is demonstrated in the Driller and WalkAll samples in the Internet Client SDK using the object model interfaces.
<HTML> <HEAD> <TITLE>Page Title</TITLE> </HEAD> <SCRIPT LANGUAGE="JavaScript"> function Loaded() { var c = document.all.length; var i; for(i=0; i < c; i++) { spanTAGS.innerHTML = spanTAGS.innerHTML + document.all.item(i).tagName + "<BR>"; } } </SCRIPT> <BODY onload="Loaded()"> <SPAN id="spanTAGS"></SPAN> </BODY> </HTML>
To start using the object model interfaces, you need to obtain the IHTMLDocument2 interface for the document. Once you have this interface, you can access all the elements within the document. How the document interface is obtained depends on how your application is being implemented. Each of the following scenarios requires that the document interface be obtained in a different manner.
When hosting an MSHTML object, you create the object using CoCreateInstance. Once the object is created, you can call its IUnknown::QueryInterface method, requesting IID_IHTMLDocument2. The WalkAll sample in the Internet Client SDK demonstrates how to do this.
When hosting the WebBrowser control, perform the following steps to obtain the document pointer:
The Accessing Dynamic HTML section of the ActiveX Controls documentation explains how to obtain the document interface from an ActiveX control.
Once you have obtained the document interface, you can use any of the IHTMLDocument2 interfaces to obtain or modify the document's properties. This will most commonly involve getting some of the IHTMLElementCollection interfaces for the different element collections contained in the document.
A very common collection is the all collection. The all collection is obtained using the IHTMLDocument2::get_all method. This method returns an IHTMLElementCollection interface that contains all the elements in the document. You can then enumerate the elements using the IHTMLElementCollection::item method. The IHTMLElementCollection::item method provides you with an IDispatch pointer that you can call IUnknown::QueryInterface on, requesting IID_IHTMLElement. This will give you an IHTMLElement interface pointer that you can use to obtain or set information for the individual element.
Most elements provide an interface for working with that specific element. These element-specific interface names take the format of IHTMLXXXXElement, where XXXX is the name of the element. To obtain the element-specific interface, you simply call IUnknown::QueryInterface on the IHTMLElement interface, requesting the element-specific interface that is desired. For example, the IMG element provides an IHTMLImgElement interface that can be used to work with the IMG element specifically. For a list of the available element-specific interfaces, see the interface listing in MSHTML.
In addition to displaying Web pages and running DHTML scripts, Microsoft® Internet Explorer 5 includes a component that provides DHTML editing. You can quickly and easily build applications that allow users to perform the following functions:
For example, if you are creating a Web-based workflow application, you can use the DHTML Editing component to build document editing right onto a Web page.
Internet Explorer provides DHTML editing capability at two levels:
The easier way to provide DHTML editing is to use the ActiveX control. You can add the control to any host environment that supports COM objects, including Microsoft® Visual Basic®, Visual C++, and Microsoft® Visual J++. You can also write script against the editing component on a Web page.
The ActiveX control provides a basic WYSIWYG editing surface. You can control the editing environment using properties, methods, and events on the control. You can easily add menus and toolbars to expose built-in formatting commands. The control also includes built-in support for:
The control is available in two versions: one that is marked safe for scripting and another that is not marked. The safe-for-scripting version is downloaded without a warning, regardless of the user's security setting. (It therefore doesn't support loading and saving files directly; you must provide your own method for posting changes to the appropriate location.) The unsafe-for-scripting version is useful in stand-alone applications. For more information about using the DHTML Editing ActiveX control, see DHTML Editing Component.
If you are familiar with programming OLE document objects in C++, you can implement DHTML editing using the DHTML editing document object. The document object provides a few features not supported by the ActiveX control, including:
Internet Explorer 5 exposes two document objects through two libraries: Mshtml.dll and DHTMLEd.dll. Both expose the standard OLEExec and QueryStatus interfaces to control the editing environment, using various commands that you can pass to each interface.
Mshtml.dll exposes the complete base document object, which includes all editing commands supported in the standard browser. DHTMLEd.dll excludes a few of the lesser-used commands, but adds support for: