Templates
Templates defined the applications top-level frame and navigation.
An application’s template is chosen on the first page of the Application Manifest Editor.
Potomac ships with one template called potomac_dark provided by the potomac_ui_templates_dark bundle.
There will be more templates made available in the future (including, hopefully, third party templates).
Creating Templates
A template is simply an extension of the Template extension point. Create a UI component and add the [Template] tag at the top. A template is responsible for providing the entire frame and navigation structure for an application. It will be added as a child to the top level Flex application object.
A template’s primary responsibility is managing and display pages. There are no requirements as to how the template chooses to display pages. Some templates may represent pages as tabs in a tab navigator (such as the default potomac_dark template), some templates may choose to only have one template visible at one time and use a ViewStack, perhaps a template might choose to display pages in an Accordion. Advanced templates will likely use advanced effects and animations between page transitions. Ultimately, what a template can do is only limited by the imagination of the template author.
The communication between a template and Potomac is handled via events. Writing a template requires writing event handlers for the following template events.
| TemplateEvents | |
|---|---|
| templateInitialize | The template initialize event is dispatched to allow the template to load its properties and actions (both discussed below). |
| templateOpenPage | Dispatched when a page’s UI selector (for example, its tab) should be created. The template event contains all the necessary detailed properties about the page being opened. Importantly, opening page does not necessarily mean that the page’s UI components should be created. Pages should only be created (i.e. calling the Page#create() method) when they’re shown to the user. This delays the necessary bundle loading until absolutely required. If the setFocus property of the event is true, then the page should be both opened and created (and shown to the user). |
| templateShowPage | Dispatched when code has programmatically requested to change the currently visible page. Templates should change the visible page (ex. change the selected tab in a tab navigator). |
| templateClosePage | Dispatched when code has programmatically closed a page. Templates should remove the associated UI (ex. remove the tab from the tab navigator). |
| templatePageDirtyChange | Dispatched when the dirty state of one or more parts within a page has changed. This gives templates the opportunity to annotate the page UI with an “*” to identify pages with unsaved work. |
Template Parameters
An important feature of templates is the configurable parameters support. Since templates are intended to be reused by multiple applications, its necessary to allow different applications to change parameters of the selected template. Template parameters are declared in the [Template] tag through the ‘properties’ attribute. The properties are then made available within the appManifest editor. Finally, the configured parameters themselves are passed into the templateInitialize event.
Template properties are declared in the [Template] tag as a comma separated string. The potential datatypes for the properties are ’string’, ‘image’, and ‘boolean’. For example:
[Template(id="myTemplate",properties="logo:image,title:string,showMenu:boolean")]
Template properties cannot be marked as required, therefore template authors should be prepared that any or all of their properties were not entered.
The properties will be encoded into the TemplateEvent#parameters object as dynamic properties. Strings will be strings, booleans as Booleans, and images as embedded images of type Class.
Actions
Another important responsibility of templates, is to display Actions. Actions are declared by bundles via the [Action] tag. Its up to the template to determine how the actions are surfaced to the user. The default potomac_dark template displays actions via a LinkBar but a template may use any UI it deems necessary.
Templates should retrieve the list of declared actions by calling IBundleService#getExtensions(”Action”). The resulting array can be used as a data provider if so desired. Only when a user triggers an action (i.e. clicks on its button) should an instance of the action be created via Injector#getInstanceOfExtension().
Sample Code
If you’re creating your own template, please use the existing potomac_dark template as a guide. You can access to source code to Potomac on github:
Source for potomac_dark class DarkTemplate.mxml