Project Templates
From FDT Documentation
While project templates were introduced in FDT 4.0, the FDT team has gathered feedback from developers and adjusted them to be more powerful. Now, FDT developers can create sophisticated project setups that can be customized just before generation.
Contents |
How Templates Worked in FDT 4.0 & 4.1
When project templates were introduced in FDT 4, FDT simply copied the contents of the project folder into your new project.
After that, it applied properties to these files and folder to integrate them into your build path.
In the above image we can see where we preset our source folders, SWCs and output folders.
Project Templates in FDT 4.2
In 4.2, project templates were greatly expanded to allow developers to consolidate their templates by introducing concepts such as:
- Create a custom GUI per template to adjust the project setup.
- Variables that can placed into any text file and edited via a GUI, then replaced after the template is generated.
- Expressions, such as conditionals and concatenation, that allow more flexibility.
- The ability to predefine source code libraries that are located outside the workspace (linked resources).
- An Ant script that can be executed upon project creation.
A simple example of template consolidation is how the default templates now include a checkbox for unit testing, as opposed to creating two separate templates - one with unit testing and one without.
Introduction - The Setup
Where They Are Located
FDT's project templates are located in a folder on your system. On OSX the path is:
(Your User Name) > Library > Application Support > FDT
Inside the FDT Folder
projectTemplateBackup
This folder is where templates that were created before version 4.2 will be moved to when FDT is upgraded from FDT 4.1 to 4.2
projectTemplates
This folder holds your project templates. When a folder is placed in here, it will appear in your new project wizard. FDT ships with 2 folders, Desktop and Web; however, you can create as many as you like.
In the above example the folder 'Another Group' was created and then appears in the New Project Wizard.
Other files & folders:
- Desktop - Default folder for templates associated with AIR.
- Web - Default folder for templates associated with standard Flash deployment.
- order.xml - The order which the templates are shown within the New Flash Project wizard.
- sdks.xml - A file that holds any custom SDK setups that both ship with FDT and created by users.
- haxeExtension.xsd - An XML schema for haxe templates.
- projectTemplate.xsd - An XML schema for project templates.
projectTypes
This folder contains XML files that determine a type for a project. Each type allows you to preset properties such as compatible SDKs, selected .SWCs of an SDK and compiler arguments. You can create your own project types.
Inside the Project Folder
A project template has three parts:
- A project folder - this is where you place files that can be processed (if they have variables in them) and / or included upon project creation.
- description.xml - this is where you define how your template is setup, processed and the UI for it.
- icon.gif - An icon to help identify the template.
Simple Project Template Tutorial
Follow this walkthrough to create a new template, based on a copy from an existing one, and add a combobox that will allow you to set the base class for your Main class.
Step One
Within the Web folder, make a copy of the AS3 template and rename it to MyTemplate.
Step Two
Open description.xml and change the name to the name of your template - in this case from AS3 to MyTemplate
Step Three
Within the Project Setup element, add this code:
<variable name="extends" label="Main Class Extends:" default="Sprite" type="enum('Sprite','MovieClip')" />
Within the Project Setup group:
The above code will:
- Create a variable named '${extends}'
- Within the New Project Wizard UI, give it a label of 'Main Class Extends:'
- Set the Default value to Sprite
- Create a combobox with the values Sprite and MovieClip
The UI will now look like this:
Step Four
Now we need to make sure the variable is processed correctly and is placed into our ActionScript file. Locate the contentCreation element in your description.xml and make sure that our Main.as is targeted and process is set to true.
In this case the file is already being processed, but it's good to double check.
Next, open the Main.as in the project > as folder:
and add the variable ${extends} to Main.as
Now when the project is created, it will replace ${extends} in your ActionScript file with whatever the value of extends.
Advanced Template Tutorial
The Simple Project Template Tutorial showed how easily it is to add variables to your template and have those variables change your ActionScript code. In this next example, we'll show how you can use some of the advanced concepts to provide even more sophisticated template setups. We'll create an option to add metadata 'themes' to your ActionScript class and an option to include a .fla.
Step One
Make a duplicate of the AS3 template and rename it to Metadata AS3 like in steps one and two in the Simple Project Template Tutorial.
Step Two
Create the UI for a checkbox and a combobox.
<group label="Metadata"> <variable name="addMetaData" label="Add Metadata" default="true" type="boolean" /> <variable name="metaTheme" label="Size" default="Leaderboard" type="enum('Leaderboard','Full Banner','Half Banner','Full Site')" /> </group>
Step Three
Create the expressions, within the expressions element, to help generate the metadata tag depending on what values we choose via the UI - whether to add metadata or not and the metadata theme. There are a few expressions to make:
- Three maps (hash tables / hash maps) to hold values which will change depending on the theme we choose.
- One expression that will concatenate our values together to create the metadata string
- One expression that will set the metadata string as blank if the users turns off metadata
- A description expression that will update the description text box within the New Project Wizard UI
Maps:
<map name="bannerWidth" > <entry key="Leaderboard" value="'728'"/> <entry key="Full Banner" value="'468'"/> <entry key="Half Banner" value="'234'"/> <entry key="Full Site" value="'800'"/> </map> <map name="bannerHeight" > <entry key="Leaderboard" value="'90'"/> <entry key="Full Banner" value="'60'"/> <entry key="Half Banner" value="'60'"/> <entry key="Full Site" value="'600'"/> </map> <map name="bannerFPS" > <entry key="Leaderboard" value="'22'"/> <entry key="Full Banner" value="'22'"/> <entry key="Half Banner" value="'22'"/> <entry key="Full Site" value="'60'"/> </map>
Metadata concatenation:
<expression name="metaDataExp" value="concat('[SWF(backgroundColor="',0xFFFFFF,'", frameRate="',bannerFPS(${metaTheme}),'", width="', bannerWidth(${metaTheme}),'", height="', bannerHeight(${metaTheme}),'")]')" />
Setting the metadata variable to blank if the users disables metadata:
<expression name="metaData" value="if(${addMetaData},${metaDataExp},'')" />
An expression that will update the description UI:
<expression name="metaDataDesc" value="if(${addMetaData},(concat('Metadata: ',${metaDataExp})),'')"/>
Step Four
Then we'll add the description variable to the description element:
<description>This template will create a project named '${projectName}' which contains only the basic libraries to develop and compile a pure AS3 project.${newline}${htmlDesc}${newline}${metaDataDesc}</description>
Step Five
To make sure this works, double check that the target file is listed within the contentCreation element:
Now edit the ActionScript file to add the metadata variable ${metaDataExp}
Step Six
The last part will be to add the options for a .fla. Add a UI button for an option for a .fla. Let's put it in our Project Setup group.
<variable name="addFla" label="Add .fla" default="true" type="boolean" />
Step Seven
Last, we'll add some logic to the contentCreation element that will determine to include the .fla in our project:
and then add the .fla to our project folder