788 Part III ✦ Document Objects Reference pages Value: Array of @page Rules Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ An @page style rule defines the dimensions and margins for printed versions of a Web page. The pages property returns a collection of @page rules contained by the current styleSheet object. If no @page rules are defined in the style sheet, the array has a length of zero. While an @page rule has the same properties as any rule object, it has one more read-only property, the pseudoClass property, which returns any pseudo-class def- initions in the rule. For example, the following @page rules define different rectangle specifications for the left and right printed pages: @page :left {margin-left:4cm; margin-right:3cm;} @page :right {margin-left:3cm; margin-right:4cm;} Values for the pseudoClass property of these two page rules are :left and :right, respectively. To the W3C DOM, an @page rule is just another rule object, but one whose type property returns page. For more information about the paged media specification, see http://www. w3.org/TR/REC-CSS2/page.html . Related Items: None. parentStyleSheet Value: styleSheet Object Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ An imported style sheet is present thanks to the hosting of a styleSheet object created by a STYLE or LINK element. That host styleSheet object is referenced by the parentStyleSheet property. For most styleSheet objects (that is, those not imported via the @import rule), the parentStyleSheet property is null. Take note of the distinction between the parentStyleSheet property, which points to a styleSheet object, and the various properties that refer to the HTML element that “owns” the styleSheet object. Related Items: None. styleSheetObject.parentStyleSheet 789 Chapter 30 ✦ Style Sheet and Style Objects readOnly Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The readOnly property’s name is a bit misleading. Its Boolean value lets your script know whether the current style sheet was embedded in the document by way of the STYLE element or brought in from an external file via the LINK element or @import rule. When embedded by a STYLE element, the readOnly property is false; for style sheets defined outside the page, the property is true. But a value of true doesn’t mean that your scripts cannot modify the style properties. Style properties can still be modified on the fly, but of course the changes will not be reflected in the external file from which the initial settings came. Related Items: owningElement property. rules Value: Array of rule Objects Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The rules property returns an array of all rule objects (other than @ rules) defined in the current style sheet. The order of rule objects in the array is based on source code order of the rules defined in the STYLE element or in the external file. Use the rules array as the primary way to reference an individual rule inside a style sheet. If you use a for loop to iterate through all rules in search of a particular rule, you will most likely be looking for a match of the rule object’s selectorText property. This assumes, of course, that each selector is unique within the style sheet. Using unique selectors is good practice, but no restrictions prevent you from reusing a selector name in a style sheet for additional style information applied to the same selector elements. The corresponding property name for NN6 is cssRules. IE5/Mac responds to both the rules and cssRules properties. Example on the CD-ROM Related Items: rule object; cssRules property. On the CD-ROM styleSheetObject.rules 790 Part III ✦ Document Objects Reference title Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ If you assign a value to the TITLE attribute of a STYLE element or a LINK element that loads a style sheet, that string value filters down to the title property of the styleSheet object. You can use the string value as a kind of identifier, but it is not usable as a true identifier that you can use as an index to the styleSheets array. In visible HTML elements, the TITLE attribute usually sets the text that displays with the tooltip over the element. But for the unseen STYLE and LINK elements, the attribute has no impact on the rendered display of the page. Therefore, you can use this attribute and corresponding property to convey any string value you want. Related Items: title property of all HTML elements. type Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The type property of a styleSheet object picks up the TYPE attribute of the STYLE or LINK element that embeds a style sheet into the page. Unless you are experimenting with some new types of style sheet language (assuming it is even supported in the browser), the value of the type property is text/css. Related Items: None. Methods addImport(“URL”[, index]) Returns: Integer. NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The addImport() method lets you add an @import rule to a styleSheet object. A required first parameter is the URL of the external .css file that contains one or more style sheet rules. If you omit the second parameter, the @import rule is styleSheetObject.addImport() 791 Chapter 30 ✦ Style Sheet and Style Objects appended to the end of rules in the styleSheet object. Or you can specify an integer as the index of the position within the rules collection where the rule should be inserted. The order of rules in a styleSheet object can influence the cascading order of overlapping style sheet rules (that is, multiple rules that apply to the same elements). The value returned by the method is an integer representing the index position of the new rule within the rules collection of the styleSheet. If you need subsequent access to the new rule, you can preserve the value returned by the addImport() method and use it as the index to the rules collection. Related Items: addRule() method. addRule(“selector”, “styleSpec”[, index]) removeRule(index) Returns: Integer (for addRule()). NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The addRule() method appends or inserts a style sheet rule into the current styleSheet object. The first two parameters are strings for the two components of every rule: the selector and the style specification. Any valid selector, including multiple, space-delimited selectors, is permitted. For the style specification, the string should contain the semicolon-delimited list of style attribute:value pairs, but without the curly braces that surround the specification in a regular style sheet rule. If you omit the last parameter, the rule is appended to the end of the rules col- lection for the style sheet. Or, you can specify an integer index value signifying the position within the rules collection where the new rule should go. The order of rules in a styleSheet object can influence the cascading order of overlapping style sheet rules (meaning multiple rules that apply to the same elements). The return value conveys no meaningful information. To remove a rule from a styleSheet object’s rules collection, invoke the removeRule() method. Exercise some care here, because you must have the correct index value for the rule that you want to remove. Your script can use a for loop to iterate through the rules collection, looking for a match of the selectorText property (assuming that you have unique selectors). The index for the matching rule can then be used as the parameter to removeRule(). This method returns no value. For NN6, the corresponding methods are called insertRule() and deleteRule(). Example on the CD-ROM Related Items: deleteRule(), insertRule() methods. On the CD-ROM styleSheetObject.addRule() 792 Part III ✦ Document Objects Reference deleteRule(index) insertRule(“rule”, index) Returns: Integer (for insertRule()). NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The insertRule() method appends or inserts a style sheet rule into the current styleSheet object. The first parameter is a string containing the style rule as it would normally appear in a style sheet, including the selector and curly braces sur- rounding the semicolon-delimited list of style attribute:value pairs. You must supply an index location within the cssRules array where the new rule is to be inserted. If you want to append the rule to the end of the list, use the length property of the cssRules collection for the parameter. The order of rules in a styleSheet object can influence the cascading order of overlapping style sheet rules (meaning multiple rules that apply to the same elements). The return value is an index for the position of the inserted rule. To remove a rule from a styleSheet object’s cssRules collection, invoke the deleteRule() method. Exercise some care here, because you must have the cor- rect index value for the rule that you want to remove. Your script could use a for loop to iterate through the cssRules collection, looking for a match of the selectorText property (assuming that you have unique selectors). The index for the matching rule can then be used as the parameter to deleteRule(). This method returns no value. For IE4+, the corresponding methods are called addRule() and removeRule(). Example on the CD-ROM Related Items: addRule(), removeRule() methods. cssRule and rule Objects Properties Methods Event Handlers cssText parentStyleSheet readOnly selectorText style type On the CD-ROM ruleObject 793 Chapter 30 ✦ Style Sheet and Style Objects Syntax Accessing rule or cssRule object properties: (IE4+) document.styleSheets[index].rules[index].property (IE5-Mac/NN6+) document.styleSheets[index].cssRules[index].property About these objects The rule and cssRule objects are different object model names for the same objects. For IE4+, the object is known as a rule (and a collection of them the rules collection); for NN6 (and IE5/Mac), the object follows the W3C DOM recommenda- tion, calling the object a cssRule (and a collection of them the cssRules collection). For the remainder of this section, they will be referred to generically as the rule object. A rule object has two major components. The first is the selector text, which governs which element(s) are to be influenced by the style rule. The second com- ponent is the style definition, with its set of semicolon-delimited attribute:value pairs. In both the IE4+ and NN6 object models, the style definition is treated as an object: the style object, which has tons of properties representing the style attributes available in the browser. The style object that belongs to a rule object is precisely the same style object that is associated with every HTML element object. Accessing style properties of a style sheet rule requires a fairly long refer- ence, as in document.styleSheets[0].rules[0].style.color = “red” but the format follows the logic of JavaScript’s dot-syntax to the letter. Properties cssText Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ (✓) The cssText property returns the full text of the current cssRule object. This property is available in NN6 and IE5/Macintosh. While the text returned from this property can be parsed to locate particular strings, it is easier and more reliable to access individual style properties and their values via the style property of a cssRule object. Related Items: style property. parentStyleSheet Value: styleSheet Object Read-Only ruleObject.parentStyleSheet 794 Part III ✦ Document Objects Reference NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ (✓) The parentStyleSheet property is a reference to the styleSheet object that contains the current cssRule object. This property is available in NN6 and IE5/Macintosh. The return value is a reference to a styleSheet object, from which scripts can read and write properties related to the entire style sheet. Related Items: parentRule property. readOnly Value: Boolean Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓ ✓ The readOnly property’s name is a bit misleading. Its Boolean value lets your script know whether the current rule’s styleSheet was embedded in the document by way of the STYLE element or brought in from an external file via the LINK ele- ment or @import rule. When embedded by a STYLE element, the readOnly prop- erty is false; for style sheets defined outside the page, the property is true. But a value of true doesn’t mean that your scripts cannot modify the style properties. Style properties can still be modified on the fly, but of course the changes are not reflected in the external file from which the initial settings came. Related Items: styleSheet.readOnly property. selectorText Value: String Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The selectorText property returns only the selector portion of a style sheet rule. The value is a string, and if the selector contains multiple, space-delimited items, the selectorText value returns the same space-delimited string. For selec- tors that are applied to classes (preceded by a period) or ids (preceded by a crosshatch), those leading characters are returned as part of the string as well. If you want to change the selector for a rule, removing the original rule and adding a new one in its place is better. You can always preserve the style property of the original rule and assign the style to the new rule. ruleObject.selectorText 795 Chapter 30 ✦ Style Sheet and Style Objects Example on the CD-ROM Related Items: style property. style Value: style Object Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓✓✓✓ The style property of a rule (or cssRule) is, itself, an object whose properties consist of the CSS style attributes supported by the browser. Modifying a property of the style object requires a fairly long reference, as in document.styleSheets[0].rules[0].style.color = “red” Any change you make to the rule’s style properties is reflected in the rendered style of whatever elements are denoted by the rule’s selector. If you want to change the style of just one element, then access the style property of just that element. Style values applied directly to an element override whatever style sheet style val- ues are associated with the element. Example on the CD-ROM Related Items: style object. type Value: Integer Read-Only NN2 NN3 NN4 NN6 IE3/J1 IE3/J2 IE4 IE5 IE5.5 Compatibility ✓ The W3C DOM defines several classes of style sheet rules. To make it easier for a script to identify the kind of cssRule it is working with, the type property returns an integer whose value is associated with one of the known cssRule types. While not all of these rule types may be implemented in NN6, the complete W3C DOM list is as follows: On the CD-ROM On the CD-ROM ruleObject.type 796 Part III ✦ Document Objects Reference Type Description 0 Unknown type 1 Regular style rule 2 @charset rule 3 @import rule 4 @media rule 5 @font-face rule 6 @page rule Most of the style sheet rules you work with are type 1. To learn more about these rule types, consult the W3C specification for CSS at http://www.w3.org/TR/ REC-CSS 2. Related Items: None. currentStyle, runtimeStyle, and style Objects Properties Methods Event Handlers (See below) Syntax Accessing currentStyle, runtimeStyle, or style object properties: (IE4+/NN6) elementReference.style.property (IE4+/NN6) document.styleSheets[index].style.property (IE5+) elementReference.currentStyle.property (IE5.5) elementReference.runtimeStyle.property About these objects All three of these objects — currentStyle, runtimeStyle, and style — return an object that contains dozens of properties related to style sheet specifications associated either with a styleSheet object (for the style object only) or any ren- dered HTML element object. With the browser page reflow facilities of IE4+ and NN6+, changes made to the properties of the style and IE-specific runtimeStyle objects are reflected immediately by the rendered content on the page. The primary object, the style object, is accessed as a property of either a styleSheet object or an HTML element object. It is vital to remember that style properties of an HTML element are reflected by the style object only if the specifi- cations are made via the STYLE attribute inside the element’s tag. If your coding style requires that style sheets be applied via STYLE or LINK tags, and if your elementRef.style 797 Chapter 30 ✦ Style Sheet and Style Objects scripts need to access the style property values as set by those style sheets, then you must read the properties through the read-only currentStyle property (avail- able in IE5+). The currentStyle object returns the effective style sheet being applied to an HTML element object. IE’s currentStyle object does not have precisely the same properties as its style object. Missing from the currentStyle object are the properties that con- tain combination values, such as border or borderBottom. On the other hand, currentStyle provides separate properties for each of the sides of a clipping rect- angle ( clipTop, clipRight, clipBottom, and clipLeft), which the clip property does not provide. Microsoft introduced one more flavor of style object — the runtimeStyle object — in IE5.5. This object lets scripts override any style property that is set in a style sheet or via the STYLE attribute. In other words, the runtimeStyle object is like a read/write version of currentStyle except that assigning a new value to one of its properties does not modify the style sheet definition or the value assigned in a STYLE attribute. By and large, however, your scripts will modify the style prop- erty of an element to make changes, unless you modify styles by enabling and dis- abling style sheets (or changing the className property of an element so that it is under the control of a different selector). Style properties If you add up all the style object properties available in browsers starting with IE4 and NN6, you have a list approximately 180 properties long. A sizable percent- age are in common among all browsers and are scriptable versions of W3C CSS style sheet attributes. The actual CSS attribute names are frequently script- unfriendly in that multiple-worded attributes have hyphens in them, such as font-size. JavaScript identifiers do not allow hyphens, so multiple-worded attributes are converted to interCap versions, such as fontSize. Not all style properties are supported by all browsers that have the style object in their object models. Microsoft, in particular, has added many properties that are sometimes unique to IE and sometimes unique to just IE for Windows (or even just to Windows 2000). On the Netscape side, you find some properties that appear to be supported by the style object, but the browser doesn’t genuinely support the attributes. For example, the CSS specification defines several attributes that enhance the delivery of content that is rendered through a speech synthesizer. While NN6 does not qualify, the Gecko browser engine at the core of NN6 could be adapted to such a browser. Therefore, if you see a property in the following listings that doesn’t make sense to you, test it out in the compatible browsers to verify that it works as you need it. Some browsers also expose advanced style object properties to scripters, when, in fact, they are not genuinely supported in the browser. For example, an inspection of the style object for IE5/Mac and NN6 shows a quotes property, which matches the quotes style attribute in the W3C CSS2 specification. But in truth, the quotes style property cannot be set by script in these browsers. When you see that a property is supported by IE5/Mac and NN6 but none others, testing out the style property (and the style sheet attribute as well) in The Evaluator is a good idea before attempting to employ the property in your application. elementRef.style . 788 Part III ✦ Document Objects Reference pages Value: Array of @page Rules Read-Only NN2 NN3 NN4 NN6. individual rule inside a style sheet. If you use a for loop to iterate through all rules in search of a particular rule, you will most likely be looking for a match of the rule object’s selectorText property CD-ROM Related Items: rule object; cssRules property. On the CD-ROM styleSheetObject.rules 790 Part III ✦ Document Objects Reference title Value: String Read/Write NN2 NN3 NN4 NN6 IE3/J1 IE3/J2