MXML 2009 - Functional and Design Specification

Glossary

Namespace In this document, references to namespaces are concerned with XML namespaces used in MXML documents (ActionScript also has the concept of namespaces but they are unrelated to MXML namespaces). A namespace must be a valid URI and provides a scope to uniquely identify a set of components, language tags or attributes.

Manifest A manifest is a simple XML document that maps tag names to qualified ActionScript class names. There is a one-to-one mapping between a tag name and a class name. A manifest is associated with a component namespace to define a set of components - this helps the compiler resolve the implementation for a component tag. SWCs use manifests to describe which components they contain but additional manifests can be configured with the compiler.

Summary and Background

This specification outlines the proposed changes to the MXML language in Gumbo, the codename for the next release of Flex.

1. Namespaces

Namespaces in MXML are used to achieve several things, such as to specify the language version, to provide a scope to map XML tag names to class names, and to provide hints to the compiler as to where to locate local sources for custom components.

In Flex 2 and 3, the MXML 2006 namespace defined the language version and contained mappings for the Flex framework components. In Gumbo, new language features are being introduced and so the MXML namespace is being updated to MXML 2009. Besides defining new language features, the MXML 2009 namespace includes mappings for the Flex 3 framework, as well as the gumbo and FXG graphics frameworks (see next).

In Gumbo, another document format is introduced with FXG. While the compiler needs to be aware of this format, it should treat such a document as an external asset - one that happens to be resolvable like an MXML component. If users wish to make declarative use of the underlying graphics classes (that are used to render FXG in Flex) inline in their MXML documents, they must port the FXG tags into the MXML 2009 namespace. The FXG namespace is not to be mixed inline with an MXML document.

2. Default Property and the Declarations Tag

For MXML 2009 (and FXG) we will remove the special case of ignoring a "default property" definition for a root tag (if one happened to be defined). In previous versions of Flex, if the root tag was a container, visual children (i.e. implementations of mx.core.IUIComponent) immediately under the parent were added through addChild(). Non-visual children were simply new property declarations for the component.

Going forward in Gumbo, if the root tag defines a default property, immediate children (visual or non-visual) that do not represent values of properties declared on the base class will be treated as default property values. New property declarations (i.e. which are not intended as values for the default property) can be declared under a new <Declarations> tag.

If the root tag does not define a default property, immediate visual children will continue to be handled via addChild(). However, non-visual children that represent new property declarations are not allowed as immediate children of the root and must instead be added under a new <Declarations> section.

3. The Private Tag and Private Attributes

The <Private> tag is a new element in MXML 2009 and FXG that is used to store application specific design-time information. All the content inside the <Private> tag is ignored by the compiler.

In MXML 2009 and FXG documents, attributes that are qualified in non-language namespaces will also be ignored by the compiler to allow other tools to add annotation and design-time information directly to tags.

4. The Library Tag and Definitions

The <Library> tag is a new element in MXML 2009 and FXG that is used to declare zero or more named graphic <Definition> children that are essentially templates that can be reused in a given document. Note the definition itself is not an instance - only subsequent usages of the definition in the document act as instances.

Usage Scenario

Please keep the following usage scenarios in mind for each language change:

1. A Flex 3 application should continue to compile.
2. Starting with a Flex 3 application, a developer creates a new MXML document and uses new components.
3. Starting with a a Flex 3 application, a developer creates a new MXML document and uses new components and some Flex 3 components.
4. Starting with a Flex 3 application, a developer takes an existing MXML document and wants to add some new components to it.
5. A developer creates a new MXML document and wishes to make use of an FXG asset.

See the Backwards Compatibility section for a discussion of how developers will handle these usage scenarios.

Detailed Description

1. Namespaces

MXML 2009 Namespace - "http://ns.adobe.com/mxml/2009"

In Gumbo we are introducing a new MXML 2009 language namespace http://ns.adobe.com/mxml/2009. A small set of tags and attributes in this namespace are known by the compiler as special language entities (and do not map to component classes or their properties).

While Flex 3 MXML documents using the http://www.adobe.com/2006/mxml namespace will still compile in Gumbo, this namespace is still considered a language namespace. Only one language namespace must be specified per MXML document so Flex 3 and Gumbo language namespaces cannot be mixed. A language namespace must be present in every document, and it must be declared on the document root node, regardless of whether it is used in the document, as this namespace will determine the language rules for the entire document.

All Gumbo language tags and attributes must be declared in this namespace. Language tags will no longer be resolved in component namespaces. If such a tag is used in a non-language namespace (and if a component was not mapped for that tag in that non-language namespace) it would be a compile time error.

Also, the following language tags are new to Gumbo:

Also, ActionScript 3 built-in types are generally special cased by the compiler. These top level classes will also be part of the MXML 2009 namespace.

Language attributes such as the frameRate property on an Application root tag are defined in the language namespace and can be qualified with a language namespace prefix. However, usually the default prefix (i.e. the empty string) is in use for the language namespace and thus there is no prefix. (Note that unqualified attributes in XML are actually in an empty namespace and not the default namespace of the document). Since historically the compiler special cased unqualified special attributes as language attributes, we will continue to do so going forward.

<Application xmlns="http://ns.adobe.com/mxml/2009" frameRate="24">
...

If a language attribute and a component property overlap, then a non-default namespace prefix can be assigned to the component and this namespace prefix used on the attribute to resolve the conflict (so that such a qualified attribute would be seen as a component property).

<fx:MyComponent
    xmlns:fx="library:mycompany/flex/components"
    xmlns="http://ns.adobe.com/mxml/2009"
    fx:includeIn="SomeValue"
    includeIn="StateA,StateB" />

In the unusual situation that a non-default prefix was assigned to the language namespace, then special attributes may also be qualified with that prefix and will continue to be seen as special attributes. However, unqualified special attributes are always seen as language attributes and thus a non-default language prefix cannot be used to disambiguate from component properties.

Finally, if some other namespace (which is neither the component's namespace or the language namespace) is used to qualify any attribute, the attribute is simply ignored as design time metadata (i.e. a "private" attribute).

<Application
    xmlns="http://ns.adobe.com/mxml/2009"
    xmlns:foo="http://somedesigntool.com/2008"
    foo:revision="Some design time info" />

The following is a list of Application root tag language attributes.

The following Flex 1.5 root tag attributes were not allowed in Flex 3 and are still not allowed by the compiler and will generate an error if used.

A special case will be made for the id attribute. It can be qualified with the language namespace, but it is a special case when unqualified and is always seen as the id of the component.

New to Gumbo are additional Enhanced States Syntax language attributes to control which states a component is included or excluded:

Multiple Manifests Per Namespace

In gumbo, we will update the namespace configuration syntax to allow for multiple manifests to be specified for a given namespace. This allows common sets of components to be specified in a single manifest but shared in several namespaces.

Since a language namespace is required per document, we will merge the components from the top level ActionScript types, the Flex 3 framework, the gumbo framework and the FXG graphics framework into MXML 2009. Note that non-equivalent mapping collisions result in an error.

With all of these components merged into the language namespace, nearly all tags can be written in one namespace. Even though the choice prefix is arbitrary in XML, for stylistic reasons, the default prefix (an empty string) is strongly recommended for the language namespace as a convention. It also results in cleaner and easier to read MXML.

<Application xmlns="http://ns.adobe.com/mxml/2009">

    <Script />
    <Button />

</Application>

Namespaces and Component Disambiguation

In the rare case that a component property exists with the same name as a language attribute, the attribute representing the property can be qualified with a prefix mapping to the component namespace (as unqualified language attributes always override component properties if a naming collision exists).

<Application xmlns="http://ns.adobe.com/mxml/2009"
    xmlns:c="mycomponents.*">

    <c:MyComponent c:includeIn="MyCategory" />

</Application>

Component Library Manifests

MXML tag names can be mapped to fully qualified class names through the use of an MXML library manifest. A library manifest is an XML formatted file like so:

<?xml version="1.0"?>
<componentPackage>
    <component id="Accordion" class="mx.containers.Accordion"/>
    <component id="AddChild" class="mx.states.AddChild"/>
    <component id="AddChildAction" class="mx.effects.AddChildAction"/>
    ... etc ...
</componentPackage>

When packaging a library of component into a SWC, an XML namespace URI is associated with such a manifest to provide a scope to the MXML component tags so that they can be resolved to ActionScript classes during compilation. A namespace-mapped library manifest can also be configured in the <namespaces> section of a flex-config.xml mxmlc configuration file.

Local Source and Package Imports

Instead of creating component library manifests and SWCs, Flex developers generally write large portions of their application as local MXML and ActionScript source files - though the compiler must resolve these sources based on their location from the application root. This is similar to a package "import" in ActionScript. The syntax in MXML is to use a namespace and set the URI as the package path, for example:

<view:MyView xmlns:view="com.mycompany.views.*" />

We are not looking to change this syntax at this time.

2. Default Property and the Declarations Tag

In order to better support FXG and improve consistency between MXML and FXG, a subtle change will be made to default property handling and a new <Declarations> tag is introduced for non-default, non-visual property declarations. Visual children are allowed inside the <Declarations> tag but they will be instantiated as if they were non-visual and will not be added to a container via addChild().

We are removing the special case of not supporting "default properties" for a root MXML document tag.

If a default property is defined for a type, immediate child tags (that are not values for properties declared on the base class) continue to be interpreted as values for the default property but this now includes the children of a root tag.

For the BaseComponent class example below, the values variable is declared as the default property. Since this value is an Array, it will accept multiple values.

MyComponent.as

package com.mycompany.components
{

[DefaultProperty("values")]
public class BaseComponent
{
    public var values:Array;
}

}

The immediate children of the BaseComponent root tag are added to the values Array variable instead of being declared as new properties on the MyComponent sub-class.

MyComponent.mxml

<BaseComponent xmlns="http://ns.adobe.com/mxml/2009">

    <String>A Value</String>
    <String>Another Value</String>

</BaseComponent>

If a container class defines a "default property" it continues to take precedence over any special casing of visual children.

This also now includes the situation where it is used as a root tag. Note, however, that using default property on a container would be a rare scenario and none of the Flex 3 containers declare a default property today.

In this example, the BaseContainer declares its values variable as the default property.

BaseContainer.as

package com.mycompany.containers
{

import mx.core.IContainer;

[DefaultProperty("values")]
public class BaseContainer implements IContainer
{
    public var values:Array;
}

}

When this class is subclassed in MXML, immediate children (that are not values for properties declared on the base class) are added to the default property, including visual children such as a Label component. A side effect of this is that the Label would not be added to the Container through addChild() and thus the developer would be responsible for ensuring the contents of the default property values were rendered manually.

MyContainer.mxml

<BaseContainer xmlns="http://ns.adobe.com/mxml/2009">

    <Label text="Hello World" />
    <String>Value</String>

</BaseContainer>

If no default property is defined, then the parent tag must be a container and all immediate children must be visual components (i.e. implementations of mx.core.IUIComponent) or represent values of for properties declared on the base class, otherwise it is an error.

In this example below, BaseSimpleContainer is just a normal container and does not declare a default property.

BaseSimpleContainer.as

package com.mycompany.containers
{

import mx.core.IContainer;

public class BaseSimpleContainer implements IContainer
{
}

}

This container is sub-classed in MXML in MySimpleContainer below. Immediate non-visual children (such as the String tag) which represent new property declarations are not allowed and will cause errors at compile time. Note that if it were not for this error, the Label component would be associated with the container as a visual child through addChild() and rendered at runtime as usual.

MySimpleContainer.mxml

<BaseSimpleContainer xmlns="http://ns.adobe.com/mxml/2009">

    <Label text="Hello World!" />
    <String id="foo">Value</String> <!-- Compile Time Error -->

</BaseSimpleContainer>

Non-visual property declarations must go into a new <Declarations> section. Note that values for existing properties declared on the base class can remain inline as children.

In this example, BaseComponent defines a simple string variable called name.

BaseComponent.as

package com.mycompany.components
{

public class BaseComponent
{
    public var name:String;
}

}

In an MXML subclass MyComponent, the name variable can be set as usual on an immediate child, but any new property declarations must occur in the <Declarations> section.

MyComponent.mxml

<BaseComponent xmlns="http://ns.adobe.com/mxml/2009">

    <Declarations>
        <String id="text">Some value for a generated variable on the subclass.</String>
    <Declarations>

    <name>Value</name>

</BaseComponent>

As a second example, here is the situation with a container. We have a BaseContainer class that defines a title variable.

BaseContainer.as

package com.mycompany.containers
{

import mx.core.IContainer;

public class BaseContainer implements IContainer
{
    public var title:String;
}

}

In an MXML subclass MyContainer, the title value can be set as an immediate child of the root, as can visual children be added such as a Button. However, new properties for the subclass must be declared in the Declarations section.

MyContainer.mxml

<BaseContainer xmlns="http://ns.adobe.com/mxml/2009">

    <Button click="ws.getData()" label="Get Data" />
    <title>Bar Value</title>

    <Declarations>
        <WebService id="ws" wsdl="http://...">
            <operation name="getData" result="onResult(event)" />
        </WebService>
    <Declarations>

    <Script>
        import mx.rpc.events.ResultEvent;

        private void onResult(event:ResultEvent):void
        {
            //...
        }   
    </Script>

</BaseContainer>

Finally, to reiterate, it is also valid to place a visual child (i.e. an implementation of mx.core.IUIComponent) in a <Declarations> tag but it will not be added to the container via the normal addChild() mechanism. The developer may instead decide to programmatically render this visual component at runtime.

MyOtherContainer.mxml

<BaseContainer xmlns="http://ns.adobe.com/mxml/2009">

    <Declarations>
        <String id="newProperty">Hello World</String>
        <Button id="myButton" label="Click Me" />
    <Declarations>

</BaseContainer>

3. The Private Tag and Private Attributes

A new <Private> tag will be introduced in MXML 2009 for Gumbo and in FXG. The contents of the <Private> tag are ignored by the compiler and are not available at runtime, however the contents must be well formed and valid XML to preserve the integrity of the document.

Application developers and tools use the <Private> tag to store design-time information. The <Private> tag is a child of the root tag and it must appear as the last child in a document.

Private attributes will also be introduced in MXML 2009 and FXG. Private attributes are defined as any qualified attribute not in a language namespace. The compiler will ignore private attributes when encountered and this information is not available at runtime.

Note the <Private> tag and private attributes are not permitted in MXML 2006 documents.

An example of the <Private> tag in FXG:

<Graphic xmlns="http://ns.adobe.com/fxg/2008">

    <elements>
        <Rect width="50" height="50">
            <fill>
                <SolidColor color="0xFF0000" hint:ui="colorpicker" 
                    xmlns:hint="http://www.mycompany.com/graphicstool"/>
            </fill>
        </Rect>
    </elements>

    <Private>
        <!--
            All children are ignored as design-time metadata,
            including tags in language and component namespaces
         -->
        <x:Comments xmlns:x="http://www.mycompany.com/comments">Simple rectangle example</x:Comments>
        <Author>John Smith</Author>
        <Revision>1.4.5</Revision>
    </Private>

</Graphic>

An example of the <Private> tag and private attributes in MXML 2009:

<Application xmlns="http://ns.adobe.com/mxml/2009">

    <Label text="Hello World!" hint:locale="en_US"
        xmlns:hint="http://www.mycompany.com/langtool" />

    <Private>
        <!-- Design-time metadata -->
        <Author>John Smith</Author>
        <Revision>1.3.1</Revision>
    </Private>

</Application>

4. The Library Tag and Definitions

A section of a component or graphical asset may occasionally be required in several places in a document. Instead of cutting and pasting the same definition in each place, MXML 2009 and FXG introduce a new <Library> tag that allows for re-usable <Definition> to be declared in the document.

<Graphic xmlns="http://ns.adobe.com/fxg/2008" width="50" height="50">

    <Library>
        <Definition name="BlueRect">
            <Group>
                <elements>
                    <Rect width="200" height="200">
                        <fill>
                            <SolidColor color="#0000FF" />
                        </fill>
                    </Rect>
                </elements>
            </Group>
        </Definition>
    </Library>

    <elements>
        <BlueRect width="100" height="200"/>
        <BlueRect />
        <BlueRect width="300" height="300"/>
    </elements>

</Graphic>

Note that each Library definition is compiled into an ActionScript class that is a subclass of the type represented by the first node in the definition - in the above example this means our definition is a subclass of mx.graphics.Group.

When an instance of the definition is placed in the document it must be resolvable by the compiler to the newly created local component - the FXG specification requires definitions to be resolvable in the language namespace, so these definitions will have to become special generated Classes mapped into the language namespace (using a virtual manifest local to the document).

This is somewhat similar to MXML's inline Component tag, however, usages are in the language namespace and the scope of this class is limited to the document (and thus the definition should be treated as if it were a private ActionScript class).

Also note that a Definition can form the basis of another Definition:

<Graphic xmlns="http://ns.adobe.com/fxg/2008" width="50" height="50">

    <Library>
        <Definition name="NewRect">
            <GreenRect />
        </Definition>
        <Definition name="GreenRect">
            <Group>
                <Rect width="200" height="200">
                    <fill>
                        <SolidColor color="#0000FF" />
                    </fill>
                </Rect>
            </Group>
        </Definition>
    </Library>

    <NewRect width="100" height="200"/>

</Graphic>

Finally, a Library tag must appear as an immediate child of the root tag. The Library tag must be the first child of a document, with the only exception being that a mask tag can precede it. Only one Library tag can exist per document. Library or Definition tags must not be nested.

API Description

This specification outlines changes to the general language in the detailed description section and does not address any specific API.

B Features

None at this time.

Additional Implementation Details

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

Compiler Work

The Flex SDK compiler must be updated to recognize the new MXML 2009 language namespace and enforce the new rules outlined in the detailed design section.

Web Tier Compiler Impact

No changes are expected to the Flex Web Tier compiler beyond testing that integrating the Gumbo Flex SDK works as expected. No changes should apply to the OEM Compiler API as a result of these changes.

Flex Feature Dependencies

This specification covers features that overlap with FXG.

Backwards Compatibility

1. Namespace Changes

General changes for all MXML document versions

MXML documents that currently make no reference to a language namespace will now be invalid and the compiler will report an error. One and only one language namespace must be declared for each MXML document, and this declaration must appear on the document root tag.

Scenario 1. A Flex 3 application should compile with no changes.

Flex 3 MXML document in an application should compile without changes, with one exception. Documents must declare a language namespace, so in the following (rare) example, a custom MXML component exists but does not make reference to the MXML 2006 namespace. To fix this scenario, the MXML 2006 namespace is simply added to the root document tag.

OldContainer.mxml

• Flex 3

  <view:BaseView xmlns:view="com.mycompany.views.*">
      ...
  </view:BaseView>

• Flex 3 file updated for Gumbo

  <view:BaseView xmlns:view="com.mycompany.views.*" xmlns:mx="http://www.adobe.com/2006">
      ...
  </view:BaseView>

Scenario 2. Starting with a Flex 3 application, a developer creates a new MXML document and uses new components.

The new MXML document should declare the new language namespace http://ns.adobe.com/mxml/2009. The choice of prefix is arbitrary, but each namespace prefix must be unique. This MXML document should be able to participate as a new MXML based component in an existing Flex application (though still compiled with Gumbo, obviously). e.g.

NewContainer.mxml

<VBox xmlns="http://ns.adobe.com/mxml/2009">
    ...
</VBox>

Scenario 3. Starting with a Flex 3 application, a developer creates a new MXML document and uses new components and some existing components.

The new MXML document should declare the new language namespace http://ns.adobe.com/mxml/2009. Each namespace requires a unique prefix, but the choice is arbitrary.

NewContainer.mxml

<VBox xmlns="http://ns.adobe.com/mxml/2009">

    <Button label="Halo Button" />
    <FxButton label="Spark Button" />

</VBox>

Scenario 4. Starting with a Flex 3 application, a developer takes an existing MXML document and wants to add some new components to it.

The user must migrate the document to the MXML 2009 namespace and will then have access to the new components.

Scenario 5. A developer creates a new MXML document and wishes to make use of an FXG asset.

An FXG document can be referenced like a local component source using the package import syntax in a custom namespace.

RevampedContainer.mxml

<VBox xmlns="http://ns.adobe.com/mxml/2009">

    <g:GraphicalAsset xmlns:g="*" />

</VBox>

GraphicalAsset.fxg

<Graphic xmlns="http://ns.adobe.com/fxg/2008">
    <elements>
        <Rect width="100" height="100">
            <stroke>
                <SolidColorStroke color="#FF0000" weight="1" />
            </stroke>
        </Rect>
    </elements>

</Graphic>

Warnings/Deprecation

MXML documents that do not declare a language namespace, such as http://www.adobe.com/2006/mxml or http://ns.adobe.com/mxml/2009 will result in a compiler error.

Accessibility

There are no expected changes to accessibility with this feature.

Performance

While a performance impact is not anticipated, monitoring of start-up time for each compile session, either full or incremental, should be monitored if the number of swcs change.

Globalization

No globalization issues are anticipated for this feature.

Localization

Compiler Features

New compiler errors and warnings will be added to compiler_en.properties for this feature and require localization as usual.

Framework Features

This feature is not expected to introduce any framework localization changes.

Issues and Recommendations

None at this time.

Documentation

Once this specification is signed off, significant documentation will be required to capture the changes and explain the usage scenarios.