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 MXML tag names or CSS type selectors to qualified ActionScript class names. There is a one-to-one mapping between a tag name and a class name, or a CSS type selector 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.
This specification outlines the proposed changes to the MXML language in Gumbo, the codename for the next release of Flex.
Namespaces in MXML are used to achieve several things, such as to specify the language version, to provide a scope to map an XML tag name to ActionScript class name, to map a CSS type selector to an ActionScript class name, 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 both 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. Only special language tags will be declared in the MXML 2009 namespace. Components will now be declared in their own namespaces, with the Flex 3 or 'MX' components in a MX library namespace and the new Gumbo Spark components in a spark library namespace.
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.
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 <fx: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 <fx:Declarations>
section.
The <fx: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 <fx: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.
The <fx:Library>
tag is a new element in MXML 2009 and FXG that is used to declare zero or more named graphic <fx: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.
In MXML the id attribute is a special attribute. It is used to define the name of a generated property declaration on the underlying ActionScript class and it allows the property to be referenced in script and binding expressions.
However, if a type has an id property the developer may intend the attribute to represent a property assignment and not just as an identifier in MXML. In Gumbo, if the type of the component is found to have a suitable id property (a public, non-static, writable id property) the compiler will set it using the id attribute value. To opt out of this new behavior, the developer can qualify the id attribute with the language namespace prefix.
<s:span fx:id="span1">
<s:span fx:id="span1">
</s:span></s:span>
Please keep the following usage scenarios in mind for each language change:
See the Backwards Compatibility section for a discussion of how developers will handle these usage scenarios.
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 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.
Flex 3
Gumbo
xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:fx="http://ns.adobe.com/mxml/2009"
<mx:Binding>
<fx:Binding>
<mx:Component>
<fx:Component>
<mx:Metadata>
<fx:Metadata>
<mx:Model>
<fx:Model>
<mx:Repeater>
<fx:Repeater>
<mx:Script>
<fx:Script>
<mx:Style>
<fx:Style>
Also, the following language tags are new to Gumbo:
Flex 3
Gumbo
xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:fx="http://ns.adobe.com/mxml/2009"
N/A
<fx:Declarations>
N/A
<fx:Definition>
N/A
<fx:DesignLayer>
N/A
<fx:Library>
N/A
<fx:Private>
N/A
<fx:Reparent>
ActionScript 3 built-in types are special cased by the compiler and are not tied to any component framework. As such, these top level classes will be seen as language tags and will be part of the MXML 2009 namespace.
Flex 3
Gumbo (MXML 2009)
xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:fx="http://ns.adobe.com/mxml/2009"
<mx:Array>
<fx:Array>
<mx:Boolean>
<fx:Boolean>
<mx:Class>
<fx:Class>
<mx:Date>
<fx:Date>
<mx:Function>
<fx:Function>
<mx:int>
<fx:int>
<mx:Number>
<fx:Number>
<mx:Object>
<fx:Object>
<mx:RegExp>
<fx:RegExp>
<mx:String>
<fx:String>
<mx:uint>
<fx:uint>
N/A
<fx:Vector>
<mx:XML>
<fx:XML>
<mx:XMLList>
<fx:XMLList>
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, in the unusual situation that the default prefix (i.e. the empty string) was used for the language namespace there would be 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.
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
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).
<c:mycomponent xmlns:c="library://mycompany/flex/components" xmlns:fx="http://ns.adobe.com/mxml/2009" c:includein="SomeValue" includein="StateA,StateB">
</c:mycomponent>
In the more common situation that a non-default prefix such as fx:
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).
<s:application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:foo="http://somedesigntool.com/2008" foo:revision="Some design time info">
</s:application>
The following is a list of Application root tag language attributes.
Flex 3
Gumbo
<mx:Application
<s:Application
xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns="http://ns.adobe.com/mxml/2009"
frameRate="..."
frameRate="..."
implements="..."
implements="..."
pageTitle="..."
pageTitle="..."
preloader="..."
preloader="..."
scriptRecursionLimit="..."
scriptRecursionLimit="..."
scriptTimeLimit="..."
scriptTimeLimit="..."
usePreloader="..."
usePreloader="..."
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.
Flex 3
Gumbo
<mx:Application
<s:Application
xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns="http://ns.adobe.com/mxml/2009"
}
}
}
}
}
}
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.
Flex 3
Gumbo
<mx:Button id="..."
<s:Button id="..."
New to Gumbo are additional Enhanced States Syntax language attributes to control which states a component is included or excluded:
Flex 3
Gumbo
N/A
<c:ComponentXYZ includeIn="..."
N/A
<c:ComponentXYZ excludeFrom="..."
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.
Note that non-equivalent mapping collisions result in an error.
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).
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:c="mycomponents.*">
<c:mycomponent c:includein="MyCategory">
</s:Application>
</c:mycomponent>
MXML tag names and CSS type selectors 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:
<componentPackage>
<component id="Accordion" class="mx.containers.Accordion">
<component id="AddChild" class="mx.states.AddChild">
<component id="AddChildAction" class="mx.effects.AddChildAction">
... etc ...
</componentPackage>
</component></component></component>
When packaging a library of components into a SWC, an XML namespace URI is associated with such a manifest to provide a scope to the MXML component tags or CSS type selectors so that they can be resolved to fully qualified ActionScript class names during compilation. A namespace-mapped library manifest can also be configured in the <namespaces>
section of a flex-config.xml
mxmlc configuration file.
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 in this case the compiler resolves these sources based on their location from the application root (or any additional configured source paths). 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.*">
</view:myview>
We are not changing this syntax at this time.
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 <fx:Declarations>
tag is introduced for non-default, non-visual property declarations. Visual children are allowed inside the <fx:Declarations>
tag but they will be instantiated as if they were non-visual and will not be added to a container via addChild()
.
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
{
<a href="DefaultProperty%28%26quot%3Bvalues%26quot%3B%29">DefaultProperty("values")</a>
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
<c:BaseComponent xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:c="com.mycompany.components.*">
<s:String>A Value</s:String>
<s:String>Another Value</s:String>
</c:BaseComponent>
This also now includes the situation where it is used as a root tag. Close attention should be paid to this scenario as using default property on a Container would have been a rare scenario Flex 3 since none of the Flex Containers declared a default property.
In this example, the BaseContainer
declares its values variable as the default property.
BaseContainer.as
package com.mycompany.containers
{
import mx.core.IContainer;
<a href="DefaultProperty%28%26quot%3Bvalues%26quot%3B%29">DefaultProperty("values")</a>
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
<ct:BaseContainer xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:ct="com.mycompany.containers.*">
<mx:label text="Hello World">
<mx:String>Value</mx:String>
</ct:BaseContainer>
</mx:label>
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
{code:xml}
<ct:BaseSimpleContainer xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:ct="com.mycompany.containers.*">
<mx:label text="Hello World!">
<mx:String id="foo">Value</mx:String>
</ct:BaseSimpleContainer>
</mx:label>
<fx: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
<c:BaseComponent xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:c="com.mycompany.components.*">
<fx:Declarations>
<mx:String id="text">Some value for a generated variable on the subclass.</mx:String>
<fx:Declarations>
<c:name>Value</c:name>
</c: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
<ct:BaseContainer xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:ct="com.mycompany.containers.*">
wzxhzdk:55
<ct:title>Bar Value</ct:title>
<fx:Declarations>
<mx:WebService id="ws" wsdl="http://...">
wzxhzdk:56
</mx:WebService>
<fx:Declarations>
<fx:Script>
import mx.rpc.events.ResultEvent;
private void onResult(event:ResultEvent):void
{
//...
}
</fx:Script>
</ct:BaseContainer>
Finally, to reiterate, it is also valid to place a visual child (i.e. an implementation of mx.core.IUIComponent) in a <fx: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
<ct:BaseContainer xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:ct="com.mycompany.containers.*">
<fx:Declarations>
<mx:String id="newProperty">Hello World</String>
<mx:button id="myButton" label="Click Me">
<fx:Declarations>
</ct:BaseContainer>
</mx:button>
A new <fx:Private>
tag will be introduced in MXML 2009 for Gumbo and in FXG. The contents of the <fx: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 <fx:Private>
tag to store design-time information. The <fx: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 <fx:Private>
tag and private attributes are not permitted in MXML 2006 documents.
An example of the <fx: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>
<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>
</solidcolor>
An example of the <fx:Private>
tag and private attributes in MXML 2009:
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark">
<s:simpletext text="Hello World!" hint:locale="en_US" xmlns:hint="http://www.mycompany.com/langtool">
<fx:Private>
<Author>John Smith</Author>
<Revision>1.3.1</Revision>
</fx:Private>
</s:Application>
</s:simpletext>
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 <fx:Library>
tag that allows for re-usable <fx: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>
</bluerect></bluerect></bluerect></solidcolor>
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 spark.components.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>
</newrect></solidcolor></greenrect>
Finally, a <fx:Library>
tag must appear as an immediate child of the root tag. The <fx: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. <fx:Library>
or <fx:Definition>
tags must not be nested.
This specification outlines changes to the general language in the detailed description section and does not address any specific API.
None at this time.
Enter implementation/design details for the feature here. This section may be updated after the spec signs off.
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.
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.
This specification covers features that overlap with FXG.
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.
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>
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
<s:VGroup xmlns:fx="http://ns.adobe.com/mxml/2009"
mlns:s="library://ns.adobe.com/flex/spark">
...
</s:VGroup>
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
<mx:VBox xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx">
<mx:button label="MX Button">
<s:button label="Spark Button">
</mx:VBox>
</s:button></mx:button>
The user must migrate the document to the MXML 2009 namespace and will then have access to the new components.
An FXG document can be referenced like a local component source using the package import syntax in a custom namespace.
RevampedContainer.mxml
<s:VGroup xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark">
<g:graphicalasset xmlns:g="*">
</s:VGroup>
</g:graphicalasset>
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>
</solidcolorstroke>
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.
There are no expected changes to accessibility with this feature.
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.
No globalization issues are anticipated for this feature.
New compiler errors and warnings will be added to compiler_en.properties for this feature and require localization as usual.
This feature is not expected to introduce any framework localization changes.
None at this time.
Once this specification is signed off, significant documentation will be required to capture the changes and explain the usage scenarios.