Please note: Macros are not available in current version 2.2, but they will in 2.3, and you can experiment with them using beta versions.

edit How macros work

edit Differences with symbols

Macros are similar to symbols. They are something you type in the template and is substituted (we say expands to) with meaning content when the user watch the page.

While symbols are just a name, macros have a name and optionally parameters.

You can tell symbols by macros because symbols are surrounded by %percent% signs, macros are surrounded by {.dotted braces.}.

edit More on them

How the macro will work depends on the parameters. The same macro has a different effect when the parameter change.

The macro section will copy the content of a section of the template. But which section is specified by the parameters. So, you have one macro, section, but it will expand to any content as you change the name of the section (as parameter). Let's say {.section|style.} and it will copy the content of section [style].

edit Parameters

After the name of the macro you can put a character "|" (its name is pipe) and then a parameter: {.name|parameter.}. If the macro requires more parameters, like 2 or 3, you just add more pipes: {.name | parameter | another parameter | don't look at me.}.

edit Readability

Having macro in macro, nested, can be a mess to read. To increase readability you can

• split the syntax over several lines, and indent.
• add a final /macroname to know that you are closing just that macro, like {.load | something /load.}. The final /load is ignored by hfs, it's just for your convenience.

edit Quoting

Sometimes you don't want HFS to consider a text as part of the macros syntax. There's a way to tell HFS to leave untouched the text, and it is called quoting.

To quote a text you type {: then the text you want. To close the quoting just type :} .

This capability is very useful with macros set and if. You'll see later.

The pipe "|" is a special character, but you may need to use it as part of your text, without it being treated. In such case you can type it as {:|:}. Example: {.add to log|print{:|:}pipes.} to have the pipe character in your log.

edit Available commands

Refer to the full list for available commands.

edit Execution order

The current execution order of macros is: from inner to outer, from left to right.

An example: {.A {.B.} {.C.}.} {.D.}. In this scenario, the order is B, C, A, D. Because B and C are inner, but on the same level, so B is expanded before C.

edit Problem

All macros, except quoted ones, are expanded. Consider having if|A|B|C. Depending on the value of A, only B or C will be kept, and the other discarded. But whatever is the value of A, both B and C are expanded, before being kept or discarded. Many times you want C to be not even expanded, just because it's wasted CPU time, or because it will have undesired side-effects like when C contains the macro save (the file will be written anyway).

edit Workaround to the problem

Since having C not executed when A is true (from the previous example) is a very worth having feature, there's a workaround. By quoting the bodies of if, you avoid them to be executed. After the if choice between B (then) and C (else), it removes the surrounding quoting markers, if any. Let's see with an example

{.if| %user% | {.append|file.txt|someone is in!.} /if.}

As we stated before, this won't do what it seems to do. Append will always be executed, because every macro is executed. The only way to stop this is to surround with quoting markers

{.if| %user% | {: {.append|file.txt|someone is in!.} :} /if.}

By having quoted the append, it will only be executed if %user% is not void. This is because the if automatically removes the quoting markers.

Normally you would have to remove the markers yourself, by using macro dequote. But few macros (like if) have this special behavior, for your convenience. The special macros with such behaviour are: if, set, for, switch and breadcrumbs.

edit From the beginning

Sometimes you need to be sure something gets done before every page is built and sent to the browser. In such case, you can put all your macros in the section [special:begin].