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.

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 be raised on the element in the containing page, with the event object's propertyName set to the name of the property.

The variable type for VALUE is a variant. As such, it will return the type it was given. For example, if VALUE is given a string, it will return as a string. If it is given a boolean, it will return as a boolean.

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('/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>

Code example: https://samples.msdn.microsoft.com/workshop/samples/components/htc/toc/toc.htm

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

Introduction to DHTML Behaviors, Using HTML Components to Implement DHTML Behaviors in Script, PUBLIC:EVENT, PUBLIC:METHOD