HFS: 模板宏

From rejetto wiki
Revision as of 17:55, 5 September 2020 by NaitLee (talk | contribs) (Created page with "HFS 支持服务器端语言(指令),也叫做宏。这种语言在模板和事件脚本中的表现几乎相同。 '''请注意:''' 2.3 之前的版本不支持宏...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

HFS 支持服务器端语言(指令),也叫做宏。这种语言在模板和事件脚本中的表现几乎相同。

请注意: 2.3 之前的版本不支持宏。

宏很强大,可以用于给 HFS 及其文件页面添加新的功能。

宏是如何工作的

与占位符的不同

您需要对模板如何工作有大概的了解。宏与占位符相似。输入的宏将在用户浏览页面时被替换为有实际意义的内容(我们称之“扩展”)。

占位符只代表一个名称,而宏有自己的功能及相应的参数。占位符只会被替换为文本(比如 %user% 替换为当前用户),而宏被用来在 HFS 服务器端进行指令操作(如 {.load.} 用以加载文件内容)。

您可以很简单地区分占位符与宏:占位符由 %百分号% 包围,而宏由 {.带点的大括号.} 包围.

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|{.section|stuff /section.} /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 and Solution

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.

Since it is important to be able to select the execution of B or C based on the value of A, there's a workaround. By quoting B and C, you stop them from being executed. After the if command chooses between B (then) and C (else) based on A, it removes the surrounding quoting markers, if any, executing the proper command. However, if B and C contain only text and not macros, they do not need to be quoted. Here's an example:

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

As we stated before, this is not going to choose whether or not to execute the append command. 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!.}:} .}

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

Normally you would have to remove the markers yourself, by using macro dequote. But some macros (like if) have this special behavior, for your convenience. The special macros with such behavior are: if, set, for, for each, switch and breadcrumbs. These allow you to use variables to change output.

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