CSS Namespaces Support - Functional and Design Specification

Glossary

See the CSS Advanced Selectors specification.

Summary and Background

Flex developers use CSS as an efficient way to define styles for MXML components. Styles can be applied to all instances of a component using a single style declaration. However, styles are currently defined for MXML components based on the local tag name; the namespace of a tag is not considered.

In Gumbo, a new set of components will be introduced (called Spark) and some of these components share the same local name as existing MX components. While our customers have said that they don't use type selectors very often, some mechanism is still required to disambiguate name collisions. We will provide developers new CSS syntax to target styles for types of components based on the namespace of the component set.

The W3C Candidate Recommendation for CSS-3 includes a module for CSS Namespaces. Flex will base its new syntax on this recommendation.

Note: This work is required to support the removal of the Fx prefix from our new components. See the Dropping the Fx Prefix documentation for details.

Usage Scenarios

A Flex developer has noticed that Gumbo has Advanced CSS support. In particular they wish to make use of descendant selectors which rely heavily on type selectors. However, the developer wishes to make use of both MX and Spark components in this same application. To avoid potential name collisions, the developer needs a mechanism to scope each type selector to its fully qualified class name to ensure the correct components are styled.

A Flex developer migrates their Flex 3 application to Flex 4. Their application made use of CSS type selectors which were not qualified with namespaces. On compiling their application they notice warnings for their unqualified type selectors and the application does not look styled as expected. They have read the migration guide and realize that they can either add namespace qualification to their application or specify the -compatibility flag as version '3' to restore the legacy behavior.

Detailed Description

CSS 3 Namespace Qualification

Namespace qualification is now required for type selectors in CSS style declarations for all applications.

We will use the CSS-3 suggested syntax for declaring namespaces and prefixing type selectors. e.g.

<Style>
@namespace "library://ns.adobe.com/flex/spark";
@namespace mx "library://ns.adobe.com/flex/mx";
</Style>

The default namespace does not use a prefix. All other namespaces define a prefix before the URI. Such prefixes are used on type selectors and are separated by a pipe | char.

<Style>
mx|Button { color:#FF0000; }
</Style>

The CSS-3 specification states that a namespace declaration must appear after anycharset or import at-rules, but before any other at-rules and before any rule sets (i.e. style declarations). Given the subset of features of CSS that Flex supports, in essence this means thatnamespace must be declared at the top of a style sheet before any @font-face rules or style declarations.

The default namespace should be used for the most common component namespace to avoid requiring prefixes on each type selector as much as possible (note: actual namespace urls to be finalized by product management):

<Style>
@namespace "library://ns.adobe.com/flex/spark";

Button { color: #990000; }
</Style>

In more complex scenarios multiple namespaces may be required in the same stylesheet and thus prefixes are used:

<Style>
@namespace "library://ns.adobe.com/flex/spark";
@namespace cx "com.mycompany.*";

Button { color: #990000; }
cx|MyFancyButton { color: #000099; }
</Style>

If no type selectors are used in a style sheet then an @namespace rule is not required and can be omitted by the developer.

If the default namespace or a namespace prefix is declared more than once the last declaration wins.

The declaration of 'no namespace' will be interpreted to mean the top level package. This means there are several ways to declare the top level package in Flex CSS. The preferred way is to use the MXML-centric method of using a single asterisk * character. Two other ways include using the empty string URI either with a prefix or as the default namespace. The final way is to use the CSS namespace prefix separator char | but without an actual prefix. In the following example, all four style declarations declare that the MyFancyComponent class is in the top level package.

<Style>
@namespace "";
@namespace d "*";
@namespace e "";

MyFancyComponent { color: #990000; }
d|MyFancyComponent { color: #000099; }
e|MyFancyComponent { color: #000099; }
|MyFancyComponent  { color: #000099; }
</Style>

Note: the format of the URI in itself will not be validated during parsing. If the resolved qualified type does not correspond to a known manifest mapping or represent a local package, a warning will be reported. See the next section for more details.

Finally, the CSS 3 wildcard namespace prefix syntax of *| that is supposed to match ANY namespace (including no namespace) will NOT be supported.

<Style>
*|MySpecialButton { color: #990000; }    /* Wildcard namespace prefix not supported on types */
</Style>

Theoretically, the only time this syntax would have supportable meaning in Flex would be for the universal selector *.

<Style>
*|* { color: #990000; }     /* Theoretically just the universal selector */
</Style>

We will also NOT support the universal selector scoped to a particular namespace. Namespaces are not known at runtime in Flex and as such the universal selector will remain universal no matter what namespace it is scoped to in CSS.

<Style>
@namespace "library://ns.adobe.com/flex/spark";
@namespace mx "library://ns.adobe.com/flex/mx";

|* { font-size:12pt; }    /* Not limited to namespace */
mx|* { font-size:12pt; }    /* Not limited to namespace */
</Style>

In our implementation - Batik's CSS Parser must first be made aware of CSS-3 namespace syntax, at least for type selectors (since Flex does not use attribute selectors, namespace syntax for attribute selectors will not be supported). The Flex Compiler must also be updated to look out for qualified type selectors and map them to ActionScript class names. This is covered in the next section.

Mapping type selectors to ActionScript class names

The Flex Compiler will be updated to resolve namespace prefixed CSS type selectors to qualified ActionScript class names. The namespace mappings that are currently used to map MXML tag names to ActionScript class names will also apply to CSS-3 type selectors. These mappings draw information from configured manifests in flex-config.xml, swcs' catalog.xml files, and local package namespaces (e.g. in MXML you use xmlns:c="com.mycompany.*" to specify the package name of a custom component).

The XML namespaces and prefix mappings defined in MXML do not automatically apply to a corresponding style sheet. They must be declared explicitly in CSS using the @namespace syntax.

Type selectors that are either not qualified by a namespace or do not resolve to an ActionScript class linked into the Application cause a warning at compile time.

Legacy Flex applications (i.e. MXML 2006) must either be updated to use CSS namespaces or run in a backwards compatibility mode targeting version 3 (or earlier) in order for type selectors to function and to avoid compile time warnings. If developers choose to use the compatibility mode, CSS namespaces are ignored and they can use unqualified local names for type selectors.

CSS type selectors at runtime

Since the compiler translates namespace qualified type names to fully qualified ActionScript class names, there is no concept of namespaces at runtime.

The runtime Flex style subsystem will now only match against fully qualified ActionScript class names. When the compatibility version mode is used for version 3 (or earlier), the runtime will only match against unqualified (i.e. local) type names.

Type selectors only in root document

We continue to discourage type selectors anywhere but the root application file, and a warning will be given if type selectors are used outside of the root application.

API Description

CSS syntax in Flex will be updated to include @namespace at-rules and namespace prefixes for element selectors.

Example.mxml

<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:mx="library://ns.adobe.com/flex/mx">

    <fx:Style source="styles.css" />

    <s:Button label="Spark Button" />
    <mx:Button label="MX Button" />

</s:Application>

styles.css

@namespace fx "library://ns.adobe.com/flex/spark";
@namespace mx "library://ns.adobe.com/flex/mx";

fx|Button {
    baseColor:#009900;
}
mx|Button {
    color:#000099;
}

In the above example, the Spark Button should be green and the MX Button label text should be blue.

B Features

None.

Additional Implementation Details

Enter implementation/design details for the feature here. This section may be updated after the spec signs off.

Prototype Work

Changes to Batik were prototyped to show that CSS-3 syntax can be parsed and the information made available to the Flex compiler.

Code generation and runtime changes were prototyped to show that qualified ActionScript class names can be used to match type selectors to components.

Compiler Work

This is largely a compiler feature and the work required is outlined in the detailed description section.

Web Tier Compiler Impact

No changes are expected for the web tier compiler.

Flex Feature Dependencies

Knowing how gumbonents will make use of styles is a major requirement for this feature.

Backwards Compatibility

Syntax changes

The @namespace syntax in CSS is covered by this specification in detail.

At runtime, the StyleManager APIs that take selectors as arguments will expect qualified type names going forward unless the backwards compatibility version is set to 3 (or earlier).

Behavior

Going forward, CSS type selectors must be namespace qualified and map to a fully qualified ActionScript class name. However, for legacy applications running in compatibility mode, they will not use namespace qualification and rely on matching types by local type name.

For runtime, if running in compatibility mode for version 3 (or earlier), legacy unqualified type selectors must be used.

Warnings/Deprecation

Type selectors that are either not qualified by a namespace or do not resolve to an ActionScript class linked into the Application cause a warning at compile time.

We continue to discourage type selectors anywhere but the root application file, and a warning will be given if type selectors are used outside of the root application.

Accessibility

None known.

Performance

The mapping of namespace qualified type selectors to ActionScript class selectors is not expected to impact performance. The mechanism for matching type selectors continues to be string based (despite being qualified ActionScript class names) and is also not expected to impact application startup or runtime performance.

Globalization

None known. If we support non-Latin component names, ids, styleNames, or states, then we must test that such names can be targeted in CSS.

Localization

Compiler Features

Error/warning messages that are related to the compiler core (flex2.compiler.* packages) will be added to sdk/modules/compiler/src/java/flex2/compiler_en.properties and compiler_ja.properties.

Error/warning messages that are related to the linker (flex2.linker.* packages) will be added to sdk/modules/compiler/src/java/flex2/linker_en.properties and linker_ja.properties.

Framework Features

N/A

Issues and Recommendations

None.

Documentation

We will need to explain this new CSS syntax in detail in Gumbo in addition to our Advanced CSS changes.