Custom Tag Definition
Structurally, a custom tag is a file with an HTC extension that describes its properties, methods, and events between <PUBLIC:COMPONENT> and </PUBLIC:COMPONENT>.
To define a custom CHECKBOX tag, we create a file checkbox.htc as in the following snippet where the first line sets the tag name of the component:
<PUBLIC:COMPONENT NAME="cbx" tagName="CHECKBOX">
<PROPERTY NAME="value" GET="getValue" PUT="putValue" />
// Here we place all other properties of the component
<METHOD NAME="show" />
// Here we place all other methods of the components
<EVENT NAME="onItemChanging" ID="onItemChanging"/>
// Here we place all other events that component will fire to application
<ATTACH EVENT="oncontentready" HANDLER="constructor" />
// Here we place all other events that component handles itself
<SCRIPT >
// Here we place all methods, properties getters and setters and event handlers
</SCRIPT>
</PUBLIC:COMPONENT>
Custom Tag Use Case
While the contents of the HTC file matter a lot, the name of the file is irrelevant, although, ultimately, the URL to the HTC file needs to be specified using the IMPORT instruction. It has to be done before the corresponding custom tag is mentioned for the first time (on the page). Here is how the simplest possible page utilizing a custom checkbox might look, assuming the page and the HTC file are located in one folder:
<HTML xmlns:myns>
<?IMPORT namespace="myns" implementation="checkbox.htc" >
<BODY>
<myns:checkbox id='cbx_1' label='Hello'/>
</BODY>
</HTML>
Please notice how custom CHECKBOX has been mapped to a nondefault namespace "myns" in the opening HTML tag. The IMPORT instruction performs a synchronous load of the HTC into the browser's memory and also instructs the browser how to perform name resolution for the appropriate namespace (HTC to namespace association can be many-to-one).
Constructor of the Custom Tag
The best way to initialize HTC, once it's loaded, is to process the "oncontentready" event. Accordingly, we define a handler function, which for sheer clarity is called constructor:
<ATTACH EVENT="oncontentready" HANDLER="constructor" />
The logic of constructor() is simple: concatenate a regular HTML checkbox and HTML label in the order dependent on the value of property labelonleft (see property definition below):
function constructor() {
// We will add an HTML checkbox and label to the element body
// See Listing 2 for details
}
Defining Custom Tag Properties
To define property labelonleft, we add one more line to the <PUBLIC:COMPONENT> section:
<PROPERTY NAME="labelonleft" VALUE="true"/>
Please note that this property does not contain getter and/or setter methods. Properties onValue and offValue that provide the mapping of the checkbox status into a business value domain also don't need getters and setters:
<PROPERTY NAME="onValue" VALUE="true"/>
<PROPERTY NAME="offValue" VALUE="false" />
However, property checked is defined with both getter and setter:
<PROPERTY NAME="checked" GET="getChecked" PUT="putChecked" />
Accordingly, we have definitions for both methods in the <SCRIPT> section. As you can see, setter putChecked(), which is triggered every time checked is modified, sets the value property to one of two variants: onValue or OffValue. Please note that putChecked() will get triggered not only by the script on the checkbox-hosting page, but also by any assignment to checked done inside this very checkbox.htc.
var _value;
function putChecked( newValue ) {
value = (newValue?onValue:offValue);
}
function getChecked(){
return ( _value == onValue);
}
Defining Events for the Custom Tag
Let's look at the definition of onItemChanging and onItemChanged events and how these events are being fired and processed inside the setter for value property (see Listing 2).
Method putValue() has a couple of points of interest. First, it can be called during the parsing on the CHECKBOX tag, as long as the HTML value attribute is specified. That's why we have a separate logic branch for not constructed objects, to differentiate the process of construction from a reaction to a user click. Second, we illustrate here the creation and processing of the custom event onItemChanging, which allows the application to cancel (block) the action. Please note that both clicking as well as programmatic assignment to the value can get cancelled this way.
Event Canceling
To cancel the event, an application should intercept the event and set event.returnValue to false. The schematic snippet of code illustrating how the application would cancel the processing is presented below:
cbx_1::onItemChanging() {
. . . . .
if (canNotBeAllowed) {
event.returnValue=false;
. . . . .
}
If the event is not cancelled, putValue() sets the internal, plain HTML checkbox's checked property as per the current value: if that is equal to onValue, the internal checkbox will get checked; if it is equal to offValue (there is no third option), unchecked (the full listing is presented in Listing 2).
HTML Internals of the CHECKBOX
The painting of our control is done by the helper functions addLabel() and addCheckBox() and is called from within a constructor(). These functions inject HTML inside the element's innerHTML (element is the analog for this in HTC parlor). The injected HTML, in the simplified form, looks like the following:
<LABEL for=cb_{uniqueID}>Show Details:</LABEL>
<INPUT id=cb_{uniqueID} type=checkbox />
where uniqueID is a unique (within a page) string literal generated by IE, which identifies the instance of the HTC.
Subscribe to Open Source Magazine Email News Alerts
Subscribe via RSS
