MXML filenames must adhere to the following naming conventions:

• Filenames must be valid ActionScript identifiers, which means they must start with a letter or underscore character (_), and they can only contain letters, numbers, and underscore characters after that.

• Filenames must not be the same as ActionScript class names, component id values, or the word application. Do not use filenames that match the names of MXML tags that are in the fx:, s:, or mx: namespace.

• Filenames must end with a lowercase .mxml file extension.

An MXML tag that corresponds to an ActionScript class uses the same naming conventions as the ActionScript class. Class names begin with a capital letter, and capital letters separate the words in class names. For example, when a tag corresponds to an ActionScript class, its properties correspond to the properties and events of that class.

You usually specify the value of a scalar property as a property of a component tag, as the following example shows:

 <s:Label width="50" height="25" text="Hello World"/>

The valid values of many component properties are defined by static constants, where these static constants are defined in an ActionScript class. In MXML, you can either use the static constant to set the property value, or use the value of the static constant, as the following example shows:

 <!-- Set the property using the static constant. --> 
 <s:Wipe direction="{spark.effects.WipeDirection.LEFT}"> 
 	... 
 </s:Wipe> 
  
 <!-- Set the property using the value of the static constant. --> 
 <s:Wipe direction="left"> 
 	... 
 </s:Wipe>

The Wipe effect defines a property named direction that defines the direction of the wipe effect. In this example, you explicitly set the direction property to cause the wipe effect to move left.

In the first example, you set the direction property using a static constant named LEFT, which is defined in the spark.effects.WipeDirection class. In MXML, you must use data binding syntax when setting a property value to a static constant. The advantage of using the static constant is that the Flex compiler recognizes incorrect property values, and issues an error message at compile time.

Alternatively, you can set the value of the direction property to the value of the static constant. The value of the LEFT static constant is "left". When you use the value of the static constant to set the property value, the Flex compiler cannot determine if you used an unsupported value. If you incorrectly set the property, you will not know until you get a run-time error.

In ActionScript, you should use static constants to set property values whenevera possible, as the following example shows:

 var myWipe:Wipe = new Wipe(); 
 myWipe.direction=spark.effects.WipeDirection.LEFT;

Many Flex components define a single default property. The default property is the MXML tag that is implicit for content inside of the MXML tag if you do not explicitly specify a property. For example, consider the following MXML tag definition:

 <s:SomeTag> 
 	anything here 
 </s:SomeTag>

If this tag defines a default property named default_property, the preceding tag definition is equivalent to the following code:

 <s:SomeTag> 
 	<s:default_property> 
 		anything here 
 	</s:default_property> 
 </s:SomeTag>

It is also equivalent to the following code:

 <s:SomeTag default_property="anything here"/>

The default property provides a shorthand mechanism for setting a single property. For a Spark List, the default property is the dataProvider property. Therefore, the two List definitions in the following code are equivalent:

<?xml version="1.0"?> 
<!-- mxml\DefProp.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"> 
    <s:layout> 
        <s:HorizontalLayout/> 
    </s:layout> 
 
    <!-- Omit the default property. --> 
    <s:List> 
        <s:ArrayCollection> 
            <fx:String>AK</fx:String> 
            <fx:String>AL</fx:String> 
            <fx:String>AR</fx:String> 
        </s:ArrayCollection> 
    </s:List> 
    
    <!-- Explicitly speficy the default property. --> 
    <s:List> 
        <s:dataProvider> 
            <s:ArrayCollection> 
                <fx:String>AK</fx:String> 
                <fx:String>AL</fx:String> 
                <fx:String>AR</fx:String> 
            </s:ArrayCollection> 
        </s:dataProvider> 
    </s:List>    
</s:Application>

Not all Flex components define a default property. To determine the default property for each component, see the ActionScript 3.0 Reference for Apache Flex.

You can also define a default property when you create a custom component. For more information, see Metadata tags in custom components.

When setting a property value in MXML, you can escape a reserved character by prefixing it with the backslash character (\), as the following example shows:

<?xml version="1.0"?> 
<!-- mxml\EscapeChar.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"> 
 
    <s:Label text="\{\}"/> 
 
</s:Application>

In this example, you want to use literal curly brace characters ({ }) in a text string. But Flex uses curly braces to indicate a data binding operation. Therefore, you prefix each curly brace with the backslash character to cause the MXML compiler to interpret them as literal characters.

The MXML compiler automatically escapes the backslash character in MXML when the character is part of the value specified for a property of type String. Therefore, it always converts "\" to "\\".

This is necessary because the ActionScript compiler recognizes "\\" as the character sequence for a literal "\" character, and strips out the leading backslash when it initializes the property value.

For properties of type String, you can insert a newline character in the String in several ways:

• By using data binding with the '\n' characters in your String value in MXML

• By inserting the 
 code in your String value in MXML

• By inserting "\n" in an ActionScript String variable used to initialize the MXML property

To use data binding, wrap the newline character in curly brace characters ({ }), as the following example shows:

 <s:TextArea width="100%" text="Display{'\n'}Content"/>

To use the 
 code to insert a newline character, include that code in the property value in MXML, as the following example shows:

 <s:TextArea width="100%" text="Display&#13;Content"/>

To use an ActionScript String variable to insert a newline character, create an ActionScript variable, and then use data binding to set the property in MXML, as the following example shows:

 <fx:Script> 
 	<![CDATA[ 
 		[Bindable] 
 		public var myText:String = "Display" + "\n" + "Content"; 
 	]]> 
 </fx:Script> 
  
 <s:TextArea width="100%" text="{myText}"/>

In this example, you set the text property of the TextArea control to a value that includes a newline character.

Notice that this example includes the [Bindable] metadata tag before the property definition. This metadata tag specifies that the myText property can be used as the source of a data binding expression. Data binding automatically copies the value of a source property of one object to the destination property of another object at run time when the source property changes.

If you omit this metadata tag, the compiler issues a warning message specifying that the property cannot be used as the source for data binding. For more information, see Data binding.

<?xml version="1.0"?> 
<!-- mxml\DefPropMixed.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"> 
 
    <s:RichText  fontFamily="Verdana" fontWeight="bold"> 
        <s:content> 
            <fx:String>Hello World!</fx:String><s:br/> 
            <fx:String>Hello Universe</fx:String><s:br/> 
            Hello Flex! 
        </s:content> 
    </s:RichText> 
</s:Application>

In this example, the RichText.content property is of type Object. The property value contains values defined by <fx:String> tag, and by character data ("Hello Flex!"). Character data is almost always converted to a value of type String. However, an Array property may be defined to support an explicit data type for its values. In that case, the compiler converts the character data to the appropriate data type.

When a class has a property that takes an Array as its value, you can represent the property in MXML using child tags. The component in the following example has a children property that contains an Array of numbers:

 <mynamespace:MyComponent> 
 	<mynamespace:children> 
 		<fx:Array> 
 			<fx:Number>94062</fx:Number> 
 			<fx:Number>14850</fx:Number> 
 			<fx:Number>53402</fx:Number> 
 		</fx:Array> 
 	</mynamespace:children> 
 </mynamespace:MyComponent>

The <fx:Array> and </fx:Array> tags around the Array elements are optional. Therefore, you can also write this example as the following code shows:

<mynamespace:MyComponent> 
	<mynamespace:children> 
		<fx:Number>94062</fx:Number> 
		<fx:Number>14850</fx:Number> 
		<fx:Number>53402</fx:Number> 
	</mynamespace:children> 
</mynamespace:MyComponent>

In this example, since the data type of the children property is defined as Array, Flex automatically converts the three number definitions into a three-element array.

Component developers may have specified additional information within the component definition that defines the data type of the Array elements. For example, if the developer specified that the dataProvider property supports only String elements, this example would cause a compiler error because you specified numbers to it. The ActionScript 3.0 Reference for Apache Flex documents the Array properties that define a required data type for the Array elements.

When a component has a property that takes an object as its value, you can represent the property in MXML using a child tag with tag attributes, as the following example shows:

 <mynamespace:MyComponent> 
 	<mynamespace:nameOfProperty> 
 		<mynamespace:typeOfObject prop1="val1" prop2="val2"/> 
 	</mynamespace:nameOfProperty> 
 </mynamespace:MyComponent>

The following example shows an ActionScript class that defines an Address object. This object is used as a property of the PurchaseOrder component in the next example.

 class Address  { 
 	public var name:String; 
 	public var street:String; 
 	public var city:String; 
 	public var state:String; 
 	public var zip:Number; 
 }

The following example shows an ActionScript class that defines a PurchaseOrder component that has a property type of Address:

 import example.Address; 
  
 class PurchaseOrder { 
 	public var shippingAddress:Address; 
 	public var quantity:Number; 
 ... 
 }

In MXML, you define the PurchaseOrder component as the following example shows:

 <mynamespace:PurchaseOrder quantity="3" xmlns:e="example"> 
	 <mynamespace:shippingAddress> 
 		<mynamespace:Address name="Fred" street="123 Elm St."/> 
 	</mynamespace:shippingAddress> 
 </mynamespace:PurchaseOrder>

If the value of the shippingAddress property is a subclass of Address (such as DomesticAddress), you can declare the property value, as the following example shows:

 <mynamespace:PurchaseOrder quantity="3" xmlns:e="example"> 
 	<mynamespace:shippingAddress> 
 		<mynamespace:DomesticAddress name="Fred" street="123 Elm St."/> 
 	</mynamespace:shippingAddress> 
 </mynamespace:PurchaseOrder>

If the property is explicitly typed as Object like the value property in the following example, you can specify an anonymous object using the <fx:Object> tag.

 class ObjectHolder { 
 	public var value:Object 
 }

The following example shows how you specify an anonymous object as the value of the value property:

 <mynamespace:ObjectHolder> 
 	<mynamespace:value> 
 		<fx:Object foo='bar'/> 
 	</mynamespace:value> 
 </mynamespace:ObjectHolder>

When a component has a property of type Object that takes an Array as its value, you can represent the property in MXML using child tags, as the following example shows:

 <mynamespace:MyComponent> 
 	<mynamespace:nameOfObjectProperty> 
 		<fx:Array> 
 			<fx:Number>94062</fx:Number> 
 			<fx:Number>14850</fx:Number> 
 			<fx:Number>53402</fx:Number> 
 		</fx:Array> 
 	</mynamespace:nameOfObjectProperty> 
 </mynamespace:MyComponent>

In this example, you initialize the Object property to a three-element array of numbers.

As described in the section Setting Arrays of scalar values, the <fx:Array> tag and the </fx:Array> tag around the Array elements are optional and may be omitted, as the following example shows:

 <mynamespace:MyComponent> 
 	<mynamespace:nameOfObjectProperty> 
 		<fx:Number>94062</fx:Number> 
 		<fx:Number>14850</fx:Number> 
 		<fx:Number>53402</fx:Number> 
 	</mynamespace:nameOfObjectProperty> 
 </mynamespace:MyComponent>

The only exception to this rule is when you specify a single Array element for the Object property. In that case, Flex does not create an Object containing a single-element array, but instead creates an object and sets it to the specified value. This is a difference between the following two lines:

 object=[element] // Object containing a one-element array 
 object=element // object equals value

If you want to create a single-element array, include the <fx:Array> and </fx:Array> tags around the array element, as the following example shows:

 <mynamespace:MyComponent> 
 	<mynamespace:nameOfObjectProperty> 
 		<fx:Array> 
 			<fx:Number>94062</fx:Number> 
 		</fx:Array> 
 	</mynamespace:nameOfObjectProperty> 
 </mynamespace:MyComponent>

When a component has a property that takes an Array of objects as its value, you can represent the property in MXML using child tags, as the following example shows:

 <mynamespace:MyComponent> 
 	<mynamespace:nameOfProperty> 
 		<fx:Array> 
 			<mynamespace:objectType prop1="val1" prop2="val2"/> 
 			<mynamespace:objectType prop1="val1" prop2="val2"/> 
 			<mynamespace:objectType prop1="val1" prop2="val2"/> 
 		</fx:Array> 
 	</mynamespace:nameOfProperty> 
 </mynamespace:MyComponent>

The component in the following example contains an Array of ListItem objects. Each ListItem object has properties named label and data.

 <mynamespace:MyComponent> 
 	<mynamespace:dataProvider> 
 		<fx:Array> 
 			<mynamespace:ListItem label="One" data="1"/> 
 			<mynamespace:ListItem label="Two" data="2"/> 
 		</fx:Array> 
 	</mynamespace:dataProvider> 
 </mynamespace:MyComponent>

The following example shows how you specify an anonymous object as the value of the dataProvider property:

 <mynamespace:MyComponent> 
 	<mynamespace:dataProvider> 
 		<fx:Array> 
 			<fx:Object label="One" data="1"/> 
 			<fx:Object label="Two" data="2"/> 
 		</fx:Array> 
 	</mynamespace:dataProvider> 
 </mynamespace:MyComponent>

As described in the section Setting Arrays of scalar values, the <fx:Array> tag and the </fx:Array> tag around the Array elements are optional and may be omitted, as the following example shows:

 <mynamespace:MyComponent> 
 	<mynamespace:dataProvider> 
 		<fx:Object label="One" data="1"/> 
 		<fx:Object label="Two" data="2"/> 
 	</mynamespace:dataProvider> 
 </mynamespace:MyComponent>

The Vector class lets you access and manipulate a vector. A Vector is an array whose elements all have the same data type. The data type of a Vector's elements is known as the Vector's base type. The base type can be any class, including built in classes and custom classes. The base type is specified when declaring a Vector variable as well as when creating an instance by calling the class constructor.

In MXML, define an instance of a Vector class in a <fx:Declarations> block, as the following example shows:

<fx:Declarations>  
	<fx:Vector type="String">  
		<fx:String>one</fx:String> 
		<fx:String>two</fx:String> 
		<fx:String>three</fx:String> 
	</fx:Vector> 
   
	<fx:Vector type="Vector.&lt;String&gt;"> 
		<fx:Vector type="String"> 
			<fx:String>one</fx:String> 
			<fx:String>two</fx:String> 
			<fx:String>three</fx:String> 
		</fx:Vector> 
	</fx:Vector> 
</fx:Declarations>

The first example defines a Vector with a base type of String. The second example defines a Vector of Vectors of type String. Notice that you use the HTML escape characters &lt; and &gt; , instead of < and >, in the nested Vector. This syntax is necessary to conform to XML syntax rules.

If a component contains a property that takes XML data, the value of the property is an XML fragment to which you can apply a namespace. In the following example, the value property of the MyComponent object is XML data:

 <mynamespace:MyComponent> 
 	<mynamespace:value xmlns:a="http://www.example.com/myschema"> 
 		<fx:XML> 
 			<a:purchaseorder> 
 				<a:billingaddress> 
 				... 
 				</a:billingaddress> 
 				... 
 			</a:purchaseorder> 
 		</fx:XML> 
 	</mynamespace:value> 
 </mynamespace:MyComponent>

A style property of an MXML tag differs from other properties because it corresponds to an ActionScript style, rather than to a property of an ActionScript class. You set these properties in ActionScript using the setStyle( stylename , value ) method rather than object.property=value notation.

For example, you can set the fontFamily style property in MXML, as the following code shows:

 <s:TextArea id="myText" text="hello world" fontFamily="Tahoma"/>

This MXML code is equivalent to the following ActionScript code:

 myText.setStyle("fontFamily", "Tahoma");

You define style properties in custom ActionScript classes by using the [Style] metadata tags, rather than defining them as ActionScript variables or setter/getter methods. For more information, see Metadata tags in custom components.

An event property of an MXML tag lets you specify the event listener function for an event. This property corresponds to setting the event listener in ActionScript using the addEventListener() method.

For example, you can set the creationComplete event property in MXML, as the following code shows:

 <s:TextArea id="myText" creationComplete="creationCompleteHandler();"/>

This MXML code is equivalent to the following ActionScript code:

 myText.addEventListener("creationComplete", creationCompleteHandler); 

You define event properties in custom ActionScript classes by using the [Event] metadata tags, rather than defining them as ActionScript variables or setter/getter methods. For more information, see Metadata tags in custom components.

Some MXML tags, such as the <fx:Script> tag, have a property that takes a URL of an external file as a value. For example, you can use the source property in an <fx:Script> tag to reference an external ActionScript file instead of typing ActionScript directly in the body of the <fx:Script> tag.

MXML supports the following types of URLs:

• Absolute, as in the following example:

   <fx:Style source="http://www.somesite.com/mystyles.css">

• A path used at compile time that is relative to the application, as in the following example:

   <fx:Script source="/myscript.as"/>

• Relative to the current file location, as in the following example:

   <fx:Script source="../myscript.as"/>

• A path used at run time that is relative to the context root of the Java web application in which a Flex application is running. For example:

   <mx:HTTPService url="@ContextRoot()/directory/myfile.xml"/>

  You can only use the @ContextRoot() token if you are using the web-tier compiler or if you set the value of the context-root compiler argument

For a property of type RegExp, you can specify its value in MXML using the following format:

 "/pattern/flags"

pattern

Specifies the regular expression within the two slashes. Both slashes are required.

flags

(Optional) Specifies any flags for the regular expression.

For example, the regExpression property of an MXML component is of type RegExp. Therefore, you can set its value as the following example shows:

 <mynamespace:MyComponent regExpression="/\Wcat/gi"/>

Or set it using child tags, as the following example shows:

 <mynamespace:MyComponent> 
 	<mynamespace:regExpression>/\Wcat/gi</mynamespace:regExpression>	 
 </mynamespace:MyComponent>

The flags portion of the regular expression is optional, so you can also specify it as the following example shows:

 <mynamespace:MyComponent regExpression="/\Wcat/"/>

Compiler tags are tags that do not directly correspond to ActionScript objects or properties. They include the following:

• <fx:Binding>

• <fx:Component>

• <fx:Declarations>

• <fx:Definition>

• <fx:DesignLayer>

• <fx:Library>

• <fx:Metadata>

• <fx:Model>

• <fx:Private>

• <fx:Reparent>

• <fx:Script>

• <fx:Style>

MXML has the following syntax requirements:

• The id property is not required on any tag.

• The id property is not allowed on the root tag.

• Boolean properties take only true and false values.

• The <fx:Binding> tag requires both source and destination properties.

• The <fx:Binding> tag cannot contain an id property.