defineProperty Method (Windows Scripting - JScript)

Article
07/17/2015

Adds a property to an existing Document Object Model (DOM) object.

Syntax

Object.defineProperty(object, propertyname, descriptor)

Arguments

object
Required. The existing DOM object on which to add the property.
propertyname
Required. A string that contains the name of the new property.
descriptor
Required. A JScript object that contains a descriptor that describes the property. The definition can be for a data property or an accessor property.

Return Value

The DOM object that was passed to the method.

Remarks

The descriptor object describes attributes of the property to be added.

You can use the defineProperty method to create accessor properties and data properties. The attributes of the descriptor object determine which of these two types is created.

Accessor Properties

An accessor property calls a user-provided function every time that the property value is set or retrieved. The descriptor object for an accessor property contains a get attribute, a set attribute, or both.

In the accessor property descriptor, the enumerable attribute can be set to false, or it can be unspecified. The configurable property can be set to true, or it can be unspecified. Those attributes are reserved for future use.

When a get accessor is not specified and an attempt is made to access the property value, the value undefined is returned. When a set accessor is not specified and an attempt is made to assign a value to the accessor property, nothing happens.

Data Properties

A data property is a property that can store and retrieve a value. The descriptor object for a data property contains a value attribute, a writable attribute, or both.

In the data property descriptor, the writable attribute, the enumerable attribute, and the configurable property can each be set to true, or they can be unspecified.

In the following example, the defineProperty method is used to add an accessor property to an existing DOM object.

function AddAccessorProperty()
    {
    var obj = window.document;

    // Create the descriptor for the new accessor property.
    var descriptor =
        {
        set: function (x)
            {
            println("in property set accessor");
            this.newaccpropvalue = x;
            },
        get: function ()
            {
            println("in property get accessor");
            return this.newaccpropvalue;
            },
        enumerable: false,
        configurable: true
        };


    // Display the descriptor's properties.
    ShowProperties (descriptor, "accessor descriptor");

    // Add the new data property to the window.document object.
    Object.defineProperty (obj, "NewAccessorProperty", descriptor);

    // Set the property value.
    println ("<i>Setting and getting accessor property value</i>");

    obj.NewAccessorProperty = 42;
    println ("Property value: " + obj.NewAccessorProperty);
    println ("");

    // Get the descriptor from the object's property.
    var descfromprop = Object.getOwnPropertyDescriptor(obj, "NewAccessorProperty");

    // Display the descriptor's properties.
    ShowProperties (descfromprop, "descfromprop accessor descriptor");
    }

function ShowProperties(objwithproperties, description)
    {
    println ("<i>properties in " + description + "</i>");
    for (var prop in objwithproperties)
        {
        println(prop + ': ' + objwithproperties[prop]);
        }
    println ("");
    }

function println(s)
    {
    document.write(s + '<br>');
    }

In the following example, the defineProperty method is used to add a data property to an existing DOM object. The ShowProperties() and println() support functions are in the previous example.

function AddDataProperty()
    {
    var obj = window.document;

    // Create the descriptor for the new data property.
    var descriptor =
    {
      value: 101,
      writable: true,
      enumerable: true,
      configurable: true
    };
 
    // Display the descriptor's properties.
    ShowProperties (descriptor, "descriptor");

    // Add the new data property to the window.document object.
    Object.defineProperty (obj, "NewDataProperty", descriptor);

    // Display the properties of the window.document object,
    // which now includes the NewDataProperty property.
    ShowProperties (obj, "window.document object");

    // Display the property value.
    // Output: 101
    println ("Initial value: " + obj.NewDataProperty);

    // Modify and display the property value.
    // This is allowed if the descriptor's writable value is true.
    obj.NewDataProperty = 45;
    println ("Modified value: " + obj.NewDataProperty);
    println ("");

    // Get the descriptor from the object's property.
    var descfromprop = Object.getOwnPropertyDescriptor(obj, "NewDataProperty");

    // Display the descriptor's properties.
    ShowProperties (descfromprop, "descfromprop descriptor");
    }

You can also use the assignment operator (=) to add a data property, as shown in the following example. The ShowProperties() and println() support functions are in the first example in this topic.

function AddDataProperty2()
    {
    var obj = window.document;

    // Create the new data property and set the value.
    obj.NewDataProperty2 = 105;

    // Display the data property value.
    println ("Data Property value: " + obj.NewDataProperty2);
    println ("");
     
    // Display the properties of the window.document object,
    // which now includes the NewDataProperty2 property.
    ShowProperties (obj, "window.document object");
    }

Requirements

Version 5.8

Note

Starting with JScript 5.8, by default, the JScript scripting engine supports the language feature set as it existed in version 5.7. This is to maintain compatibility with the earlier versions of the engine. To use the complete language feature set of version 5.8, the Windows Script interface host has to invoke IActiveScriptProperty::SetProperty.

Internet Explorer 8 opts into the JScript 5.8 language features when the document mode for Internet Explorer 8 is "Internet Explorer 8 Standards" mode. For other document modes, Internet Explorer uses the version 5.7 feature set.

JScript 5.8 includes native JavaScript Object Notation (JSON) support and the accessor methods for Document Object Model (DOM) prototypes.

Change History

Date	History	Reason
March 2009	Added topic.	Information enhancement.

March 2009

Added topic.

Information enhancement.

Share via