PUBLIC:PROPERTY Element

Defines a property of the HTML Component (HTC) to be exposed to the containing document.

Syntax

<PUBLIC:PROPERTY
    GET = "sGetFunction"
    ID = "sPropertyID"
    INTERNALNAME = "sInternalName"
    NAME = "sName"
    PERSIST = "bPersist"
    PUT = "sPutFunction"
    VALUE = "vValue"
/>

Attributes

GET
Optional. String that specifies the function to be called whenever the value of the property is retrieved. A PUBLIC:PROPERTY element that specifies a GET attribute without specifying a PUT attribute is a read-only property.
ID
Optional. String that uniquely identifies the PUBLIC:PROPERTY element within the component. This attribute is analogous to the ID attribute in Dynamic HTML (DHTML).
INTERNALNAME
Optional. String that specifies the name by which the property is referred to within the component. This internal name must be declared globally before it can be referenced anywhere in the component; otherwise, a scripting error occurs, indicating that the name is undefined. If no internal name is specified, the NAME attribute is used by default.
NAME
Required. String that specifies the name of the property exposed to the containing document. By default, the NAME specified is also used to refer to the property within the component, unless an INTERNALNAME attribute is specified.
PERSIST
Optional. Boolean that specifies whether to persist the property as part of the page.
PUT
Optional. String that specifies the function to be called when the value of the property is set. A PUBLIC:PROPERTY element that specifies the GET and PUT attributes is a read/write property. Failure to specify a GET function, when a PUT function is specified, causes the property to be write-only, which often might not be desired.
VALUE
Optional. Variant that specifies the default value for the property.

Methods

propertyID.fireChange()
Notifies the containing document that the value of the property has changed by firing the onpropertychange event on the element. If no PUT attribute is specified on the property, the onpropertychange is automatically fired when the property is set in the containing document.

Element Information

Parent elements PUBLIC:COMPONENT
Child elements None
Minimum availability Internet Explorer 5
Minimum operating systems Windows 95, Windows NT 4.0

Remarks

By specifying a NAME attribute similar to a standard property already defined for the element, a behavior can override the element's default behavior.
If either the PUT or GET attribute is specified, the INTERNALNAME attribute is ignored. Setting and/or retrieving the value of the property through the function(s) specified in the PUT and GET attributes takes precedence over setting and/or retrieving the value of the property through the INTERNALNAME.
The function specified in the PUT attribute must notify the element in the containing document about the property change by calling the PUBLIC:PROPERTY element's fireChange method. Invoking this method causes the onpropertychange event to fire on the element in the containing page, with the event object's propertyName set to the name of the property.

Examples

This example uses an HTC to create a table of contents that expands and collapses when the user clicks it. The HTC exposes a child property to the containing document to indicate which element needs to toggle its display property to achieve the desired expanding/collapsing effect.
<PUBLIC:PROPERTY NAME="child" />
<PUBLIC:ATTACH EVENT="onclick" ONEVENT="ExpandCollapse()" />
<SCRIPT LANGUAGE="JScript">
function ExpandCollapse()
{
var i;
var sDisplay;
// Determine current state of the list (expanded or collapsed)
// based on the current display property of the child.
bCollapsed = (element.document.all(child).runtimeStyle.display == "none");
if (bCollapsed)
{
runtimeStyle.listStyleImage = "url('../common/blueminus.gif')";
element.document.all(child).runtimeStyle.display = "";
}
else
{
runtimeStyle.listStyleImage = "url('../common/blueplus.gif')";
element.document.all(child).runtimeStyle.display = "none";
}
}
</SCRIPT>
This feature requires Microsoft® Internet Explorer 5 or later. Click the following icon to install the latest version. Then reload this page to view the sample.
This example uses the PUT and GET attributes to specify which functions to invoke when the property is set or retrieved.
<PUBLIC:PROPERTY ID="propID" NAME="child"
PUT="saveChild" GET="returnChild"/>
:
<SCRIPT LANGUAGE="JScript">
var myChild=null;
function saveChild (vValue)
{
myChild = vValue;
propID.fireChange();
}
function returnChild()
{
return myChild;
}
</SCRIPT>