Changing the filenames in Flex Builder html templates
Comments(37) 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}.
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.
${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.
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.
You set the ${version_…} values by going to the Flex Compiler or ActionScript Compiler tab of the Project Properties dialog.
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.
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.
Where does the {$title} value get set?
${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).
Thanks Mike. Worked like a charm. May I suggest you make a blog entry _just_ on these tokens? Would be useful.
Good idea Raymond.
[...] 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. [...]
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
Whoa, cool, I didn’t know about that. Thanks for the link, Matt!
[...] 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… [...]
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
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.
thanks Mike, that works great.
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
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.
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 : )
[...] general info go here, and to see what macros are available go [...]
Thanks man, I’ve got the feeling that someday I’m going to be thankful for bookmarking this one..
[...] 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 [...]
This is quick a bit off topic, but I’m working with the new Flex Builder plug-in for Eclipse, and am creating an ActionScript project, which means I don’t have a MXML file to set all the fancy attributes of the application, such as the background color, page title, etc.
I’m lost, and have no idea where and how I can do this with an ActionScript only project. Any ideas?
Ben, some of them can be set as described here: http://www.morearty.com/blog/2007/01/24/macros-that-are-available-in-html-template-files/
Thanks Mike, my confusion was with where to put the [swf()] declaration. The link in your response made that clear, and I got everything working. Thanks!
[...] is again poorly documented by Adobe, but Renaun Erickson’s posting together with Mike Morearty who nicely documents the marco’s. If you’ve got this far, you need to consider added [...]
[...] morearty.com/blog … First Post [...]
[...] can also read this post by Mike Morearty on “ Changing the filenames in Flex Builder html templates” which will provide some more insight into the [...]
Hi mike..
really nice post about the index-html.template! :)
Lately, I’ve been facing problems running my application in full screen mode in a web browser. It works like a charm in the Adobe Flash player 9 but I get an Error 2152: SecurityError: Full sreen mode not allowed when I try to change the .displayStageSet to FULL_SCREEN.I’ve been trying to figure out a solution to my problem and finally I reached this blog of yours. But I still can’t make out if is there any way of solving it. What exactly do I change in the index-html.template file to get rid of it?
Nikhil, I’m not sure, please try asking on the "flexcoders" mailing list on Yahoo Groups.
What if you want your generated template to be named index.html?
Post as well as comments, very informative.
hello there, I just moved from flashdevelop to flex builder and i’m finding some things a little bit rigid actually.
Though I found this post (as others on your blog) really useful, i still couldn’t manage to do what i need.
Specifically, i would need to create a custon html template with swfaddress, swfobject and swffit.
I did that, but i can’t find a way to:
- choose a custom name (and path, let’s say "/swf/") for the exported swf
- avoiding that flex exports an *application*.html, as i’d need just an "index.html", customized with the wildcards.
I suppose these are quite simple tasks but i actually couldn’t find any info on that.
anyone can help?
jurito,
> choose a custom name (and path, let’s say "/swf/") for the exported swf
You can set the directory into which all generated files are written, by going to Project > Properties, Flex Build Path, and setting "Output folder"; put any directory name you want there. But I don’t think that’s what you are asking for — it sounds like you want a different directory hierarchy under bin-debug, e.g.
..bin-debug/
….swf/
……myapp.swf
….index.html
I don’t think we provide a way to put the swf under a subdirectory of the output directory. If that’s what you mean, please log an enhancement request at http://bugs.adobe.com/flex — thanks!
> avoiding that flex exports an *application*.html, as i’d need just an "index.html", customized with the wildcards.
We don’t provide a way to do that for "index.html", but you can do it for any other filename, such as "index.htm". E.g. rename index.template.html to index.template.htm. Again, please file an enhancement request if you’d like this changed.
[...] http://www.morearty.com/blog/2006/12/11/changing-the-filenames-in-flex-builder-html-templates/ [...]
Thanks, very helpful