HFS: Template macros: Difference between revisions

From rejetto wiki
Jump to navigation Jump to search
Line 47: Line 47:


=== Problem ===
=== Problem ===
All macros, except [[#Quoting|quoted ones]], are expanded. Consider having <tt>if|A|B|C</tt>. 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.
All macros, except [[#Quoting|quoted ones]], are expanded, not matter what. For example, if you have the command {.if|A|B|C.}, then B and C will both be expanded, no matter what A is.
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).


=== Workaround to the problem ===
=== Workaround to the problem ===

Revision as of 00:31, 4 September 2011

Template scripting is possible through commands, also known as macros. These commands are mostly the same for templates and for hfs.events.

Please note: Macros are currently not available in 2.2f, but they will be in 2.3. You can experiment with them using beta versions.

Macros are very powerful and can be used to add new functionality to HFS.

How macros work

Differences with symbols

You are supposed to already know how templates work. Macros are similar to symbols. They are something you type in the template that gets substituted (we say expands to) with meaningful content when the user watch the page.

While symbols are just a name, macros have a name and optionally parameters. Additionally, while symbols only expand to text (such as %user% or %url%), macros can be used to perform server-side commands (such as {.save.} and {.load.} ).

You can tell symbols from macros easily: symbols are surrounded by %percent% signs, while macros are surrounded by {.dotted braces.}.

More on them

How the macro will work depends on the parameters. The same macro can have a variety of functions based on its parameters.

The macro section will copy the content of a [section] of the template. The parameter in the macro specifies which section. 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]. A shortcut for this is {.$style.}.

Parameters

After the macro name you specify parameters with "|" (pipes) and then the parameter: {.name|parameter.}. If the macro requires more parameters, you just add more pipes: {.name | parameter | another parameter | a third parameter.}.

Readability

You can also put macros inside macros, or nest them. However, this can often 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.

Quoting

Sometimes you don't want HFS to consider plain text as part of the macro syntax. There's a way to tell HFS to not process the text, and it is called quoting.

To quote 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.

Sometimes you may need to use the pipe in plain text. To tell HFS not to interpret it as a parameter, you can quote it. Example: {.add to log|print{:|:}pipes.} to have the pipe character in your log. Additionally, you can use the command {.no pipe||.}

Available commands

Refer to the full list for available commands.

Execution order

The current execution order of macros is: from inner to outer, from left to right. Macros are like XHTML in that they cannot overlap.

An example: {.A {.B.} {.C.}.} {.D.}. In this scenario, the order is B, C, A, D. HFS cannot process A until B and C are processed because it doesn't yet know what the macro {.A.} contains.

Problem

All macros, except quoted ones, are expanded, not matter what. For example, if you have the command {.if|A|B|C.}, then B and C will both be expanded, no matter what A is.

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.

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].