GlossaryNamespace 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. Summary and BackgroundThis specification outlines the proposed changes to the MXML language in Gumbo, the codename for the next release of Flex. 1. NamespacesNamespaces 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. 2. Default Property and the Declarations TagFor 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. 3. The Private Tag and Private AttributesThe <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. 4. The Library Tag and DefinitionsThe <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. 5. The id attributeIn 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. <!-- MXML id and component id property --> <s:span fx:id="span1" /> <!-- MXML id only --> <s:span fx:id="span1" /> Usage ScenarioPlease keep the following usage scenarios in mind for each language change: 1. A Flex 3 application should continue to compile. See the Backwards Compatibility section for a discussion of how developers will handle these usage scenarios. Detailed Description1. NamespacesMXML 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 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:
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.
<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" />
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" />
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 NamespaceIn 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. Namespaces and Component DisambiguationIn 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> Component Library ManifestsMXML 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: <?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 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. Local Source and Package ImportsInstead 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.*" />
We are not changing this syntax at this time. 2. Default Property and the Declarations TagIn 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(). 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 <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> 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. 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;
[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 <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> 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 {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> <!-- Compile Time Error -->
</ct:BaseSimpleContainer>
Non-visual property declarations must go into a new <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.*"> <mx:Button click="ws.getData()" label="Get Data" /> <ct:title>Bar Value</ct:title> <fx:Declarations> <mx:WebService id="ws" wsdl="http://..."> <mx:operation name="getData" result="onResult(event)" /> </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> 3. The Private Tag and Private AttributesA 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> <!-- 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 <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> <!-- Design-time metadata --> <Author>John Smith</Author> <Revision>1.3.1</Revision> </fx:Private> </s:Application> 4. The Library Tag and DefinitionsA 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> 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> 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. API DescriptionThis specification outlines changes to the general language in the detailed description section and does not address any specific API. B FeaturesNone at this time. Additional Implementation DetailsEnter implementation/design details for the feature here. This section may be updated after the spec signs off. Compiler WorkThe 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 ImpactNo 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 DependenciesThis specification covers features that overlap with FXG. Backwards Compatibility1. Namespace ChangesGeneral changes for all MXML document versionsMXML 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
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 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 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 GraphicalAsset.fxg Warnings/DeprecationMXML documents that do not declare a language namespace, such as http://www.adobe.com/2006/mxml or http://ns.adobe.com/mxml/2009will result in a compiler error. AccessibilityThere are no expected changes to accessibility with this feature. PerformanceWhile 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. GlobalizationNo globalization issues are anticipated for this feature. LocalizationCompiler FeaturesNew compiler errors and warnings will be added to compiler_en.properties for this feature and require localization as usual. Framework FeaturesThis feature is not expected to introduce any framework localization changes. Issues and RecommendationsNone at this time. DocumentationOnce this specification is signed off, significant documentation will be required to capture the changes and explain the usage scenarios. |
MXML2009
發表評論
所有評論
還沒有人評論，想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章