setAttribute method
Sets the value of the specified attribute.
.png){kind=icon} |
Syntax
HRESULT retVal = object.setAttribute(strAttributeName, AttributeValue, lFlags);
Parameters
strAttributeName [in]
Type: BSTR
BSTR that specifies the name of the attribute.
AttributeValue [in]
Type: VARIANT
Variant that specifies the string, number, or Boolean to assign to the attribute.
lFlags [in, optional]
Type: long
LONG that specifies whether to use a case-sensitive search to locate the attribute. Can be one of the following values:
1
The case of strAttributeName is respected.
0
Match strAttributeName regardless of case.
Return value
Type: HRESULT
If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Standards information
- Document Object Model (DOM) Level 2 HTML Specification, Section 1.6.5
Remarks
Windows Internet Explorer 8 and later. IE8 Standards mode enables several enhancements to the IHTMLEventObj2::setAttribute, IHTMLEventObj2::getAttribute, and IHTMLEventObj2::removeAttribute methods that are not available when pages are displayed in earlier document modes.
The strAttributeName parameter requires the name of the desired content attribute and not the Document Object Model (DOM) attribute. For example, in IE8 mode, this method no longer requires strAttributeName to be
"className"when setting, getting, or removing a IHTMLElement::className attribute. Earlier versions of Windows Internet Explorer and Internet Explorer 8 in compatibility mode still require strAttributeName to specify the corresponding DOM property name.The strAttributeName parameter is not case sensitive. As a result, the lFlags parameter is no longer supported and should not be used.
The methods support event handlers. For example, the following code example defines an event handler to call a function called SomeFunction when the body of the page is loaded.
document.body.setAttribute('onload', 'SomeFunction()');
If the specified attribute is not already present, the IHTMLEventObj2::setAttribute method adds the attribute to the object and sets the value.
If your pages are displayed in IE5 (Quirks) mode or IE7 Standards mode, be careful when spelling attribute names. If you set lFlags to 1 and the strAttributeName parameter does not have the same uppercase and lowercase letters as the attribute, a new attribute is created for the object. If two or more attributes have the same name, differing only in case, and lFlags is set to 0, this method assigns values only to the first attribute created with this name. All other attributes of the same name are ignored.
Internet Explorer 8 and later. When pages are displayed in IE8 mode, the AttributeValue parameter only supports string values. Non-string values are not automatically converted to string values. For best results, formally convert values to strings before using them as parameter values. For example, do not attempt to pass an object directly to the AttributeValue parameter; call the object's toString method instead.
Use either VariantClear or SysFreeString with IHTMLEventObj2::setAttribute to clear a VARIANT. VariantClear will set a variant to VT_EMPTY, but will not free its allocated memory.
The strAttributeName parameter requires the name of the desired content attribute.
The strAttributeName parameter is not case sensitive. As a result, the lFlags parameter is no longer supported and should not be used.
The AttributeValue parameter only supports string values. Non-string values are not automatically converted to string values. For best results, formally convert values to strings before using them as parameter values. For example, do not attempt to pass an object directly to the AttributeValue parameter; call the object's toString method instead.
The methods support event handlers. For example, the following code example defines an event handler to call a function called SomeFunction when the body of the document is loaded.
document.body.setAttribute('onload', 'SomeFunction()');
IHTMLEventObj2::removeAttribute always returns S_OK as an HRESULT value. Check the pfSuccess parameter to determine if the attribute is successfully removed.
See also
Reference