Alternate Stylesheets DOM ========================= This version: http://www.hixie.ch/specs/css/dom/altss/altss-1.0-pre8 Latest version: http://www.hixie.ch/specs/css/dom/altss/altss Previous version: http://www.hixie.ch/specs/css/dom/altss/altss-1.0-pre7 Editor: Ian Hickson, Opera Software Note: this page is ancient and is here for historical interest only. The most recent work in this area is here: http://dev.w3.org/csswg/cssom/ Status of this document ----------------------- This is a draft proposal. It may one day become part of a W3C draft, or, it may not. Implementors must realise that this is not a formal specification and that they must be ready to change their implementations to match more formal specifications if required. Interface --------- Note: For this interface, the DOMString values "null" and "the empty string" are distinct, and must not be considered equivalent. // Introduced in DOM Level 2: interface DocumentStyle { readonly attribute StyleSheetList styleSheets; // Introduced in DOM Level 3: attribute DOMString selectedStylesheetSet; readonly attribute DOMString lastStylesheetSet; readonly attribute DOMString preferredStylesheetSet; readonly attribute DOMStringList stylesheetSets; void enableStylesheetsForSet(in DOMString name); }; Attributes ---------- selectedStylesheetSet of type DOMString This attribute indicates which stylesheet set (see [[HTML4]]) is in use. This attribute is live; changing the disabled attribute on stylesheets directly will change the value of this attribute. If all the sheets that are enabled have the same title (by case insensitive comparisons) then the value of this attribute is exactly equal to the title of the first enabled stylesheet with a title in the styleSheets list. If stylesheets from different sets are enabled, then the return value is null (there is no way to determine what the currently selected stylesheet set is in those conditions). Otherwise, either all stylesheets are disabled, or there are no alternate stylesheets, and selectedStylesheetSet returns the empty string. Setting this attribute to the null value has no effect. Setting this attribute to a non-null value calls enableStylesheetsForSet() with that value as the function's argument, then sets lastStylesheetSet to that value. Note that from the DOM's perspective, all views have the same selectedStylesheetSet. If a UA supports multiple views with different selected alternate stylesheets, then this attribute (and the StyleSheet 'disabled' attribute) return and set the value for the default view. lastStylesheetSet of type DOMString, readonly This property returns the last value that selectedStylesheetSet was set to, or, if none, null. preferredStylesheetSet of type DOMString, readonly This attribute indicates the preferredStylesheetSet as set by the author. It is determined from the order of stylesheet declarations and the Default-Style HTTP headers. See [[HTML4]]. If there is no preferred stylesheet set, this attribute returns the empty string. The case of this attribute must exactly match the case given by the author where the preferred stylesheet is specified or implied. This attribute must never return null. stylesheetSets of type DOMStringList, readonly This is a live list of the currently available stylesheet sets. This list is constructed by enumerating all the stylesheets for this document available to the implementation, in the order they are listed in the styleSheets attribute, adding the title of each stylesheet with a title to the list, avoiding duplicates by dropping titles that match (case insensitively) titles that have already been added to the list. enableStylesheetsForSet, method Calling this method changes the 'disabled' attribute on each StyleSheet object with a title attribute with a length greater than 0 in the styleSheets attribute, so that all those whose title matches the 'name' argument are enabled, and all others will be disabled. Title matches are case insensitive. Calling this method with the empty string disables all alternate and preferred stylesheets (but does not change the state of persistent stylesheets, that is those with no title attribute). Calling this method with a null value has no effect. Stylesheets that have no title are never affected by this method. This method does not change the values of the lastStylesheetSet or preferredStylesheetSet attributes. Arguments name, of type DOMString The name of the stylesheet set to enable. No return value Does not raise any exceptions. Dynamically adding new stylesheets ---------------------------------- If new stylesheets with titles are added to the document, the UA must decide whether or not the stylesheets should be initially enabled or not. How this happens depends on the exact state of the document at the time the stylesheet is added, as follows. ADDING STYLESHEETS First, if the stylesheet is a preferred stylesheet (it has a title, but is not marked as alternate), and there is no current preferred stylesheet (the preferredStylesheetSet attribute is equal to the empty string) then the preferredStylesheetSet attribute is set to the exact value of this stylesheet's title. (This changes the preferred stylesheet set, which causes further changes -- see below.) Then, for all sheets, if any of the following is true, then the stylesheet is enabled: * The stylesheet has an empty title. * The lastStylesheetSet is null, and the stylesheet's title matches (by case insensitive match) the value of the preferredStylesheetSet attribute. * The stylesheet's title matches (by case insensitive match) the value of the lastStylesheetSet attribute. Otherwise, the stylesheet is disabled. CHANGING THE PREFERRED STYLESHEET SET If the UA has the preferred stylesheet set changed, for example if it receives a "Default-Style:" HTTP header after it receives HTTP "Link:" headers implying another preferred stylesheet, then the preferredStylesheetSet attribute's value should change appropriately, and, if the lastStylesheetSet is null, the enableStylesheetsForSet() method should be called with the new preferredStylesheetSet value. (The lastStylesheetSet attribute is not changed.) EXAMPLES Thus, in the following HTML snippet: ...the stylesheets that end up enabled are stylesheets "a", "b", and "c", the selectedStylesheetSet attribute would return null, lastStylesheetSet would return "foo", and preferredStylesheetSet would return "". Similarly, in the following HTML snippet: ...the "before" variable will be equal to the empty string, the "after" variable will be equal to "foo", and stylesheets "a" and "c" will be enabled. This is the case even though the first script block sets stylesheet "b" to be enabled, because upon parsing the following element, the preferredStylesheetSet is set and the enableStylesheetsForSet() method is called (since selectedStylesheetSet was never set explicitly, leaving lastStylesheetSet at null throughout), which changes which stylesheets are enabled and which are not. Interaction with the User Interface ----------------------------------- The user interface should list the stylesheet titles given in the stylesheetSets list, showing the selectedStylesheetSet as the selected stylesheet set, leaving none selected if it is null or the empty string, and selecting an extra option "Basic Page Style" (or similar) if it is the empty string and the preferredStylesheetSet is the empty string as well. Selecting a stylesheet from this list should set the selectedStylesheetSet attribute. Persisting the Selected Stylesheet Set -------------------------------------- If UAs persist the selected stylesheet set, they should use the value of the selectedStylesheetSet attribute, or if that is null, the lastStylesheetSet attribute, when leaving the page (or at some other time) to determine the set name to store. If that is null then the stylesheet set is not persisted. When re-setting the stylesheet set to the persisted value (which can happen at any time, typically at the first time the stylesheets are needed for styling the document, after the of the document has been parsed, after any scripts that are not dependent on computed style have executed), the stylesheet set should be set by setting the selectedStylesheetSet attribute as if the user had selected the set manually. This specification does not define how the UA decides to persist the stylesheet set or whether or how to persist the selected set across pages. Future compatibility -------------------- Note: Future versions of CSS may introduce ways of having alternate stylesheets declared at levels lower than the top level, i.e. embedded within other stylesheets. Implementations of this specification that also support this proposed declaration of alternate stylesheets are expected to perform depth-first traversals of the styleSheets list, not simply enumerations of the styleSheets list, which only contains the top level. Acknowledgements ---------------- David Hyatt, Boris Zbarsky, and fantasai have contributed valuable suggestions to this proposal.