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
Did you find this topic useful? Suggestions for other topics? write us!
© 1999 microsoft corporation. all rights reserved. terms of use.