1 Introduction to STML

The SkunkWeb Enviroment gives you two ways to do programming for your web applications: with code modules written in the programming language Python, and with templates, which are text documents with embedded programming code. In SkunkWeb, these templates' embedded programming code is written in a language called STML, or Skunk Template Markup Language. STML is like other markup languages such as HTML or XML, in that it uses tags to express its instructions.

This guide introduces the syntax and conventions of STML, and also includes a reference for all STML tags.

STML documents are text (usually HTML) documents with embedded programming tags. These programming tags are written in the special tag language we call STML (Skunk Template Markup Language).

At first glance, an STML document looks just like a regular text document. Its filename ends in .html (or .txt or whatever you want the output to be). Once you look at the document, however, you will notice the STML tags, which look like HTML tags with colons (:) inside them:

<:tag_name:>

SkunkWeb can recognize these STML tags, and follow the instructions you give in the tags.

STML tags are more complex and powerful than HTML tags. In HTML, a tag has a name (such as BR), and optionally some attributes, which are pairs of strings with a name and a value:

<A HREF="index.html">

In the above HTML tag, A is the tag's name, and the tag has one attribute. The attribute's name is HREF, and its value is the string "index.html" (quotes not included). In HTML, attribute values are always strings, and the quotation marks around a string are required only if there are spaces or tabs in the string.

STML tags are similar. However, STML uses Python! So the values of attributes can be things other than strings. Consider this STML tag:

<:happy_tag foo=hi bar="Hello there" 
     baz=5 dib=`myVar`:>

The name of the STML tag is happy_tag. (This tag is not a real STML tag, of course.) The tag has four attributes, with keys foo, bar, baz, and dib. Looks like an HTML tag so far, correct? But look at the attribute values.

The value of attribute foo is the "hi" (quotes not included). It's a string; if you type something without any quotes, STML assumes the value is a string. The value of attribute bar is "Hello there" (quotes not included in the value). It's also a string, of course. When you quote string values in STML, you can use Python's way of quoting strings with single or double quotes.

The value of attribute baz is 5. In HTML, this would be the string "5", and so it is in STML. But STML, which uses Python, is smart enough to know about Python's real data types, such as integers and floating-point numbers.

Therefore, if you want an attribute value to be something other than a string, use STML's best feature: the backticks. Any value which you enclose in backticks `like this` will be taken to be a Python expression. Thus when you say bar=5, STML sees the string "5" for bar, but when you say bar=`5`, STML sees the Python expression 5, which it knows is an integer.

The attribute dib is an example of more powerful uses of backticked Python expressions: the use of Python variables. The dib argument has a value `myVar`, which in Python means the Python object in the variable named myVar. Now you have a real programming enviroment in your STML document! You can use certain STML tags to assign strings and other Python objects to variable names, and then use those variable names in later STML tags:

<:set name=myVar expr=`56.7`:>
<:val expr=`myVar`:>

The STML <:set:> (see section 2.2, page ) tag lets you assign the result of a Python expression in the attribute named expr to a variable name in the attributed named name. In the example, you assign the floating point number 56.7 to the variable myVar. Then the <:val:> (see section 2.1, page ) tag displays the result of a Python expression in the attribute named expr as HTML output for the user.

You can do a lot inside the backticks. Any Python expression is legal: make calls to functions, make instances of Python classes, do arithmetic, do boolean logic with and and or. Python has a built-in function int(), for example, which takes an object (like a floating-point number) and turns it into an integer:

<:set name=myVar expr=`56.7`:>
<:set name=myOtherVar expr=`int(myVar)`:>

STML sees the Python expression int(myVar) and executes it; then it puts the result to the variable myOtherVar. myOtherVar now contains the integer 56.

STML has one other feature that is very different from HTML: in most cases, attributes do not have to be specified by name, because the order in which the tag expects the attributes is always the same. Thus you can specify just values without names, in the order expected by the tag. (This reference guide tells you the expected order of attributes of each and every STML tag.)

For instance, the <:set:> tag in STML expects an attribute named name followed by and attribute named expr. Instead of typing

<:set name=myVar expr=`56`:>

all the time, you can just type the values for name and expr in that order:

<:set myVar `56`:>

If you do use attribute names in STML tags, the order of attributes does not matter, because STML will see them by name and disregard the order of the attributes. The following example works, although you would probably not do it in practice:

<:set expr=`56` name=myVar:>

A few STML tags do not allow you to drop the attribute names in certain cases. Their documentation in this manual will always tell you when you cannot.