tutorials/www/stock-tracker.ui.xml - pivot - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to you under the Apache License,
 Version 2.0 (the "License"); you may not use this file except in
 compliance with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 -->

 <document id="stock-tracker.ui">
     <properties>
         <title>UI Markup Using BXML</title>
     </properties>

     <body>
         <p>
             The user interface of a Pivot application is often defined using an XML markup language
             called BXML ("Bean XML"). BXML is effectively a shorthand for instantiating and
             configuring Java class instances. Though it can be used to declaratively construct any
             type of Java object hierarchy, it is most often used to define the structure of an
             application's user interface - the hierarchical structure of an XML document closely
             parallels the structure of the application's component hierarchy, which makes it easy
             to visualize the resulting output.
         </p>

         <p>
             In general, XML elements in BXML refer either to class instances or properties of class
             instances. Any element that begins with a capital letter represents a class instance,
             and elements beginning with lowercase letters represent properties. The exception is
             elements that use the "bxml" namespace prefix, which represent processing directives to
             the BXML serializer. Similarly, XML attributes generally represent properties, with the
             exception of attributes that begin with a "bxml" prefix, which contain processing
             information used by the serializer.
         </p>

         <h3>StockTrackerWindow</h3>

         <p>
             The following is a snippet of code taken from <tt>stock_tracker_window.bxml</tt>,
             the BXML file that defines the main window of the Stock Tracker application:
         </p>

         <source type="xml">
             <![CDATA[
             <stocktracker:StockTrackerWindow title="%stockTracker" maximized="true"
                 xmlns:bxml="http://pivot.apache.org/bxml"
                 xmlns:content="org.apache.pivot.wtk.content"
                 xmlns:stocktracker="org.apache.pivot.tutorials.stocktracker"
                 xmlns="org.apache.pivot.wtk">
                 <TablePane styles="{padding:8, horizontalSpacing:6, verticalSpacing:6}">
                     <columns>
                         <TablePane.Column width="1*" />
                     </columns>

                     <TablePane.Row height="-1">
                         <Label text="%stockTracker"
                             styles="{font:{size:14, bold:true}, verticalAlignment:'center'}" />
                     </TablePane.Row>

                     <TablePane.Row height="1*">
                         <SplitPane splitRatio="0.4">
                             <left>
                                 ...
                             </left>

                             <right>
                                 <Border styles="{padding:6, color:10}">
                                     <bxml:include bxml:id="detailPane" src="detail_pane.bxml"/>
                                 </Border>
                             </right>
                         </SplitPane>
                     </TablePane.Row>

                     <TablePane.Row height="-1">
                         <BoxPane styles="{horizontalAlignment:'left', verticalAlignment:'center'}">
                             <Label text="%symbol" styles="{font:{bold:true}}" />
                             <TextInput bxml:id="symbolTextInput" textSize="10"
                                 maximumLength="8" />
                                 ...
                 </TablePane>
             </stocktracker:StockTrackerWindow>
             ]]>
         </source>

         <p>
             The root node of <tt>stock_tracker_window.bxml</tt> is a
             <tt>stocktracker:StockTrackerWindow</tt> element. This element corresponds to an
             instance of <tt>org.apache.pivot.tutorials.stocktracker.StockTrackerWindow</tt>. In
             BXML, XML namespaces are used to associate a class element with a Java package. In this
             case, "stocktracker" is mapped to <tt>org.apache.pivot.tutorials.stocktracker</tt>, and
             "content" is mapped to <tt>org.apache.pivot.wtk.content</tt>; the default namespace is
             mapped to <tt>org.apache.pivot.wtk</tt>, the Java package that contains most of Pivot's
             common components. The file also declares the "bxml", which is specific to the
             serializer.
         </p>

         <p>
             <tt>StockTrackerWindow</tt> is an application-specific class that extends the base
             <tt>org.apache.pivot.wtk.Window</tt> class. Windows are the primary entry point into a
             Pivot user interface. Windows are always direct descendants of the "display" (an
             instance of <tt>org.apache.pivot.wtk.Display</tt> that is created by the platform). An
             application can open any number of windows on the display, though many applications
             will use a single primary window and a number of secondary windows (for example,
             dialogs, sheets, menu popups, or tooltips).
         </p>

         <h3>The Bindable Interface</h3>
         <p>
             <tt>StockTrackerWindow</tt> implements the <tt>org.apache.pivot.beans.Bindable</tt>
             interface. This interface allows developers to easily map elements declared with a
             <tt>bxml:id</tt> attribute to Java member variables. For example,
             <tt>StockTrackerWindow</tt> declares the following member variables:
         </p>

         <source type="xml">
             <![CDATA[
             @BXML private TableView stocksTableView = null;
             @BXML private TextInput symbolTextInput = null;
             @BXML private Button addSymbolButton = null;
             @BXML private Button removeSymbolsButton = null;
             @BXML private BoxPane detailPane = null;
             @BXML private Label lastUpdateLabel = null;
             @BXML private Button yahooFinanceButton = null;
             ]]>
         </source>

         <p>
             Because <tt>StockTrackerWindow</tt> implements <tt>Bindable</tt>, these member variables
             are automatically populated with the corresponding values declared in the BXML file.
             For example, the object with ID "stocksTableView" in the BXML file will be assigned to
             the <tt>stocksTableView</tt> member variable, and so on.
         </p>

         <p>
             <tt>Bindable</tt> defines a single method, <tt>initialize()</tt>, that is called when
             the root element has been fully loaded and the bound values have been processed. This
             allows the bound class to perform any required initialization (generally event
             registration, discussed in more detail in the
             <a href="stock-tracker.events.html">Event Handling</a> section).
         </p>

         <h3>Attribute Resolution and Includes</h3>

         <p>
             The BXML snippet above also illustrates a couple other important aspects of BXML markup:
             resource resolution and includes. Resource resolution allows a developer to insert
             "tags" in the markup that will be replaced at load time with a localized equivalent.
             This makes it very easy to build internationalized applications in Pivot. Any attribute
             value that begins with a "%" character is considered a resource key, and the value
             for the attribute is obtained from a resource bundle associated with the BXML file.
             This is discussed in more detail in the
             <a href="stock-tracker.localization.html">Localization</a> section.
         </p>

         <p>
             BXML also supports two other attribute resolution operators: "@" and "$". The "at" symbol
             is used to resolve URLs; any attribute value preceded by an "at" symbol is converted to an
             instance of <tt>java.net.URL</tt> relative to the current BXML file. This notation is
             very useful for loading images from a location relative to the current file.
         </p>

         <p>
             The dollar sign is a "variable dereference" operator. Though it isn't shown in this
             example, it is possible to embed script code in a BXML file using the
             <tt>&lt;bxml:script&gt;</tt> tag. Any JVM-capable scripting language is supported,
             including JavaScript, Groovy, and Clojure, among others. Any attribute value preceded by
             a dollar sign is resolved to an instance of a script variable declared within the page.
             This allows developers to define variables in script and then easily use them as
             initialization parameters for class instances declared as elements. Script code can
             also refer to any page elements identified via a <tt>bxml:id</tt> attribute as globally
             scoped page level variables.
         </p>

         <p>
             Includes allow a developer to embed content defined in an external BXML file as if it
             was defined in the source file itself. This is useful for partitioning content into
             manageable pieces (for example, when working on large applications or with multiple
             developers, or when defining reusable content templates). The detail pane in the
             Stock Tracker application is defined in an include, <tt>detail_pane.bxml</tt>. This file
             is included into the main window via the <tt>&lt;bxml:include&gt;</tt> tag.
         </p>
     </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to you under the Apache License,
	Version 2.0 (the "License"); you may not use this file except in
	compliance with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<document id="stock-tracker.ui">
	<properties>
	<title>UI Markup Using BXML</title>
	</properties>

	<body>
	<p>
	The user interface of a Pivot application is often defined using an XML markup language
	called BXML ("Bean XML"). BXML is effectively a shorthand for instantiating and
	configuring Java class instances. Though it can be used to declaratively construct any
	type of Java object hierarchy, it is most often used to define the structure of an
	application's user interface - the hierarchical structure of an XML document closely
	parallels the structure of the application's component hierarchy, which makes it easy
	to visualize the resulting output.
	</p>

	<p>
	In general, XML elements in BXML refer either to class instances or properties of class
	instances. Any element that begins with a capital letter represents a class instance,
	and elements beginning with lowercase letters represent properties. The exception is
	elements that use the "bxml" namespace prefix, which represent processing directives to
	the BXML serializer. Similarly, XML attributes generally represent properties, with the
	exception of attributes that begin with a "bxml" prefix, which contain processing
	information used by the serializer.
	</p>

	<h3>StockTrackerWindow</h3>

	<p>
	The following is a snippet of code taken from <tt>stock_tracker_window.bxml</tt>,
	the BXML file that defines the main window of the Stock Tracker application:
	</p>

	<source type="xml">
	<![CDATA[
	<stocktracker:StockTrackerWindow title="%stockTracker" maximized="true"
	xmlns:bxml="http://pivot.apache.org/bxml"
	xmlns:content="org.apache.pivot.wtk.content"
	xmlns:stocktracker="org.apache.pivot.tutorials.stocktracker"
	xmlns="org.apache.pivot.wtk">
	<TablePane styles="{padding:8, horizontalSpacing:6, verticalSpacing:6}">
	<columns>
	<TablePane.Column width="1*" />
	</columns>

	<TablePane.Row height="-1">
	<Label text="%stockTracker"
	styles="{font:{size:14, bold:true}, verticalAlignment:'center'}" />
	</TablePane.Row>

	<TablePane.Row height="1*">
	<SplitPane splitRatio="0.4">
	<left>
	...
	</left>

	<right>
	<Border styles="{padding:6, color:10}">
	<bxml:include bxml:id="detailPane" src="detail_pane.bxml"/>
	</Border>
	</right>
	</SplitPane>
	</TablePane.Row>

	<TablePane.Row height="-1">
	<BoxPane styles="{horizontalAlignment:'left', verticalAlignment:'center'}">
	<Label text="%symbol" styles="{font:{bold:true}}" />
	<TextInput bxml:id="symbolTextInput" textSize="10"
	maximumLength="8" />
	...
	</TablePane>
	</stocktracker:StockTrackerWindow>
	]]>
	</source>

	<p>
	The root node of <tt>stock_tracker_window.bxml</tt> is a
	<tt>stocktracker:StockTrackerWindow</tt> element. This element corresponds to an
	instance of <tt>org.apache.pivot.tutorials.stocktracker.StockTrackerWindow</tt>. In
	BXML, XML namespaces are used to associate a class element with a Java package. In this
	case, "stocktracker" is mapped to <tt>org.apache.pivot.tutorials.stocktracker</tt>, and
	"content" is mapped to <tt>org.apache.pivot.wtk.content</tt>; the default namespace is
	mapped to <tt>org.apache.pivot.wtk</tt>, the Java package that contains most of Pivot's
	common components. The file also declares the "bxml", which is specific to the
	serializer.
	</p>

	<p>
	<tt>StockTrackerWindow</tt> is an application-specific class that extends the base
	<tt>org.apache.pivot.wtk.Window</tt> class. Windows are the primary entry point into a
	Pivot user interface. Windows are always direct descendants of the "display" (an
	instance of <tt>org.apache.pivot.wtk.Display</tt> that is created by the platform). An
	application can open any number of windows on the display, though many applications
	will use a single primary window and a number of secondary windows (for example,
	dialogs, sheets, menu popups, or tooltips).
	</p>

	<h3>The Bindable Interface</h3>
	<p>
	<tt>StockTrackerWindow</tt> implements the <tt>org.apache.pivot.beans.Bindable</tt>
	interface. This interface allows developers to easily map elements declared with a
	<tt>bxml:id</tt> attribute to Java member variables. For example,
	<tt>StockTrackerWindow</tt> declares the following member variables:
	</p>

	<source type="xml">
	<![CDATA[
	@BXML private TableView stocksTableView = null;
	@BXML private TextInput symbolTextInput = null;
	@BXML private Button addSymbolButton = null;
	@BXML private Button removeSymbolsButton = null;
	@BXML private BoxPane detailPane = null;
	@BXML private Label lastUpdateLabel = null;
	@BXML private Button yahooFinanceButton = null;
	]]>
	</source>

	<p>
	Because <tt>StockTrackerWindow</tt> implements <tt>Bindable</tt>, these member variables
	are automatically populated with the corresponding values declared in the BXML file.
	For example, the object with ID "stocksTableView" in the BXML file will be assigned to
	the <tt>stocksTableView</tt> member variable, and so on.
	</p>

	<p>
	<tt>Bindable</tt> defines a single method, <tt>initialize()</tt>, that is called when
	the root element has been fully loaded and the bound values have been processed. This
	allows the bound class to perform any required initialization (generally event
	registration, discussed in more detail in the
	<a href="stock-tracker.events.html">Event Handling</a> section).
	</p>

	<h3>Attribute Resolution and Includes</h3>

	<p>
	The BXML snippet above also illustrates a couple other important aspects of BXML markup:
	resource resolution and includes. Resource resolution allows a developer to insert
	"tags" in the markup that will be replaced at load time with a localized equivalent.
	This makes it very easy to build internationalized applications in Pivot. Any attribute
	value that begins with a "%" character is considered a resource key, and the value
	for the attribute is obtained from a resource bundle associated with the BXML file.
	This is discussed in more detail in the
	<a href="stock-tracker.localization.html">Localization</a> section.
	</p>

	<p>
	BXML also supports two other attribute resolution operators: "@" and "$". The "at" symbol
	is used to resolve URLs; any attribute value preceded by an "at" symbol is converted to an
	instance of <tt>java.net.URL</tt> relative to the current BXML file. This notation is
	very useful for loading images from a location relative to the current file.
	</p>

	<p>
	The dollar sign is a "variable dereference" operator. Though it isn't shown in this
	example, it is possible to embed script code in a BXML file using the
	<tt><bxml:script></tt> tag. Any JVM-capable scripting language is supported,
	including JavaScript, Groovy, and Clojure, among others. Any attribute value preceded by
	a dollar sign is resolved to an instance of a script variable declared within the page.
	This allows developers to define variables in script and then easily use them as
	initialization parameters for class instances declared as elements. Script code can
	also refer to any page elements identified via a <tt>bxml:id</tt> attribute as globally
	scoped page level variables.
	</p>

	<p>
	Includes allow a developer to embed content defined in an external BXML file as if it
	was defined in the source file itself. This is useful for partitioning content into
	manageable pieces (for example, when working on large applications or with multiple
	developers, or when defining reusable content templates). The detail pane in the
	Stock Tracker application is defined in an include, <tt>detail_pane.bxml</tt>. This file
	is included into the main window via the <tt><bxml:include></tt> tag.
	</p>
	</body>
	</document>