Customizing ActiveX Control Properties

Built-In Controls

• Window Object
  • Frames Object
  • Location Object
  • History Object

• Document Object
  • Color
  • Anchors
  • Links
  • Forms
  • Location
  • LastModified
  • Title
  • Referrer
  • Talking to the Document
    • Document.Write
    • Open/Close
• Control Attributes and Parameters
  • Attributes—ID, ClassID, Data
  • Parameters
• Summary
• Q&A
• Workshop
• Quiz

Chapter 18

Customizing ActiveX Control Properties

By now you should have a strong familiarity with the processes involved in inserting objects into an HTML document and ensuring that those objects are verifiably intact (or trusted).

In this chapter, you will learn more about what ActiveX controls are, what they can do, and how to make them do it. This chapter covers

• The controls that come with the Internet Explorer
  
  
• How to manipulate options (or parameters) available with the different ActiveX objects
  
  

Built-In Controls

Day 15, "What Is an ActiveX Control?" discusses the COM and DCOM models for object-oriented programming. The DCOM model provides the programmer with a hierarchical, standard set of objects that would be found in an intranet-connected machine. Programmers can manipulate the properties of these objects to enable customized networking features within their applications.

This hierarchy follows the structure shown in Figure 18.1. I refer to this structure as the Object Model for Scripting and the Internet Explorer Object, interchangeably. For a full explanation of each of the objects in the hierarchy, you should refer to the documents in the ActiveX SDK under \INetSDK\Help\ScriptOM\.

Figure 18.1. The Object Model for Scripting.

To easily identify the objects within the Object Model for Scripting , naming conventions are quite valuable. By naming your objects in a consistent manner, you can easily tell what type of object something is.

Using the conventions in the following table, you can have many separate instances of a given object in use at the same time. You will still be able to refer to each of them directly, and in a way that makes sense to someone who is not already familiar with your code.

---

Note
Naming conventions are not written in stone. These are provided as a guide. If you (or your supervisor) have a preferred way of naming your objects, go ahead and use that. The important thing is that each name be unique and that they follow some sort of convention.

---

Table 18.1. Object Model naming conventions .

---

Hint
Throughout this chapter, you will see several examples of how to reference the various objects built into the Explorer model. You can use the ActiveX Control Pad, included on the enclosed CD-ROM, to explore these features—the way they were meant to be used.
The control pad has the different objects, properties, events, and methods built into its artificial intelligence engine. This enables it to prompt you, through the use of wizards, in the steps for referencing and manipulating the objects built into the Explorer. It also gives you a way to use other controls that are plugged into your system registry.

---

Window Object

The topmost object within the Object Model For Scripting is the Window object. The Window object is the container within which programs or scripts will run. This is the primary object against which you will be programming. The "window" to which it refers is the main window of your Web browser.

If you wanted to refer to an object such as the current location or URL, within the current window, you would address it as follows:

window.location.href

Extending this out,

window.location.href="http://www.domain.net"

or

location="http://www.domain.net"

would set the location.href of the current window to www.domain.net.

Notice that the default parent of this Location object is the Window object and the default property of the Location object is href.

---

Hint
Multiple windows may be visible at any one time. If you wished to refer to the current window, you would not have to specify to which window object you are referring, so

window.location.href="http://www.domain.net"

is the same, for our purposes, as

location.href="http://www.domain.net"

---

By assigning the window a name, you can make your code easier to read by adding something like this:

window.name = "wDomain"

Then you could refer to it elsewhere in the program like this:

wDomain.location.href="http://www.domain.net"

Just like people, objects within the Internet Explorer Object can be referred to in many ways. Each has its own name, as well as other ways to refer to it that are relative to the context in which they are used.

A window's parent is the window within which it was created. Thus, if you have a window named wChild, and it is contained within a frame that is in is contained within a top-level window named wParent, it would have the full name:

wParent.frFrame.wChild

If you were to have a bit of script within wChild that addresses its parent, you could refer to it as wParent or wChild.Parent. If you wanted to refer to the topmost window, you could use the property Top and refer to it as wChild.Top. There are other context-relative properties defined in the Object Model for Scripting, such as Self, that work in a similar way.

---

The Window Object
window.[*]

The Window object refers to browser window. If no Window object is specified, the current window is assumed. This object contains all the objects in the Object Model for Scripting.

Example:

strURL=Window.location

and

strURL=location

Both of these will set the value of strURL to the location of the current window.

Frames Object

The Frames object is a property of the Window object. Some Web pages make use of a type of window display known as frames that enables the display of several different Web pages within one window. (See Figure 18.2.) Since several frames can be used within one window, the Frames object is used as an array.

Figure 18.2. Frames allow the display of multiple Web pages within one window.

When a browser loads a page with frames, a hyperlink can instruct the client browser to change one or more of the pages, while leaving the other pages intact.

---

DO remember to use Frames(0) to refer to the first frame.
DON'T use Window.Frames(1) to refer to the first frame.

---

---

DO remember to use the plural form, Frames.
DON'T use the singular form, Frame, since there should never be only one frame within a window if frames are used on a page.

---

When you reference Window.Frames(x) within a script or program, what it will return is not a name or label or anything like that. It returns an entire Window object. If you want to reference the URL of the document in the second frame of a window, you would phrase it like this:

wWindow.frFrames(1).Location.href

In this way you are, for all practical purposes, treating the wWindow.frFrames(1) object as a Window object.

---

The Frames Collection Object
window.frames()

The Frames Collection object references any of the frames in a given window. Each frame in a given window is numbered consecutively, beginning with the first one, numbered "0" rather than "1".

Example:

Window.Frames(0)
would refer to the first frame and

Window.Frames(1)
would refer to the second frame.

---

Location Object

Another important property of the Window object is the Location object . Providing more than just the simple URL, this object enables you to use several powerful features that would not otherwise be available through straight HTML. This includes the capability to reference the port on which the connection is accepted, and the full filename of the specific file that was returned (if it had one).

---

The Location Object
window.location

The Location object references each of the parts of a URL, including:

Parameter Description

HRef The complete URL

Protocol HTTP, FTP, and so on

Host The local hostname of the computer

HostName The full host and domain name

Port The TCP/IP port of a connection

PathName The full filepath on a host

Search Any search parameters specified in the URL after a ?

Hash Any index parameters specified in the URL after a #

Example:

strURL=Window.Location.HREF

would return the full URL of the current window.

---

Warning

The Hash and Search properties always return the question mark (?) or pound sign (#) along with the parameter. Thus if you set the variable strMyString to the value within a Hash property, it will return something like #Place instead of just Place.

---

History Object

A really great property of the Window object is the History object . A simple line like

window.history = intX

will set the variable intX to the number of pages that were accessed by the browser window (or window frame).

This object has two particularly powerful methods, Back and Forward. These enable you to tell the browser to go back to a previous page, or forward (if you have already gone back one or more pages).

Unlike the Frames() property array, the number in the history starts counting with 1=1. If no pages have been accessed yet, the value of the history property will be set to d.

Another method of the History object, Go, enables you to select a specific site in the history and jump to that page. The format for this would go something like this:

Window.Go 5 'Assuming there are at least 5 sites in the history.

---

The History Object

Window.History

The History object references each or all the sites visited during the current session of the browser (even longer with some browsers). The length of the list can be determined through the aptly named Length property.

Example:

intHistList = Window.History.Length

would return the total number of sites loaded during the current session of the browser.
The browser can be commanded to go backwards and forwards in this list, using the Back and Forward methods.

Window.History.Back

would load the previously loaded page.

Window.History.Forward

would load the page previously backed up from.
If you already know which history item to which you wish to go, you can specify it with the Go method:

Window.History.Go 3

---

Document Object

The most important (and complex) property of the Window object is the Document object. This is where the actual content of a Web page resides. The next sections go into some of the details of Object properties so that when you are done with the sections, you will be able to program with the properties.

Color

A group of properties (LinkColor, aLinkColor, vLinkColor) enables you to customize the color in which hyperlinks will appear. You can use BGColor and FGColor to customize the color of the background and foreground, respectively, of the document as a whole.

For example, you can set the background color of a page to all black using either the following format:

wWindow.docDocument.BGColor="Black"

Or, if you are referring to a document within the current window:

docDocument.BGColor="Black"

Several different color names are supported by the Explorer Object Model including black, white, and gray; the primary colors red, yellow and blue; and several tertiary colors such as green and orange.

Anchors

The Anchors property of the Document object returns an array of all the hyperlink anchors within the document. Anchors are the pages and locations, referenced within the document, to which a user may jump.

An anchor, as typed within an HTML document would look like this:

<a href="http://www.domain.net">Jump to Domain Network</a>

To reference the third anchor within an HTML document, your code would look something like this:

document.anchors(2)

This property would return a Window object containing the properties of the referenced page.

Links

The Links object is another property array of the Document object . It is very similar to the Anchors object, but it returns all the hyperlinks within a document.

Forms

The Forms object , also, is an array. Just what a Forms object is could be confusing to anyone familiar with Visual Basic or other Windows Programming language since a form in Windows is not the same as a form in HTML. In HTML, which is the context used here, a form is an item such as a check box or a list box or other user input item.

---

The Forms Collection Object
Window.Document.Forms
The Forms collection object references an array of all the HTML forms in the current document. The length of the list can be determined through the aptly named Length property.

Example:

intFormList = Window.Document.Form.Length
would return the total number of HTML forms in the current document.

Window.Document.Forms(0)

would return the first HTML form in the current document.

---

Location

The Location object is a property of the Window object , into which we will go into some detail. It is very powerful for determining and/or setting the various options for accessing a given site.

You should know that a URL consists of several parts, even though it is presented as one long string, such as

http://www.domain.net/directory/filename.ext:80

In the Location object, these can be set or retrieved using the following properties:

There are two other properties, Hash and Search, that apply to special features of an HTML document or CGI script that I do not go into here. (Again, for full explanation of those objects, refer to the document "Object Model For Scripting" in the ActiveX SDK.)

LastModified

The LastModified property of the Document object is just what it appears to be—the date when this file was last saved. There are currently a variety of methods used by Netscape and others, who use <META> tags that are not part of the HTML standard, to enable the author to set this date. For now, until and unless the W3 Consortium decides to adopt another standard, this property is obtained from the file date of the specific file on the server.

Title

The Title property of the Document object is obtained from within the HTML document itself. It is set by the author of the HTML file by enclosing it within the <TITLE> </TITLE> container tag. Should the author neglect to assign a title to a document, the Title property will return an empty string, "".

Referrer

The Referrer property of the Document object is a very interesting item. It provides the ActiveX programmer with a method of determining how the user found your page. A command line such as

strSource = document.referrer

would return the URL of the page that had a hyperlink that took the user to your page. If you track this information, and are listed with a service such as Yahoo! or WebCrawler, you can tell how often a user was referred by one of them, or if they were referred by a link in some other company's or user's page.

If the user got to your page by typing the URL in directly, this property will return a NULL value.

---

Meta-Information
Not to be confused with the <META> tag, meta-information is certain to be one of the most valuable types of information with which companies developing an Internet presence could work. This is the beginning of what is hoped to be the Information Age.
Internet-acquired information comes in three major forms. First, some companies want a presence on the Internet so that they can put their products into a new vehicle for distribution, such as online ordering. Second, some companies want a presence on the Internet so that they can get information about the people that are interested in their products. The third major form of information is meta-information, or information about information.
You have heard the old question, "Who watches the watchers?" This is meta-information. Companies such as Dallas-based Intactix or New York City-based Paradysz Matela & Co. market this type of information-about-information quite successfully. Meta-information can tell you where, when, why, or how information is acquired—regardless of whether the information is about babies, ballet, bandages or bullets.
You can take a—sometimes very large—database and give the user meta-information about that database. Some of this information could answer questions such as, "In what states do my users live and work?" or "How much does my average user spend on online services?" or "Do products in green packages sell better on the top shelf, or the bottom?"

 

Talking to the Document

The next thing you need to know is how to tell the document what it will tell the user. This is where GIGO (Garbage In/Garbage Out) comes into play. The coolest interface in the world cannot hide bad content. Since I am discussing the interface and not the content, I won’t go there.

In the following sections you will review a couple methods for sending content, whatever the quality, to the user through the document.

Document.Write

By using the Document.Write method , you can have your application create the content of an HTML page on-the-fly. This written text will not be saved to the copy of the HTML page, but rather, it will be simply added to the local copy of the page, as viewed by the client browser.

---

The Document.Write Method
Document.Write [string]

The command Write is used to write a character string to a document. The string will be entered into the current position in the document.
It uses one string value parameter to specify the text that should be written. This parameter can be a named variable, like strMyVariable or it can be the actual text string, enclosed in quotes like this: "My Paragraph".

Example:

Document.Write "My Paragraph"

This example would write the text "My Paragraph" to the document.

---

Example:

strMyString = "Hello world!"
Document.Write strMyString

This example would write the text "Hello world!" to the document, since that is the value of the variable strMyString.

Open/Close

Before you can write to a document , you need to open the document for editing and then close it again. Thus, to perform the Write action shown in the preceding section, you would have to have to format it something like this:

Document.Open
Document.Write "Hello World!"
Document.Close

Control Attributes and Parameters

Now that you have learned a little about the built-in objects within ActiveX we will refer, again, to the <OBJECT> tag. In earlier chapters you learned how to insert objects, and even a little about customizing their size with the Height and Width keywords. The next section gets a little deeper into the parameters that are used to customize other control features.

Attributes—ID, ClassID, Data

Every object that is inserted into an HTML page should have an ID attribute . This is the unique name that will be used within the HTML page, and any script within the page, to identify it. This name should follow the conventions set forth in the previous section.

If the object is an OLE object (such as an ActiveX control), it should also name the ClassID attribute for the object. As you remember, the ClassID is the unique name used within the local machine to identify the object within the registry. Although the HTML author determines the ID, the ClassID is set by the control.

No two controls should ever have the same ClassID so that they can all be identified by their individual ClassIDs. If you have two different timers, for example, and each has different behavior, you can refer to each of them by its unique ClassID rather than by easily confused names like "Timer" and "IETimer."

Finally, the <OBJECT> tag should identify the data that the object will use. This Data attribute can be identified by using one of two methods.

The first method points to the URL where the data is stored:

Data = [URL]

The second method is to put the actual data within the Data attribute of the <OBJECT> tag:

Data = "data:[MIME Type];[Data]

Now, let's bring these properties of the <OBJECT> tag together to see how they will work.

<OBJECT
ID=objMyTextBox
ClassID="clsid:12345678-1234-1234-1234-123456789012"
Data="data:text/txt:Hello world">

This <OBJECT> tag would insert an object called objMyTextBox into the document. The ClassID is a pretend one, but it follows the format for a real one. The data that would be used to initialize the control is contained in the Data parameter, and is identified as the MIME type text/txt. The actual data is simply the phrase, Hello world.

The HTML <OBJECT> Container Tag <OBJECT
ID = [Object Name]
WIDTH = [Pixels 0 - 800]
HEIGHT = [Pixels 0 - 600]
CLASSID = "CLSID:hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh"
CODEBASE = [URL FilePathName]
Type = [MIME Type]
Data = [String of Data]
>
<PARAM
NAME=[Variable Name]
VALUE=[String Value]>
</OBJECT>

Parameters

Summary

In this chapter you have learned something about the Object Model for Scripting, or the Internet Explorer Object. This is the basic structure against which ActiveX Controls operate. It has several properties, most of which are entire objects unto themselves.

The main (or topmost) object is the Window object. Each Window object contains several objects, including the Frame, History, Navigator, Location, Script and Document. Not all of these objects are applicable to every single instance of the Window object.

The most significant subsidiary object (or property) of the Window object is the Document object (also called the DocObject). The Document object contains the actual content of a Web page. It is also composed of several objects, including the Link, Anchor, and Form objects.

You also should have a slightly better understanding of the <OBJECT> tag; most importantly, the Data attribute. Using this attribute, you can specify the persistent data with which an ActiveX control is loaded. Using this attribute, you can reference one control and have it instantiated many times, with a different purpose on each instance.

For more information on instantiation of ActiveX OLE controls, as well as other ActiveX OLE information, please see Chapter 21, "Creating an ActiveX Control," and the Microsoft Developer’s Network Level 2 Documentation.

Q&A

• Q How did Microsoft come up with the Object Model for Scripting as it is used in the Internet Explorer Object?
  
  
• A The Object Model for Scripting is based on the World Wide Web Consortium's Working Draft titled, "Inserting Objects into HTML" (http://www.w3.org/pub/WWW/TR/WD-object). This specification was developed in cooperation with Microsoft, Netscape, Sun Microsystems and others with a great interest in the growth of the World Wide Web. It provides the basis under which ANY object can be inserted into a Web page, including Java applets, ActiveX Controls, and similar OLE components.
  
  
• Q I have heard of the <INSERT> tag from HTML 2.0. When did it become the <OBJECT> tag and why?
  
  
• A HTML 3 introduced the <OBJECT> tag in response to market demand for a more object-oriented approach to Web page design. Programmers who are familiar with Object-Oriented Programming will appreciate the added power, provided by this interface, in activating their Web pages and Internet applications.
  
  
• Q I invest a lot of time and money in learning Internet technologies, only to have them change at every turn. If I create Web pages and applications based on this changed tag, will I have to relearn everything—again?
  
  
• A Change is a difficult thing on which to keep a handle. The only thing definite about Internet technologies is that they WILL change. However, the folks who are making these changes do so only to enhance what was previously there. Apologies aside, they make extensive use of backwards compatibility. If you go through the trouble of integrating these new, powerful features into your own project, you can rest assured that each modification of the standard will incorporate some degree of backwards compatibility. In most cases this means you will need to perform little or no redesign of your applications—unless you want to incorporate whatever NEW features are added.

Workshop

Create a Web page using the <OBJECT> tag and its Data parameter. Make this object a text box, and using the Data parameter, fill the text box with some sort of text, such as Hello World!.

Quiz

1. What is defined by the Object Model for Scripting?
   
   
2. What naming conventions (that is, prefixes) are used for the following objects:
   
   
   1. Document
      
      
   2. Window
      
      
   3. Script
      
      
   4. Frames
      
      
   5. Form

1. What is the topmost object within the Object Model for Scripting?
   
   
2. Which object array allows the display of several Web pages within one Window?
   
   
3. What attribute of the <OBJECT> tag provides a way to assign a unique name for each object?
   
   
4. What number is used to reference the first frame of a frames array?
   
   
5. What property of the Window object is used to reference previously displayed documents?
   
   

   Questions 5-7 refer to Location object, using the following URL as an example:
   
   http://www.domain.net/directory/subdirectory/filename.ext:80

6. What property would return with 80?
   
   
7. What property would return with www.domain.net:80?
   
   
8. What property would return with www.domain.net?