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
bindirectory. - 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.templatepart will be removed from the filename when copying to thebindirectory. - Finally, the name
index.template.htmlis 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}.
23 Responses to “Changing the filenames in Flex Builder html templates”
December 11th, 2006 at 1:03 pm
Great information, and extremely useful. Do you have any more info on the macro keywords and their use. I may be dense but I’ve had a terrible time trying to sort out where the ${bgcolor} info that is placed in the HTML file comes from.
December 11th, 2006 at 1:39 pm
${bgcolor} comes from the “backgroundColor” attribute of the <mx:Application> tag. or, if it is a pure-ActionScript project, from the [SWF] attribute immediately before the main application class, e.g.
[SWF(backgroundColor=”#ff0000″)]
public class MyApp extends Sprite.
December 11th, 2006 at 7:51 pm
Hi Mike, great post. I was actually wondering about this topic just the other day. How do we set the ${version_major}, ${version_minor}, and ${version_revision} values?
Thanks.
December 11th, 2006 at 9:20 pm
You set the ${version_…} values by going to the Flex Compiler or ActionScript Compiler tab of the Project Properties dialog.
December 12th, 2006 at 8:24 am
A bit off topic, but your post reminded me that I was wondering if there were a way to do the wrapper page processing from the command line instead of from within Flex Builder. I needed this recently when writing a daily build script for our app. One of the things I had to do to get it to work was check in the generated wrapper page, because I didn’t know of any way to build it from the command line.
December 12th, 2006 at 8:32 am
Sorry David, I don’t know of a way to do that. But check if this might help — it appears to show how to make an Ant script tell Eclipse to do its normal Eclipse-style build. If that works for you, then great. Note that that would do the whole build, not just the HTML-template part.
January 22nd, 2007 at 8:42 am
Where does the {$title} value get set?
January 22nd, 2007 at 10:08 am
${title} gets set to the value of the "pageTitle" attribute of the <mx:Application> tag — or, if that is not set, then to the filename of the main application file (minus the ".mxml" part).
January 24th, 2007 at 9:44 am
Thanks Mike. Worked like a charm. May I suggest you make a blog entry _just_ on these tokens? Would be useful.
January 24th, 2007 at 10:10 am
Good idea Raymond.
January 24th, 2007 at 10:51 am
[…] In a post last month, I briefly mentioned the list of macro substitutions that are available in the files in the html-template folder. Here, I’ll offer a little more information on those. I’ll try to make sure this makes it into the next version of the documentation. […]
January 24th, 2007 at 12:42 pm
In response to Dave Coletta’s question: There is now an html-wrapper custom Ant task that will generate wrappers and supporting files. It’s available on labs:
http://labs.adobe.com/wiki/index.php/Flex_Ant_Tasks
hth,
matt horn
flex docs
January 24th, 2007 at 12:48 pm
Whoa, cool, I didn’t know about that. Thanks for the link, Matt!
January 24th, 2007 at 1:36 pm
[…] As I recently blogged, one of my goals for the year is to learn how to use Ant with Flex. I had asked a question on Mike Morearty’s blog some time back about how to build the index.html wrapper page for a Flex application from the command line, since I was working on a nightly build script. He just pinged me to let me know that there’s an Ant task to do that. Cool! And there’s also a wiki page at Adobe Labs that documents how to use Ant with Flex. Extra cool! Now if I can just find some time to read it… […]
February 7th, 2007 at 2:59 pm
Mike, your method works great.
however, after i change index.template.html to ${application}${build_suffix}.template.cfm (i am using coldfusion), Flex Builder still launches index.html file in brower, which gets me 404 error. any way to make it launch index.cfm? thanks
February 7th, 2007 at 5:49 pm
hua,
You need to change the URL that is used to launch. See http://www.morearty.com/blog/2006/05/23/flex-builder-ctrl-click-to-access-a-lanch-configs-properties/ for instructions on how to get to the dialog. Then, un-check the box for using the default URLs, and then change both the "Debug" and "Run" launch URLs.
February 8th, 2007 at 7:22 am
thanks Mike, that works great.
March 7th, 2007 at 9:35 am
Hey Mike,
Related to your reply to Hua… For startup time and screen real estate, I find myself changing the "URL or path to launch" from the defaults (running the [MyApp].html and [MyApp]-debug.html) to just run the associated SWF files in the standalone player/debug player (so I change the values to [MyApp].swf and [MyApp]-debug.swf)
Any idea if there is a configuration file or preference I can change (using the Eclipse plugin) to set these AS the defaults? I’d LIKE to be able to set it globally so that a NEW project already has these as the defaults when I create it. Right now I RUN the app, kill it, edit the values and then rerun / debug it. It’s getting to be a small but irritating step.
Thanks!
– Todd
– TC
March 7th, 2007 at 9:48 am
Hi Todd,
Sorry, but there is no built-in way to automatically change the default launch URLs as you suggest.
One way to do this, if you have sufficient knowledge of Eclipse, would be to write your own plugin that listens for the creation of new launch configurations, and then modifies them. But that would take quite a bit of work.
March 7th, 2007 at 2:43 pm
Yep, that’s what I figured. Nope to both knowledge and time… think I can spare the 10 seconds pre new app and do it manually : )
May 25th, 2007 at 4:30 am
[…] general info go here, and to see what macros are available go […]
June 3rd, 2007 at 7:26 am
Thanks man, I’ve got the feeling that someday I’m going to be thankful for bookmarking this one..
June 3rd, 2007 at 7:58 am
[…] a post by Neil Webb I bumped into a post by Mike Morearty in which he talked about changing the index.template.html file that Flex Builder automatically […]