Template Parameters & Expressions Explained

One of the most difficult things to wrap the 'ole cranium around is Dreamweaver MX Template Parameters and Expressions. This article will try to explain them to you in a way that makes sense and can be easily retained and applied.

Remember when you were in Grade 6 math class and the teacher started teaching you equations? Template Expressions are pretty much the same as a math equation.

2 + X = 5 or 5 - 2 = X

Or, if English is your favorite subject (also insert any language of choice that you learned in school), an expression can be thought of as a sentence in which you have to fill in the blank.

Mary had a little ______.

Both of these are examples of expressions. Similarly, these same two expressions also contain a parameter (for all intents and purposes, a variable that can be uniquely defined on each page). As related to our examples above, for the Math equation the parameter is X, and the English parameter is the missing word _____ (lamb, if you need help!).

Template Parameters

As discussed above, template parameters can be thought of as page variables that are user configurable and can be referenced anywhere in the template as long as the reference is not contained within an editable region. There are 5 different types of parameters, described in the list below. The parameter must be set with a default value in the template, and that value can then be customized on each child page based on that same template. In English, you might define a *text* type parameter named myname in the template to equal Brad (i.e., it has "Brad" as the default value). Any page you make from the template (page1) will use that 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 - as outlined in our book).
Must be one of 5 allowed types (As discussed in this tutorial) - text, boolean, color, URL and number.
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... (Dreamweaver MX) or Format » Template Properties... (Contribute).

Parameter format - Template:

(note that 'name', 'type' and 'value' should not be left as null strings)

Parameter format - Child page

(see note above)

Parameter Samples
Parameter Type		Allowable Value Examples
boolean		false
boolean		true
color		#666
color		#666666
color		Blue
number		123456.00
number		-123456.00
text		Anything you want here, even entity encoded characters and punctuation.
URL		../images/myimage.gif
URL		/images/myimage.gif
URL		http://www.mydomain.com/images/myimage.gif
URL		mypage.htm

If you need a parameter value containing the double quote (") character, then that double quote must be entity encoded or else the template engine will either give you an error (in most cases), or it will not display all the parameter data when referenced through an expression because the " character is used as the string identifier.

Caution - When using the URL parameter type, forget what you know about Dreamweaver's 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 - Dreamweaver 'sort of' manages the value of the URL type parameters but ONLY in the child pages of the template and NOT in the template, if you were to move the asset to another folder location or rename the referenced asset.

Caution - When using the boolean parameter type, the case of the value is important, it MUST be either true or false as the template engine does not recognize True/False or TRUE/FALSE as allowable values and an error message will be displayed when you try to save the template (in other words, the values true and false must be spelled out in lower case).

Common Conversions
Character		Character Code/Entity
"		" or "

Using parameters in the template:

Template parameters (similarly to javascript variables) are non-displayed values for the child page. What this means is that simply creating a parameter on a page will have no effect on the page. To have the value of the parameter display or be used in calculations, you must reference that template parameter in the template using a template expression (discussed below).

Passthrough Parameters:

Our discussion of parameters wouldn't be complete if we didn't discuss these little critters.

Caution - Passthrough Parameters cannot be used on root level templates. The can be used in any nested template withour incident.

Parameter format - Template:

@@@(ParamName)@@@

Parameter format - Child page:

Nothing is displayed in code view

Simply put, Passthrough parameters only relate to nested templates and in effect allow you to tell the parameter to not be customizable on the second generation templates child page but will continue to be customizable on any third generation template's child pages. Our book covers this pretty well from pages 114 to 117. Note the unusual syntax for the passthrough parameter expression (the triple "@"). Think of this as a way to tell DMX to ignore the expression and to pass its value and exposure through to the next 'generation' of pages.

Template Expressions

As discussed above, template expressions (as placed on the TEMPLATE page) can be thought of as statements which bring the defined and referenced parameters to life 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 the template is saved and child pages are updated.
Can reference Template Parameters by name, Optional Regions, Repeating Regions and Repeating Tables. See our book for more information.

Expression Format - Template:

Expression Examples - Template
Expression Type		Expression Sample
Simple		@@(ParamName)@@ OR <!-- TemplateExpr expr="ParamName" --> OR <!-- #TemplateExpr expr="ParamName" --> Notes: The top expression can be used inside tags. eg. <a href="@@(LinkURL)@@">Link</a> The second and third expression cannot be used inside tags. The last expression is old technology and recommended that you don't use it since its functionality will likely be removed when Dreamweaver is next updated. We recommend that you only use the top expression format.
Complex		@@(ParamName!="Me"?"True Resultant":"False Resultant")@@
Complex #2		@@(ParamName!="Me"?ParamName:OtherParamName)@@
Nested Complex		@@(ParamName!="Me"?(OtherParamName=="You"?"foo":"bar"):"I dunno")@@
Region Lock		@@(" ")@@ (Nested Templates ONLY)

Expression Results - Child page:

Expression Examples - Child (Instance)
Expression Type		Expression Sample
Simple		Value of ParamName Value of ParamName Value of ParamName
Complex		If ParamName!=Me - True Resultant If ParamName=Me - False Resultant
Complex #2		If ParamName!=Me - ParamName Value If ParamName=Me - OtherParamName Value
Nested Complex		If ParamName != Me, then if OtherParamName = You - foo If ParamName != Me, then if OtherParamName != You - bar If ParamName = Me - I dunno
Region Lock		Nothing at all except the contents of the editable region, since this acts as a region lock in Nested Templates

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 then the calculation is performed and the result is used to determine what to display. The template engine runs when a new page is created from the template and when the Modify » Template Properties... dialog closes after the OK button is pressed on the dialog.

Because expressions can contain characters such as ', ", and @ these MUST generally be converted to their respective entities or Character Codes for the template engine to accept the values. See the conversion chart below.

Common Conversions
Character		Character Code/Entity
'		'
"		" or "
@		@

Most of our tutorials at http://www.dreamweavermx-templates.com directly relate to parameters and expressions. With this new knowledge, perhaps the other tutorials on our site will make more sense.

Conclusion

Hopefully the information we have provided will steer you in the correct direction and make the proverbial light bulb turn on. It truly isn't rocket science!

Downloads:

Working files for you to download are available here: ExprParams.zip