Dreamweaver Article

Explaining Template Parameters and Expressions

One of the most difficult things to wrap your head around is Dreamweaver MX template parameters and expressions. This article attempts to explain them to you in a way that makes sense and helps you easily retain and apply them.

Requirements

• Dreamweaver MX

  • Try
  • Buy
   
• Download the completed files for this article

Remember when you were in sixth grade Math class and the teacher started teaching you equations?

2 + X = 5 or 5 – 2 = X

Template expressions are almost the same as those math equations.

Or, if English (or any language) was your favorite subject , think of an expression as a sentence where you fill in the blank.

Mary had a little ______.

Both of these are examples of expressions. Similarly, these same two expressions also contain a parameter (in short, a variable that you can uniquely define on each page). In the above examples, in the Math equation, the parameter is X, and in the English sentence, the parameter is the missing word _____ (or lamb, if you need help!).

Template Parameters

As discussed above, you can think of template parameters as page variables that are user configurable and that you can reference anywhere in the template as long as the reference is not contained within an editable region. There are five different types of parameters, described in the list below. You must set the parameter with a default value in the template, and you can customize that value on each child page based on that same template. In other words, you might define a text type parameter named myname in the template equal to Brad (where "Brad" is the default value). Any page you make from the template (page1) will use the default value until you change it for that page. You can easily change it on the generated page (page1) to Murray with a couple of mouse clicks (discussed below).

Parameter Requirements

• Must be defined in the template.
• Must be defined only once in the template.
• Must be defined in a template's non-editable area of the head block.
• Each parameter must have a unique name (preferably with no spaces, special characters, or JavaScript reserved words. See more in our book, Dreamweaver MX Templates).
• Must be one of five permitted data types: text, boolean, color, URL, or number. You can learn more about the five allowed types of parameters in our tutorial, Template Parameter Types.
• Can be manually changed in the template; changes will not affect already existing child pages but will affect any new page made based on the template.
• Must not be manually altered using code view on the child page or the change will not take effect.
• Must be changed on the child page using Modify > Template Properties... (in Dreamweaver MX) or Format > Template Properties... (in Contribute).

Parameter Format for the Template

The following is an example of parameter format based on the template.

 < !-- TemplateParam name="" type="" value="" -->

Note: Do not leave the following parameters as null strings: name, type, and value.

Parameter format for the Child Page

The following is an example of parameter format in a child page based on the template.

 < !-- InstanceParam name="" type="" value="" -->

Here are some sample parameters and values for each type of template parameter.

If your parameter value contains a double quote (") character, then you must entity encode the double quote or else the template engine will either throw an error (in most cases), or it will not display all the parameter data when you reference it through an expression. This is because the double quote character is a string identifier. Find below some common entity encoding conversions for the double quote below.

Caution: When using the URL parameter type, forget what you know about the Dreamweaver asset management engine, and reference these parameter type values as if you were making the association in the child of the template. In other words, instead of referencing an image (from a file in the templates folder) as ../images/myimage.gif, you would reference it as if you were in the parent folder already, such as images/myimage.gif.

Caution: If you move an asset, such as moving an image to another folder location, or renaming the referenced asset, Dreamweaver somewhat manages the value of the URL type parameters. But only does so in the child pages of the template; and not in the template.

Caution: When using the boolean parameter type, the value must be a lowercase true or false as the template engine does not accept an uppercase True/False or TRUE/FALSE. Using any uppercase in the boolean value will result in an error message when you try to save the template.

Using Parameters in the Template

Template parameters, which are similar to JavaScript variables, do not display values on the child page. In other words, simply creating a parameter on a page will have no effect on the page. To display the value of the parameter or use it in calculations, you must reference that template parameter in the template using a template expression. Read on for more information.

Passthrough Parameters

Our discussion of parameters wouldn't be complete if we didn't discuss these little critters. Think of passthrough parameters as a way to tell Dreamweaver MX to ignore the expression and to pass its value and exposure through to the next 'generation' of pages.

Caution: You cannot use passthrough parameters on root level templates. You can use them in any nested template without incident.

Parameter Format - Template

Here is an example of the syntax for passthrough parameters.

 < !-- InstanceParam name="" type="" value="" passthrough="true" -->
@@@(ParamName)@@@
                

Parameter Format - Child page

Nothing displays in code view. Simply put, passthrough parameters only relate to nested templates. In effect, they enable you to specify that the parameter cannot be customized on the second generation templates child page, but they will continue to be customizable on any third generation template's child pages. Our book, Dreamweaver MX Templates, covers this from pages 114 to 117. Note the unusual syntax for the passthrough parameter expression (the triple "@").

Template Expressions

As discussed above, you can think of template expressions (as placed on the template page) as statements, which makes the defined and referenced parameters usable on your template-driven child pages.

Expression Requirements

• Must be defined in the template
• Must be in a template's non-editable area
• Can be manually changed in the template; changes will affect all existing and new child pages when you save the template and update child pages
• Can reference template parameters by name: Optional Regions, Repeating Regions and Repeating Tables. See our book for more information

Expression Format - Template

Expression Results - Child page

Using Expressions in the Template

When you create a child page of a template, the template engine evaluates all expressions on the template page and writes the results of each evaluation to the child page. If the expression uses a parameter, then the template engine substitutes the parameter value wherever it sees the parameter used in an expression. If that expression uses the parameter's value in a calculation, the expression calculates a result uses it to display something. The template engine runs when you create a new page from the template and when you use Modify > Template Properties... The dialog box closes after you press OK button.

Because expressions can contain characters such as ', ", and @, you must convert them to the appropriate entities or character codes for the template engine to accept the values. See the conversion chart below.

Common Conversions

Most of our tutorials at http://www.dreamweavermx-templates.com directly relate to parameters and expressions. Using this new knowledge, you'll be able to take advantage of other tutorials on our site.

Conclusion

Hopefully, the information we have provided clarifies template parameters and expressions so that you can use them more easily!

About the authors

Submit feedback on our tutorials, articles, and sample applications.