5.2 Placeholder Syntax Rules

Placeholders follow the same syntax rules as Python variables except that they are preceded by $ (the short form) or enclosed in ${} (the long form). Examples:

$var                                        
${var}                                      
$var2.abc['def']('gh', $subplaceholder, 2)  
${var2.abc['def']('gh', $subplaceholder, 2)}

We recommend $ in simple cases, and ${} when followed directly by a letter or when Cheetah or a human template maintainer might get confused about where the placeholder ends. You may alternately use $() or $[], although this may confuse the (human) template maintainer:

$(var)                                      
$[var]                                      
$(var2.abc['def']('gh', $subplaceholder, 2))
$[var2.abc['def']('gh', $subplaceholder, 2)]

Note: Advanced users can change the delimiters to anything they want via the #compiler directive.

Note 2: The long form can be used only with top-level placeholders, not in expressions. See section 5.3 for an elaboration on this.

To reiterate Python's rules, placeholders consist of one or more identifiers separated by periods. Each identifier must start with a letter or an underscore, and the subsequent characters must be letters, digits or underscores. Any identifier may be followed by arguments enclosed in () and/or keys/subscripts in [].

Identifiers are case sensitive. $var does not equal $Var or $vAr or $VAR.

Arguments inside () or [] are just like in Python. Strings may be quoted using any Python quoting style. Each argument is an expression and may use any of Python's expression operators. Variables used in argument expressions are placeholders and should be prefixed with $. This also applies to the *arg and **kw forms. However, you do not need the $ with the special Python constants None, True and False. Examples:

$hex($myVar)
$func($arg=1234)
$func2($*args, $**kw)
$func3(3.14159, $arg2, None, True)
$myList[$mySubscript]

Trailing periods are ignored. Cheetah will recognize that the placeholder name in $varName. is varName, and the period will be left alone in the template output.

The syntax ${placeholderName, arg1="val1"} passes arguments to the output filter (see #filter, section 7.9. The braces and comma are required in this case. It's conventional to omit the $ before the keyword arguments (i.e. arg1) in this case.

Cheetah ignores all dollar signs ($) that are not followed by a letter or an underscore.

The following are valid $placeholders:

$a $_ $var $_var $var1 $_1var $var2_ $dict.key $list[3]
$object.method $object.method() $object.method
$nest($nest($var))

These are not $placeholders but are treated as literal text:

$@var $^var $15.50 $$