The declarative XML-based user interface markup language
MXML is an XML-based language introduced in 2004 by Macromedia. In Royale you use it to lay out user-interface components. You can create an application in Royale using only ActionScript, but it takes a lot more work.
Most Royale applications have an MXML file as the main file. It provides the structure of the application. The main MXML file from our very simple hello world example looks a bit like this:
<?xml version="1.0" encoding="utf-8"?>
</--
A comments field that could include a copyright statement, license notice, author notice,
a statement of the purpose of the file, and
other information useful for future file maintenance.
-->
<js:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:js="library://ns.apache.org/royale/express">
<js:initialView>
<js:View>
<js:Label text="Hello World" />
</js:View>
</js:initialView>
</js:Application>
You also build components that you might incorporate into an application using an MXML file. A component with a card layout to display a set of clickable buttons might look like this:
<?xml version="1.0" encoding="utf-8"?>
</--
A comments field that could include a copyright statement, license notice, author notice,
a statement of the purpose of the file, and
other information useful for future file maintenance.
-->
<j:Group xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:j="library://ns.apache.org/royale/jewel"
xmlns:html="library://ns.apache.org/royale/html">
<fx:Script>
<![CDATA[
private function clickHandler(event:MouseEvent):void {
button.emphasis = (button.emphasis == Button.PRIMARY) ? "" : Button.PRIMARY;
}
]]>
</fx:Script>
<j:Card width="600">
<html:H3 text="items expand test"/>
<j:HGroup itemsExpand="true" gap="3">
<j:Button text="Hello" click="clickHandler(event)"/>
<j:Button text="Apache"/>
<j:Button text="Royale!!!!"/>
</j:HGroup>
</j:Card>
</j:Group>
The more complex the application is, the more things the main MXML file needs to be able to support and do. Typically, a developer organizes the file so it is easy to locate things in it. Some elements must be inside certain tags, and for others you have a lot of flexibility. However, if you are working in a team, it is good to have an agreement about what goes where so nobody wastes time or tries to add code that already exists somewhere else in the file.
Your main MXML file has two essential elements:
The header: In the example above, the header tag <?xml version="1.0" encoding="utf-8"?> has two parts:
utf-8, but some applications use different encodings that suit their specific needs.The main tag: This tag includes everything else on the page. For a full application, it usually starts <js:Application... and ends as the last line of the file: </js:Application>. In the component example above for a module that could be included in a larger application, the main tag defines a group: <j:Group... and closes at the end of the file: </:Group>.
The main tag's attributes are very important for configuring and launching the application. The attributes can include:
xmlns:j="library://ns.apache.org/royale/jewel in the main tag, we can later deploy buttons from that namespace (like <j:Button text="Apache"/>) very simply, using just “j” instead of the full URL of the namespace.initialize="addEventListener('dataReady', dataReadyHandler);configurator.send()")You write what this file does, how it does it, and what the user sees as a result, inside this main tag, after it opens and before its closing tag at the end of the file. See the “What your file may have” section, below.
It is good to add, just under the XML declaration line, a comments block that includes a copyright statement, license notice, author notice, a statement of the purpose of the file, and other information useful for future file maintenance. The file will compile and run just fine without such a statement; but if you are building code others will see, try to maintain, and possibly want to reuse, you should include it.
A lot happens inside the main tag, and things can get complicated. The following elements to not all have to appear in every app or module, and do not have to appear in a specific order for the app to compile and run. But it's good to have a pattern you follow, especially if you are working as part of a team, so you can avoid wasting time trying to find something, forgetting to add something, or adding it twice.
Declarations: Define things like effects, validators, and formatters, and send and request data, inside the <fx:Declarations>...</fx:Declarations> tag.
Metadata: Add additional information to classes, properties, or methods to use at runtime inside the <fx:Metadata>...</fx:Metadata> tag. Learn more.
Styles: Declare the styles the app uses in the <fx:Styles>...</fx:Styles> tag.
Functions, property definitions, and other features: Declare properties, instantiate components, and write functions inside the <fx:Script>...</fx:Script> tag. In the component example above, we declare an event handler, a function that does things when you click one of the buttons in the user interface.
Beads: Royale components generally follow the PAYG principle of starting out with just enough functionality to do the basic things you would expect of them. If you want a component to do more, you add a bead with extra functions to it, as if the component were a thread. This way, only the components that need a lot of code have it, and this keeps down the size of the application.
User interface: