Flashbang! Media: Tutorials: Template Parameters




	FlashBang! Basics

	Adding Sounds

	Custom Presets

	Using Behaviors

	Setting Template Parameters

Setting Template Parameters in a FlashBang! Button
by Brad Halstead and Murray Summers

It would be impossible to incorporate template parameters in a traditional Flash movie as all the attributes are contained within the .swf file. FlashBang!, however, takes advantage of the newly-introduced parameter FlashVars which, properly used, exposes attributes through variables set in the HTML code. For example, in a FlashBang button, the variable FBlabelText controls the text that appears on the button. Some of these variables can be transformed to template variables through the FlashBang! interface, while others need to be modified in the code itself.

In this tutorial, you'll learn how to add template parameters to your Web page - and how to properly connect them to a FlashBang! button. Once your template parameters are in place, you can easily change the label, link or state - or any other parameter (if you've configured them - a complete list can be found on pages 50 & 51 of the FlashBang! User Guide) of a FlashBang! button - in a template-derived document that will work nicely in Macromedia's Dreamweaver MX & Contribute.

So, you've decided that you want to use FlashBang! buttons for navigating your web site and this web site design is going to be controlled through the use of a template that has the navigation system in a locked (non-editable) area of the template instances (child pages). And, you have come to this tutorial for instruction as to how to do this! Well, you've come to the right place, bunky....

A sample site has been made and is available for download so that you can compare your tutorial exercise to a completed project. Included with this sample site is the template that you will be using for the steps in this tutorial. The template is named MyTemplate.dwt and is located in the site's Templates folder (where else?).

Prerequisites

It's important that you complete the User Guide exercise starting at page 5 (Starting with a Bang!) or the online FlashBang! Basics tutorial so that you can understand a little about FlashBang!'s interface.

It's assumed that you have Dreamweaver MX running, a new site defined referencing the folder into which you extracted the downloaded file, and your display set to show Code and Design Split View for this exercise.

Tutorial project files

The Template Requirements

In developing this tutorial, the following practical goals were always foremost. The resulting template must be...

Bandwidth friendly - this will reduce load times of each page;
Contribute and Dreamweaver MX friendly - users of Contribute and Dreamweaver MX must be able to customize the FlashBang! buttons easily even though the FlashBang! buttons are in a locked region of the template;
- Customizable FlashBang! button labels - give users the ability to change the label text of individual FlashBang! buttons;
- Customizable FlashBang! button URLs - give the users the ability to change the target URL's of individual FlashBang! buttons;
- FlashBang! buttons to show appropriate down state as required - if the active page matches a FlashBang! button, then set the down state of that FlashBang! button;
- FlashBang! button URL to be disabled if that FlashBang! buttons state is set to down - if the active page matches a FlashBang! button, then disable the FlashBang! buttons target URL;
- Display a warning message if the Page Name does not match a FlashBang! parameter controlled button name - if the user has not named the page to match a FlashBang! button then display a warning message to advise the user that they must change the page name and provide a list of acceptable values;
Able to use the page name to control the page's title, heading, and the down state and URL of individual FlashBang! buttons. Also, it must prevent the user from changing the NullLink and PageNameWarning parameters - this will reduce the amount of editing required by the content editor and will make for fewer mistakes in the long run.

Limitations

As with anything in web site development, there are certain limitations that simply cannot be overcome. Contribute users will not be able to add buttons to the navigation system. There is a workaround (using template optional regions) that we will present at the end of the tutorial in a section named Enhancements but it has its own limitations also.

Getting Started

You've downloaded the project files, setup your site definition, and now it's time to get to work!

Use DMX to open the file named MyTemplate.dwt located in the Templates folder.

This template (used exclusively in this tutorial) already has all the groundwork done for you to reduce the size of this tutorial. To compare your progress with a finished example, compare it with done-SetStateBase.dwt.

Adding the Required Parameters

We want to have various items controlled by individual template parameters as outlined by the requirements. So, add the following code to the head region of the template using Code View (immediately above the closing head tag </head>):

NOTE: You can use the text file named parameters.txt in the Code folder of the site definition to copy from instead of typing it all by hand.














What are each of these? Please see the table below describing each parameter.

Parameter Table
Item # Parameter Description

1
Name: PageName
Type: text
Value: Home
Description: This parameter will contain the actual page name for each template instance (child page). It must be uniquely set on each child page created by the end user, using the Modify » Template Properties... menu item.
This is the master controlling parameter and it's the one that the end user should be changing! Changes to this single parameter drive the default values of most of the other parameters.

2

Name: PageNameWarning
Type: boolean
Value: false
Description: This parameter is automatically set to true or false depending on whether the PageName matches FB#Label. If there is no match, the value is set to true; if matched, the value is set to false. It is used as an error trap in this template.

It doesn't matter what the user sets here since its value is controlled elsewhere on the page through error detection and correction. This parameter already exists on the page since the region was already part of the template.

3

Name: FB1State
Type: number
Value: 0
Description: This parameter controls Button #1's state (up or down) and is automatically set by comparison between the PageName & FB#Label values.

One of these parameters is required for each button desired, and each is named with the button number embedded, as in FB1..., FB2..., FB3..., etc.

It doesn't matter what the user sets here since its value is controlled elsewhere on the page through template expressions and internal logic.

4

Name: FB1Label
Type: text
Value: Home
Description: This parameter controls the label text of the FlashBang! button. The end user must set this value on each child page, using Modify » Template Properties... menu item.

Additionally, forethought should be used whilst creating the template to set these values prior to creating child pages from the template.

One of these is required for each button desired; as before, the naming convention is FB1..., FB2..., FB3..., etc.

It matters what values are used here since each such value will be compared to other page parameters to set the FlashBang! button state, url, page title, and page heading.

5

Name: FB1Link
Type: URL
Value: index.htm
Description: This parameter controls the target URL of the FlashBang! button. The end user must set this value on each child page, using the Modify » Template Properties... menu item.

Additionally, forethought should be used whilst creating the template to set these values prior to creating child pages from the template.

One of these is required for each button desired; as before, the naming convention is FB1..., FB2..., FB3..., etc.

Note: You should not use relative to template links in this parameter in the template because this link is not managed when a new page is created from the template (this is true of any link embedded within a template expression).

6

Name: NullLink
Type: URL
Value: javascript:;
Description: We've set this as a parameter to make it a little easier to do value setting later on. We will be using this parameter multiple times so if we decide to change it in the future, we only have to change it in one place to effect a sitewide change.

It doesn't matter what the user sets here since its value is controlled elsewhere on the page through template expressions and internal logic.

Save the template.

Setting the Title to use the PageName Parameter

Using Code View, locate the title tag near the top of the page.
Delete the line above and below the title tag. The lines should read:
Above: 
Below: 

TIP: You could have positioned your cursor in the title tag contents, then select the Modify » Templates » Remove Template Markup menu item which will remove the doctitle editable region from your template so that you may use a template parameter instead. BUT, there is a bug in Dreamweaver MX that kills the CSS rendering in Design view. To refresh the design view, you can use Edit » Undo (CTRL-Z [CMD-Z for the Mac]) and Edit » Redo (CTRL-Y [CMD-Y for the Mac]) or save, close and re-open the template. We don't want to scare you with this....
Select and delete the word: Home from the title tag contents and in its place type: @@(PageName)@@ so that the title tag now looks like this:
<title>FlashBang! Demo :: @@(PageName)@@</title>
TIP: You can use the Document Toolbars Title field to modify this, instead of code view. Additionally, the Modify » Page Properties... menu item can also be used.
Save the template.

Setting the Heading to use the PageName Parameter

Using Code View, locate, select and delete the word: HEADING from between the H1 tags and in its place type: @@(PageName)@@ so that the H1 tags now look like this:
<h1>@@(PageName)@@</h1>
NOTE: After doing this, the heading changed to the '@@' icon, indicating that an expression has been placed at that location.
Save the template.

Add the FlashBang! Button (Yes, singular!)

If you followed the FlashBang! Basics tutorial, then you are already aware of how to insert a FlashBang! button. There are some minor differences when working with Dreamweaver MX Templates and these will be discussed below.

Position your cursor in the top row of the left table (cleverly named "leftTable") in the file MyTemplate.dwt (which should already be open).
Select the Insert » Interactive Images » FlashBang! Button menu item.
In the FlashBang! dialog, make the following Selections:
Button: Arcobaleno » 125x26 » PixaLova:Green
Save As: ../assets/FB_Demo.swf
Label: @@(FB1Label)@@
Link: @@(FB1Link)@@
Show Down State: Checked
On Rollover: Click the Choose button and make the selections as below:

In the FlashBang! Sounds dialog:
Sound: InnerSpace » Boink_v.mp3
Save As: ../assets/FB_Demo.mp3

Click the OK button of the FlashBang! Sounds dialog.

All other FlashBang! Button dialog settings: Leave at default
Click the OK button of the FlashBang! Button dialog.

Remember that some of our requirements are to have a customizable label, URL and state. These are controlled through the FlashBang! variables labeled: FBlabelText, FBbtnURL, FBbtnIsDown which exist in the Object Parameter named FlashVars & the Embed segment of the FlashBang! button code. We took care of FBlabelText and FBbtnURL when we created the FlashBang! object through the FlashBang! dialog, but there was no way to set the parameter in the dialog because it is a checkbox.

Since we created the FlashBang! button with the down state enabled (so that the variable existed in the FlashBang! button code) we can do a find and replace for FBbtnIsDown=1 and replace it with FBbtnIsDown=@@(FB1State)@@ by performing the following:

Select the Edit » Find and Replace... menu item.
In the Find and Replace dialog, populate the UI with the following:
Find In: Current Document
Search For: Source Code then FBbtnIsDown=1
Replace With: FBbtnIsDown=@@(FB1State)@@
Click the Replace All button.

There should have been 2 items found and replaced.
Our FlashBang! button code (using Code view) should now look something like this:

<object classid="clsid:D27CDB6E-AE6D-11cf-96
B8-444553540000" codebase="http://download
.macromedia.com/pub/shockwave/cabs/flash/
swflash.cab#version=6,0,29,0" width="125"
height="26">
< param name="movie" value="../assets/FB_Demo.swf">
<param name="quality" value="high">
<param name="FlashBang!" value="Arcobaleno
125x26/PixaLova__Green_125x26.swf">
<param name="FlashVars" value="FBlabelText=
@@ (FB1Label)@@&FBlabelRollOutColor=
000000&FBlabelRollOverColor=FFFFFF&FBbtnRoll
OutFirstColor=D3D3D3&FBbtnRollOutSecondColor
=808080&FBbtnRollOverFirstColor=696969&FBbtn
RollOverSecondColor=DCDCDC&FBbtnPressFirst
Color=B0C4DE&FBbtnPressSecondColor=778899&
FBbtnURL=@@(FB1Link)@@&FBbtnIs
Down=@@(FB1State)@@&FBeventRollOverSound
=assets/FB_Demo.mp3">
<embed src="../assets/FB_Demo.swf" quality=
"high" pluginspage="http://www.macromedia.
com/go/getflashplayer" type="application/x-
shockwave-flash" width="125" height="26"
flashvars="FBlabelText=@@(FB1Label)@@
&FBlabelRollOutColor=000000&FBlabelRoll
OverColor=FFFFFF&FBbtnRollOutFirstColor=
D3D3D3&FBbtnRollOutSecondColor=808080&FB
btnRollOverFirstColor=696969&FBbtnRollOver
SecondColor=DCDCDC&FBbtnPressFirstColor=
B0C4DE&FBbtnPressSecondColor=778899&
FBbtnURL=@@(FB1Link)@@&FBbtn
IsDown=@@(FB1State)@@&FBeventRoll
OverSound=assets/FB_Demo.mp3"></embed>
</object>

You may have to do other Find and Replace queries if you have set other FlashBang! button variables as parameters in the Template.
Using Code view, ensure that the closing TD tag gets butted up against the closing Object tag or a space will be visible in Internet Explorer between buttons.

The resulting line should look like this:
</object></td>
If you are Netscape 4.x conscious, you should butt the above up against the closing embed tag as well, so that the resulting line looks like this:
</embed></object></td>
NOTE: The above procedure should be done for each button on the page as you create each instance and modify the parameters as you will learn below.
Save the template.
We can use the parameters: @@(FB1Label)@@ and @@(FB1Link)@@, because they are already defined in the template. We could even use them if they were not defined although the template would throw an error when it was saved.

Create Additional Unique FlashBang! Button Instances

This is the coolest thing! Because we are using Template Parameters to specify the buttons label, url and state, we only need the a single SWF and MP3 file to represent all the buttons. We can then copy the page code to make additional unique instances of that same button thereby saving bandwidth.

Select the FlashBang button that you just inserted on the page by clicking on it once.
Hold the Control (CMD for the Mac) key down, select and drag the FlashBang! button to the next row of the table (or use the familiar Ctrl-C/Ctrl-V [CMD-C/CMD-V for the Mac] to copy and paste). This new button instance should be active - highlighted.
Using the FlashBang! Property Inspector, make the following changes:
Label: @@(FB2Label)@@
Link: @@(FB2Link)@@
Using Code view, look for the two instances (one for the FlashVars parameter of the object and one in the embed tag) of @@(FB1State)@@ attached to this button and change them to @@(FB2State)@@.
Don't forget to butt the closing tags up against each other for this button!
Repeat steps 2 through 5 (using the second button), this time changing the FB2 parts to FB3. You now have the 3 template controlled FlashBang! buttons on your page. Now, it's time to add an additional button that is not template controlled so you can see the error message in action.
Repeat steps 2 through 5 (using the third button), this time making the following changes:
Label: Dummy
Link: dummy.htm
Replace the two instances of: &FBbtnIsDown=@@(FB3State)@@ with &FBbtnIsDown=0
Save the template.

Error Protection

We want to prevent the end user from being able to inadvertently set parameters that shouldn't be set. So, add the following code to the head region of the template using Code View (immediately above the closing head tag - </head>):

TIP: In this instance, the error correction code can go in either the location specified above, or immediately below the opening body tag - <body>. If the multipleIf statement actually writes data to the page then it needs to go in the body block, but since our error correction code only sets template parameters through the use of expressions, then we don't need to have it in the body block of the page. The only advantage to moving it to the head block is that the white space will be removed from the compiled body region thereby preventing possible browser issues if the design were different.

NOTE: You can use the text file named error_correction.txt in the Code folder of the site to copy from instead of typing it all by hand.










What is all this? Let's break it down into sections then, using the file error_correction.txt.

Line 1 sets the parameter NullLink equal to 'javascript:;' so that the end user cannot change the value unless they have direct access to the template.

Line 2 sets the parameter PageNameWarning to FALSE so that the user cannot accidentally over-ride the message and make the warning layer display when there is no error.

The remainder of this block of code is determining if the PageName parameter matches something. If PageName does match something (lines 4 through 6) then it sets the appropriate button's state to down, resets the remaining buttons' states to up and sets the same button's link to null. If PageName doesn't match, then the warning layer is set to display (since it is an optional region).

Save the template.

Modifying the Warning message

Our requirements indicate that we use a warning layer to display when there is an incorrect PageName set. Our error protection routine detects when this occurs and sets the layer to display (because it is an optional region), as we discussed above.

Our problem now is that we want to be able to display the allowable values for these parameters in that error message, but those may change from time to time, so how do we address that?

It's really not that difficult. Since the user can set the page names using the template parameters FB1Label, FB2Label and FB3Label, we just use those parameters in the warning layer.

Using Code view, replace the following parts of the warning layer (<div id="warningmsg">):
X: @@(FB1Label)@@
Y: @@(FB2Label)@@
Z: @@(FB3Label)@@

NOTE: The 3 letters (X, Y and Z) changed to the '@@' icon indicating that an expression is now at each of these locations.

Save the template.

Create the Required Template Instances

Since we used a plan when developing the template, we know that we need the following pages created:
Home - index.htm
About - about.htm
Contact - contact.htm
Dummy - dummy.htm

So, lets do that, shall we?

Select the File » New menu item
Select the Templates tab
Select the desired site (The one you created for this tutorial)
Select the template: MyTemplate
Place a check in the 'Update Page when Template Changes' checkbox and click the Create button. (If you do not set this checkbox, then an exact duplicate of the template is made, however all template markup is removed and you will lose all the template controlled items. Any parameters that were used will be set with their template set values).
Once the new page opens, using File » Save As..., save the page as index.htm in the site root.
Use the Modify » Template Properties... menu item, scroll down and change the value of the parameter named PageName to Home if it isn't set already (as it should be since that's the default value) (leave the nested template checkbox unchecked).
With index.htm still open, use the Modify » Template Properties... menu item, scroll down and change the value of the parameter named PageName to About (leave the nested template checkbox unchecked).
Using File » Save As..., save the page as about.htm in the site root.
Use the Modify » Template Properties... menu item, scroll down and change the value of the parameter named PageName to Contact (leave the nested template checkbox unchecked).
Using File » Save As..., save the page as contact.htm in the site root.
Use the Modify » Template Properties... menu item, scroll down and change the value of the parameter named PageName to Dummy (leave the nested template checkbox unchecked).
Using File » Save As..., save the page as dummy.htm in the site root.
Close all open pages. (Save any if DMX prompts you to do so).

Steps 6 through 13 have used exactly the same page each and every time to make other instances of the page. The only change we made was to the template parameter PageName to make each page unique. The file named dummy.htm is our error proving pageLet's see these in action now.

Using the site panel, select index.htm and press F12. Your browser should open with the Home button in the down state.
Click on the button labeled Home and note that nothing happens. This is because we nulled the link so that the page didn't reload. This is a sign of professionalism.
Click on the other buttons labeled About and Contact. Note that their pages open with the appropriate button set to the down state, this tells the end user where they are in the site.
Notes:
A. The button's assigned sound may not play when previewed through your local browser due to a possible bug in the flash player! Rest assured, if you preview the page through a local server or live online that the sound will play just fine.
B. If you are saving files outside of the root folder with any sort of folder architecture on your site, then you need to set the FB#Link to absolute or root relative values as explained in the FlashBang! User Guide.

Enhancements

As we discussed in the introduction, you can have more buttons and allow the user to enable their visibility by adding the required parameters ahead of time and setting the display state of the optional regions to false initially (thereby effectively disabling them from view). If you elect to do this, you would need to expand the multipleIf conditional region to manage these additional buttons, as well as make each row in the table that holds a new button an optional region. Ultimately though, there is no way to programmatically add/remove buttons and their required parameters and retain the template control with a static web site.

Included in the download files is a template named: SetStateBase2.dwt, play with this template by creating a child page, saving it, then setting the template properties using Modify » Template Properties... menu item. Look for parameters labeled FB#Option (where # is a value from 4 through 7) to enable/disable additional buttons. Also be sure to check out the way the error correction routine has been modified and the warning layer contents.

Summary

This tutorial should give you a good idea of how easy it is to add and specify FlashBang! parameters in Templates. If you have any questions about this tutorial, please feel free to drop us a line at support@dreamweavermx-templates.com.

About Us - Contact Us

Setting Template Parameters in a FlashBang! Button by Brad Halstead and Murray Summers