Changing the filenames in Flex Builder html templates

Suppose you want the main HTML file that wraps your Flash app to be deployed as index.aspx instead of index.html. It’s a little trickier than you might think.

If you look in the html-template directory of your project, you will see that the main file is called index.template.html. This is a special name – Flex Builder recognizes filenameit, and says “Oh I know what that is,” and uses it to create MyApp.html and MyApp-debug.html in the bin folder.

But if you just rename it to index.template.aspx, you’ll have problems. Notice that after doing that, and then cleaning your project, you now have only index.aspx in the bin folder. There are two issues with that: For one thing, the app name isn’t part of the , which cause trouble if you have more than one app in the project; and also, it doesn’t differentiate between the debug and release versions of the file. If you examine it, you’ll see that it contains a reference to MyApp-debug.swf. Where did the release one go?

The answer is that since the file no longer has the special index.template.html name, Flex Builder doesn’t know what to do with it. It does see the “.template” part of the name, and it uses that to decide that it should do macro-substutition within the file; but beyond that, it does nothing more.

And since there are two SWFs (release and debug), Flex Builder ends up processing your file twice. First, it creates the release version of index.aspx, then it creates the debug version of the same file, overwriting the release version. (It probably should report an error in this case, but it doesn’t.)

But the solution, it turns out, is very easy (although not at all obvious): Give the file the rather cryptic name of…

${application}${build_suffix}.template.aspx

That does the trick. The ${application} and ${build_suffix} macros are substituted when creating the filename that goes into the bin directory (build_suffix is “” for the release build and “-debug” for the debug build); and “.template” causes Flex Builder to do macro substitution inside the file.

To wrap up:

• Any file in the html-template directory can have macros in the filename. Substitution will be performed when using those template files to the create the files in the bin directory.
• In addition, if any filename contains .template (either at the very end, or followed by a punctuation character such as “.”), then the contents of that file will have macro substitution performed, and the .template part will be removed from the filename when copying to the bin directory.
• Finally, the name index.template.html is a special case, and is essentially equivalent to ${application}${build_suffix}.template.html.

So, what macros are available? ${project}, ${application}, ${version_major}, ${version_minor}, ${version_revision}, ${build_suffix}, ${swf}, ${bgcolor}, ${width}, ${height}, ${title}.