Skip to content

2. Understanding the Glory “config.xml” File

Jump to bottom Edit New page
Allan Dowdeswell edited this page Dec 15, 2023 · 18 revisions

Apart from the project.xml file which is common to OpenFL, Glory Framework is configured using the config.xml file found in /assets. The best way to understand this file is to inspect the code provided in the /examples folder. You can add/remove/modify pages and assets simply by editing the config.xml file. If you have compiled and deployed to web and are not using app mode or custom page classes there is no recompile required — just reload the page to view your changes!

A basic config file only requires the following structure:

<?xml version="1.0" encoding="UTF-8"?>  
<pages basePath="/" homepageId="home" title="Glory Framework Website Demo">
	<controls></controls>  
	<page id="home" type="normal" title="The Home Page">
		<actor id="haxeLogo" type="control" action="httpLink:haxe.org/" z="20" x="0" y="100" width="200" height="200" src="title/haxe-opt.svg"></actor> 
	</page>  
</pages>

IMPORTANT: There must be one page with an id attribute that matches the "homepageId" attribute on the <pages> element. This serves as the “home” page of the framework and will display in the url when not in app mode. If no homepageId attribute is found it will default to “title”.

Base Path

If you’re making a website, be sure to use set the base path in two places or you will experience much sorrow. In the config.xml file there is a basePath attribute on the <pages> element (see above). There is also a line in "htaccess.txt" which must match the same path: RewriteBase / This will get deployed to your /html5/bin directory as ".htaccess" so that the server handles the file paths and deep linking properly with the PHP file. So if you are installing your Glory application in a subfolder on a server, make both of those paths correspond to that path, e.g.: RewriteBase /demo/glorysite/

Custom Config Path

You may want to use a file other than "config.xml" for config, for example if you have multiple Glory applications in the same directory, or if you want to generate xml from a database or script. Simply edit your project.xml file to include the following haxe define: <define name="configpath" value="assets/someOtherConfigFile.xml" /> There is an example of this in the /examples/website demo.

Trackers

In the interest of providing a good groundwork for OpenFL-based websites, Glory has support for data collection via trackers. Currently the Google Analytics V3 tracker is supported.

<tracker type="google" id="UA-XXXXXXXXX-1" version="3" user="" domain="confidant.ca">
	<!-- version 3 is universal analytics, version 4 is GA4 -->
</tracker>

IMPORTANT: Enabling trackers requires a corresponding flag to be set in the project.xml file so that the proper supporting library can be loaded: <define name="enableGoogleTrackerV3" /> <define name="enableGoogleTrackerV4" />

Controls

Of course, you will want to have some controls to control your application. Here’s an example:

<actor id="bOptions" type="control" action="pageSkipTo:options" z="18" x="849" y="-11" width="111" height="71" src="nav/bOptions.png"></actor>

Simply place actor tags within the <controls></controls> tags and configure them as desired. They will persist on screen unaffected by page changes. See the actors section below for configuration options.

Currently there are these built-in actions available for buttons and actors with type of “control”:

  • pageSkipTo
  • pageForward
  • pageBackward
  • removePage
  • playSound
  • httpLink

When you use pageSkipTo, follow it with a colon and the id of the page you want to visit when the button is pressed. The example above summons the “options” page.

Since version 2.0.3, Glory has added custom notification actions. This is a powerful new feature which lets you trigger any PureMVC custom notifications you want to add to your application. To use these you must format your action in JSON notation like so:

<actor id="bRight" type="control" action='{"doNavigation":{"destination":"pageForward"}}' width="50" height="50" src="nav/right-icon.svg" layout="alignRight:5,alignBottom:5"></actor>

In the example above, a notification named 'doNavigation' will be dispatched using PureMVC’s facade.sendNotification function. The '{"destination":"pageForward"}' object will be sent along with the notification to provide instructions to whatever functions are listening for that notification. It is recommended to read the “Implementation Idioms and Best Practices” document for PureMVC to fully understand how to use this feature.

Pages

Pages are holders for actors, which are the graphics, etc. displayed on screen. Each page should have a unique id, and there are currently two valid values for the type attribute:

  • normal
  • overlay

Normal pages will obey the pageForward and pageBackward navigation and are included in the normal page ordering. Alternatively, overlay pages are intended for modal-style dialogs, and once they are dismissed the application returns you to the page you were on when you left.

When you define an overlay page, be sure to include an actor of type “control” which is able to dismiss the overlay. See this example:

<page id="options" type="overlay" original="" width="960" height="640">
	<actor id="background" type="prop" z="0" x="0" y="0" width="960" height="640" src="options/actor_0000_background.png"></actor>
	<actor id="limerick" type="control" action="pageSkipTo:limerickPage,removePage:options" z="5" x="135" y="366" width="198" height="185" src="options/actor_0005_limerick.png"></actor>
	<actor id="close" z="6" type="control" action="removePage:options" x="860" y="40" width="50" height="50" src="nav/close.png" ></actor>
</page>

Note in the above example that it is possible and necessary to provide two actions to actors which trigger a page change. The “removePage:yourPageId” action is necessary to dismiss the overlay page which is currently displaying – just separate that command from the other commands using a comma.

Actors

It is good practise to give each actor in your application a unique id, even if actors are in separate pages. Otherwise you will likely experience errors due to duplicate view mediators.

You may have noticed that the actor tags have two valid type attributes:

  • prop
  • control

If the actor is not intended to be clickable, use the “prop” value to save memory. Currently actors are added in the order which they appear in the config.xml file. The z attribute is currently useless but may be used in the future.

Actors may be .png,.jpg,.gif,.svg, .txt, .html or even MovieClip assets from a .swf library. All actors may be referenced using a file path in the "src" attribute. The exception to this rule is MovieClip assets – these must be placed within a page that has a swflibrary attribute and contains only MovieClip assets. These page and actor nodes have special syntax; please refer to SWF to Glory Workflow for more information.

For more information about using text actors, see Using Fonts and Text Actors.

Sounds

Use a sound tag within a page to make a sound available for playback:

<sound id="s_limerickPage" src="p1/limerickPCM.mp3,p1/limerickPCM.ogg,p1/limerickPCM.wav" autoPlay="false" ></sound>

Enter multiple file paths separated by commas, and OpenFL will choose the appropriate file for your platform. These paths will only be used when not in “app mode”. The “app mode” sounds still require an id attribute which will point to assets which were configured in your project.xml. Please refer to the project.xml documentation.

Sound settings currently feature an autoPlay attribute. Future releases may feature a loop attribute.

Page Transitions

Each page has "transitionIn" and "transitionOut" functions. They default to simple 1-second fades, but these can be overridden by using the custom page class feature. By editing the "transitionOutTime" attribute on the page tag in the config.xml file, you have some control over whether the transitionIn overlaps with the transitionOut. See the provided config.xml file and custom page class file in the /examples folder to see this.

Layout Behaviours

If your project is set to have a dynamic stage size such as shown in the website example, you will want to have your actors adjust their position and/or size appropriately. Glory uses the Advanced Layout library under the hood to help you with this. Syntax for adding layout behaviour is as follows:

<actor id="haxeLogo" type="control" action="httpLink:haxe.org/" z="20" x="0" y="100" width="200" height="200" src="title/haxe-opt.svg" layout="fillPercentWidth:0.5,maintainAspectRatio,centerX,centerY"></actor>

Note the commands contained in the layout attribute. Glory supports a subset of the options contained within the LayoutCreator class of Advanced Layout library. Simply separate the functions you want by commas, and use a colon to pass a single parameter to the function. They will be executed in order of appearance. Remember to set the position after setting the scale. Read the Advanced Layout documentation for more help. Supported commands as follows:

  • simpleX
  • simpleY
  • centerX
  • centerY
  • center
  • alignLeft
  • alignRight
  • alignTop
  • alignBottom
  • alignTopLeft
  • alignTopRight
  • alignBottomLeft
  • alignBottomRight
  • alignLeftCenter
  • alignRightCenter
  • alignTopCenter
  • alignBottomCenter
  • horizontalPercent
  • verticalPercent
  • simpleScale
  • simpleWidth
  • simpleHeight
  • rigidSimpleScale
  • rigidSimpleWidth
  • rigidSimpleHeight
  • fillWidth
  • fillHeight
  • fillPercentWidth
  • fillPercentHeight
  • rigidFillPercentWidth
  • rigidFillPercentHeight
  • maintainAspectRatio

For situations where you need layouts to be even more responsive, Glory plays nice with other OpenFL UI frameworks. Simply create a custom page class and add whatever you need. For example the ResponsiveGridLayout from FeathersUI works particularly well with Glory.

Add a custom footer
Add a custom sidebar
Clone this wiki locally