HFS: Template macros: Difference between revisions

From rejetto wiki
Jump to navigation Jump to search
m (→‎Full list: typo)
(→‎Full list: resorting)
Line 32: Line 32:
== Full list ==
== Full list ==
With letters we are denoting parameters, and their meaning is explained immediately after.
With letters we are denoting parameters, and their meaning is explained immediately after.
=== Logic ===
; if | A | B | C
; if | A | B | C
: if A is true, then it expands to B, else it expands to C. When it expands to B, C is just discarded, and the vice versa. C is optional.
: if A is true, then it expands to B, else it expands to C. When it expands to B, C is just discarded, and the vice versa. C is optional.
: How you tell A is true? A is true if it is not empty and not just a zero. So if A is "hi there!", then it is true.
: How you tell A is true? A is true if it is not empty and not just a zero. So if A is "hi there!", then it is true.
; if not | A | B | C : same as ''if'', but the logic is inverted. When A is true it expands to C and vice versa.
; if not | A | B | C : same as ''if'', but the logic is inverted. When A is true it expands to C and vice versa.
; get | A
: where A is the name of a value you are interested in, like to know if an option is enabled or not.
: This is a list of supported values for A:
:; can upload : true if in the current folder the user is allowed to upload files
:; can recur : true if the option ''Recursive listing'' is enabled
:; can archive : true if the current folder is archivable
; not | A : true if A is not true
; not | A : true if A is not true
; and | A | B : true if both A and B are true
; and | A | B : true if both A and B are true
; or | A | B : true if any of A or B are true
; or | A | B : true if any of A or B are true
; xor | A | B : true if A is true while B is false, or the opposite
; xor | A | B : true if A is true while B is false, or the opposite
; urlvar | A : url variable. Let's say in the url you see <tt>?sort=s</tt> and you want to know that '''s''', just use the macro urlvar|sort.
; header | A : get any value from the HTTP request header. A is the name of the header field. This is something mostly for techies. Don't fret if you don't even know what the header is.
; load | A : you'll love this one. You can specify A as a file name, or as a URL. It will load and expand to it. The file or URL you specify must be accessible from the server machine. A can be <tt>C:\windows\win.ini</tt> or also <tt><nowiki>http://another_hfs_in_lan/the_file_i_want.txt</nowiki></tt>.
; comment | A : this is just discarded. It's for your convenience, to put a comment in the template. HTML comments are readable by visitors if they use ''show html source'' in their browser. Using this macro you will have comments that will never leave your server.
; substring | A | B | C : cut C from A to B, with B not included. Example: <tt><nowiki>{{substring|(|belong|you (are) belong to us}}</nowiki></tt> will be <tt>(are)</tt>.
: If A is not specified, C is taken from the start. If B is not specified, C is taken to the end.
; switch | A | B | C | D | E | F ...
; switch | A | B | C | D | E | F ...
: this is rather complex for non-programmers. You can learn how a switch statement is supposed to work [http://en.wikipedia.org/wiki/Switch_statement#Examples from Wikipedia]. When you know how a ''switch'' works, then you will understand this schema that will make you understand how the parameters of this macro work
: this is rather complex for non-programmers. You can learn how a switch statement is supposed to work [http://en.wikipedia.org/wiki/Switch_statement#Examples from Wikipedia]. When you know how a ''switch'' works, then you will understand this schema that will make you understand how the parameters of this macro work
Line 74: Line 63:
}}
}}
</nowiki></pre>
</nowiki></pre>
=== Data getting ===
; get | A
: where A is the name of a value you are interested in, like to know if an option is enabled or not.
: This is a list of supported values for A:
:; can upload : true if in the current folder the user is allowed to upload files
:; can recur : true if the option ''Recursive listing'' is enabled
:; can archive : true if the current folder is archivable
; urlvar | A : url variable. Let's say in the url you see <tt>?sort=s</tt> and you want to know that '''s''', just use the macro urlvar|sort.
; header | A : get any value from the HTTP request header. A is the name of the header field. This is something mostly for techies. Don't fret if you don't even know what the header is.
; load | A : you'll love this one. You can specify A as a file name, or as a URL. It will load and expand to it. The file or URL you specify must be accessible from the server machine. A can be <tt>C:\windows\win.ini</tt> or also <tt><nowiki>http://another_hfs_in_lan/the_file_i_want.txt</nowiki></tt>.
=== Data manipulation ===
; substring | A | B | C : cut C from A to B, with B not included. Example: <tt><nowiki>{{substring|(|belong|you (are) belong to us}}</nowiki></tt> will be <tt>(are)</tt>.
: If A is not specified, C is taken from the start. If B is not specified, C is taken to the end.
=== Others ===
; comment | A : this is just discarded. It's for your convenience, to put a comment in the template. HTML comments are readable by visitors if they use ''show html source'' in their browser. Using this macro you will have comments that will never leave your server.

Revision as of 03:15, 29 November 2007

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

How macros work

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 {{double braces}}.

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

(Case sensitive: [style]<>[STYLE] )

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

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.

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 {{quote followed by a space, and all the text you want. To close the quoting you type quote}} . You can consider quote a special macro with no parameters.

Full list

With letters we are denoting parameters, and their meaning is explained immediately after.

Logic

if | A | B | C
if A is true, then it expands to B, else it expands to C. When it expands to B, C is just discarded, and the vice versa. C is optional.
How you tell A is true? A is true if it is not empty and not just a zero. So if A is "hi there!", then it is true.
if not | A | B | C
same as if, but the logic is inverted. When A is true it expands to C and vice versa.
not | A
true if A is not true
and | A | B
true if both A and B are true
or | A | B
true if any of A or B are true
xor | A | B
true if A is true while B is false, or the opposite
switch | A | B | C | D | E | F ...
this is rather complex for non-programmers. You can learn how a switch statement is supposed to work from Wikipedia. When you know how a switch works, then you will understand this schema that will make you understand how the parameters of this macro work
switch(A) {
  case C: return D;
  case E: return F;
  ...
}
The B is a separator string for C. Let's be clearer: if you want to specify several cases in C, all of them returning D, then you can specify them separating with B.
As you can see C and D are paired, as E and F, eventually G and H, and so on. If at the end of this list of pairs, a single unpaired parameter is found, then it is used as the else/default case, when all other pairs have failed.
Let me translated the first example of Wikipedia using the macro
{{switch|%n%|,|
  0|you typed zero|
  3,5,7|%n% is a prime number|
  4,6,8|%n% is an even number|
  2|%n% is a prime and even number|
  1,9|%n% is a perfect square|
  Only single-digit numbers are allowed
}}

Data getting

get | A
where A is the name of a value you are interested in, like to know if an option is enabled or not.
This is a list of supported values for A:
can upload
true if in the current folder the user is allowed to upload files
can recur
true if the option Recursive listing is enabled
can archive
true if the current folder is archivable
urlvar | A
url variable. Let's say in the url you see ?sort=s and you want to know that s, just use the macro urlvar|sort.
header | A
get any value from the HTTP request header. A is the name of the header field. This is something mostly for techies. Don't fret if you don't even know what the header is.
load | A
you'll love this one. You can specify A as a file name, or as a URL. It will load and expand to it. The file or URL you specify must be accessible from the server machine. A can be C:\windows\win.ini or also http://another_hfs_in_lan/the_file_i_want.txt.

Data manipulation

substring | A | B | C
cut C from A to B, with B not included. Example: {{substring|(|belong|you (are) belong to us}} will be (are).
If A is not specified, C is taken from the start. If B is not specified, C is taken to the end.

Others

comment | A
this is just discarded. It's for your convenience, to put a comment in the template. HTML comments are readable by visitors if they use show html source in their browser. Using this macro you will have comments that will never leave your server.