PROPERTY Element

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

Syntax

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

Attributes

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.

ID

Optional. String that uniquely identifies the 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.

GET

Optional. String that specifies the function to be called whenever the value of the property is retrieved. A PROPERTY element that specifies a GET attribute without specifying a PUT attribute is a read-only property.

PUT

Optional. String that specifies the function to be called when the value of the property is set.

Note The function specified in this attribute must notify the element in the containing document about the property change by calling the 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. A 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.

PERSIST

Optional. Boolean that specifies whether to persist the property as part of the page.

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

Number of occurrences	Any number
Parent elements	COMPONENT
Child elements	None
Requires closing tag	No

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.

Example

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.

Sample Code

<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('/workshop/graphics/blueminus.gif')";
      element.document.all(child).runtimeStyle.display = "";
   }
   else
   {
      runtimeStyle.listStyleImage = "url('/workshop/graphics/blueplus.gif')";
      element.document.all(child).runtimeStyle.display = "none";
   }
}
</SCRIPT>

This feature requires Microsoft® Internet Explorer 5 or later. Click the icon below 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>

See Also

DHTML Behaviors, Implementing DHTML Behaviors in Script, EVENT, METHOD