TechNote

Custom parameters and expressions in Dreamweaver MX templates

Custom Parameters allow you set up values or variables that can be used to determine certain functionality with templates in Dreamweaver MX. These parameters, combined with the expression language available in templates, will allow you to create complex templates that will give you a detailed level of control while giving a good degree of flexibility.

Custom parameters can be used to make tag attributes editable. You can choose to show or hide certain optional areas depending a condition that you set up. You can, for instance, set up an 'if...then' parameter that creates alternating colors for table rows when new rows are added in repeating region. You can set up a template that will automatically number your table rows and embedded table rows to create an auto numbering outline.

Setting up custom parameters and the expressions that use them may be the hardest part of working with templates in Dreamweaver MX, because it requires hand coding and an understanding of the expression language. This expression language is based on JavaScript. Using this expression language, you can use and manipulate values and custom parameters to create pages from templates that are flexible and customizable in ways not previously possible with prior versions of Dreamweaver.

In this example, all of the numbering is done with template parameters. The numbers will increment as you add rows. There are also parameters in the Notes column that will change depending on the number of rows.

Now with an idea of what is possible with template parameters, let's explore how the language of templates is set up.

Template Parameters

A parameter works like a variable. A parameter has a name, type and a value. Wherever you use the parameter name in the dwt file, the value will show in the template instance. Using the expression language, you can add, subtract, multiply or divide these parameters and the template will calculate the values accordingly.

In order to use a parameter, it first must be declared. You need to tell Dreamweaver MX that this parameter exists and give it a value. This declaration looks like:

This code must be handcoded in the source code. (The above line can easily be made into a snippet so you can drag and drop an instance whenever you need it.) While it can go anywhere on the page, Dreamweaver MX puts them in the head tag by default and it is a good idea to keep them together.
Parameter names can be pretty much whatever you want, but try to keep them short and clear. It's always a good idea to follow the general naming rules: no spaces or special characters and don't start with numbers.

For type, it depends on what you are trying to edit. Common types are color, text, number or boolean.
For value, give it whatever you wish to have as an initial value.

A parameter used for the table above is:

This parameter is used to set the border width of the table. It's initial value is 1 and can be set to any value by the developer. This parameter is named 'border' but it really can be used anywhere in the template.

In the above example, it is used as:

Dreamweaver MX will take the current value of border, which is 1 and add it as the attribute value.

There is another way to insert the value of a parameter. This is with the tag:

where "name" is the name of the parameter. This will simply show the value of that parameter. Using the above example, it would simply display the number 1.

While the result is the same, the use of this tag is different because it is full tag. Full tags cannot be used within another tag, meaning that you cannot put in a full tag inside the table tag itself.

<table border= cellpadding=3 cellspacing=0>

is not valid code.

But if you simply want to display the value of that parameter on the page, both will work. For instance:

<table >
<tr>
<td >@@(border)@@</td>
<td ></td>
</tr>
</table>

will display the current value of the parameter in the cells. So these parameters can be used as code and content.

Template Expressions

Now that template parameters have been defined, we can use them in template expressions. Using templates expressions, you can manipulate page content and attributes within the template instances, giving these pages added flexibility while maintaining the integrity of the dwt file.

As mentioned earlier, the template expression language is based on JavaScript constructs. Those familiar with JavaScript should find it easy to write template expressions. In order to create these expressions you can use any of the following operators:

	numeric literals, string literals (double-quote syntax only), boolean literals (true or false)
	unary operators: +, -, ~, !
	binary operators: +, -, *, /, %,&, \|, ^, &&, \|\|, <, <=, >, >=, ==, !=,<<, >>
	conditional operator: ?:
	parentheses: ()
	field reference (the "dot" operator)
	variable reference

Using these operators, you can create very functional and customizable templates. In the example above, the code that is used to create alternating table row colors in a repeat region is simply this:

<tr >

Where oddColor and evenColor are defined parameters.

This expression is used to count the number of rows (_index is a built-in template variable that counts rows in a repeat region), and odd uses the oddColor parameter value and even it uses the evenColor parameter. For a detailed explanation of the & operator, read this document.

Some other variables available with repeat regions are:

	_index The numerical index (from 0) of the current entry
	_isFirst True if the current entry is the first entry in its repeating region
	_isLast True if the current entry is the last entry in its repeating region
	_prevRecord The "_repeat" object for the previous entry.
	_nextRecord The "_repeat" object for the next entry.
	_parent In a nested repeated region, this gives the _repeat object for the enclosing (outer) repeated region.
	_numRows The total number of entries in this repeating region

These variables are used in the figures above. The numbers in the Child Repeat Region are generated using this code:

@@(_parent._index+1)@@ . @@(_index+1)@@

This grabs the row number of the parent table and the nested table, separates them with a period, giving you an auto numbering outline. Check out this sample file, which contains this functionality.

The variable listed above are built into Dreamweaver MX. They do not have to be declared as template parameters.