Help for editing skin templates

[KT Walrus]

I've searched around and haven't found any help on editing skin templates. If I've missed it, please give the link.

Otherwise, please make documenting skin templates a priority. I don't quite understand what all the possible control tags do or what the allowed syntax is for them. I've been making my edits by just following the existing templates. For example, I'm not quite sure what the (possibly optional?) arguments to the "<if test=" where there seems to be an optional id followed by a ':|:' followed by what appears to be a php expression. What is the significance of the optional id? I'm assuming it might hold the value of the test so it can be used later in the template, but what is the expression to test this id later (if that is the case).

I also see things like "parse" that need to be inside braces. What are all these possible outside HTML commands that can be given in between the braces?

I'm pretty sure this has to be documented somewhere, but you have made it very hard to find. When I enabled the Page Help, all I got was a "NEW:core_templates___ There was no page found." so that didn't help much.

[KT Walrus]

After searching the source files, I found the briefest documentation possible in the file in "admin/sources/template_plugins":

[*]{parse addtohead="{$this->settings[\'public_dir\']}js/myJS.js" type="javascript"}[*]{parse date="now" format="long" relative="false"}[*]{parse expression="intval($data)"}[*]{parse format_number="123456"}[*]{parse include="/path/to/file"}[*]{parse js_module="name_of_module"}[*]{parse replacement="a_post"}[*]{parse striping="someKey" classes="row1, row2"}[*]{parse template="myTemplate" group="global" params="$data, $moreData"}[*]{parse url="this=that" base="public"}[*]{parse variable="testKey" default="foo" oncondition="$data == \'new\'" value="bar"}

Anyway, now, I need to find a list of the extra tags like "<if" "<foreach" etc that are allowed and maybe some more documentation than one line examples.

Finding documentation is a very frustrating task.

At least I now know what can go between those braces although I could use some words as to exactly what each plugin actually does. Like, if I addtohead, where does the javascript go? Does it go above the other javascript or after? I have coded some jQuery scripts that need to go before Prototype or they won't work in IE (some sort of weird conflict).

[Josh]

We're working on the documentation. The optional id that can precede either <if or <foreach statements are hook locations, if you specify the id then it becomes a hook point that plugins can use.

[KT Walrus]

[quote name='Josh' date='25 September 2009 - 04:10 PM' timestamp='1253909423' post='1861062']
We're working on the documentation. The optional id that can precede either <if or <foreach statements are hook locations, if you specify the id then it becomes a hook point that plugins can use.


Thanks for that. I was thinking the id was a condition variable that could be later tested by another if statement and not have to repeat the same expression again. Boy was I wrong. I didn't even think about hooks.

What are the other extra statements like <if and <foreach? Is there <while and <switch and other php control statements?

[bfarber]

The only other pseudo html tag is <php> which allows you to execute raw PHP code. e.g.

<php>print "Hello World";</php>

Be aware though - code inside <php></php> tags is put at the very beginning of the skin template (NOT necessarily where you put it within the template itself when editing the template), which can affect your PHP code. For instance, this wouldn't work

<foreach loop="$variable as $var"> {$var}<br /> </foreach>

$variable will be a localized variable in this case (scope) while foreach loops actually generate functions in the compiled php template file, and $variable won't be set there.

<div>Some text

<php>$variable = array( 1, 2 );</php>

[KT Walrus]

[quote name='bfarber' date='25 September 2009 - 05:52 PM' timestamp='1253915552' post='1861101']
Be aware though - code inside <php></php> tags is put at the very beginning of the skin template (NOT necessarily where you put it within the template itself when editing the template), which can affect your PHP code.


I discovered this before you posted when I tried to implement an indent var surrounding a recursive parse template call. I tried incrementing the variable before the call and decrementing it after the call, but the cached skin just put the increment and decrement at the top of the function resulting in no change.

It would be nice if php were evaluated in place (in an out of line function just like the foreach generates) so it would be more intuitive.

I ended up adding an indent var as a parameter to the recursive function and just incrementing the indent var on the call. A better solution in this case.

Why isn't <php> implemented like the <foreach> out of line functions?

BTW, I was using a global in my <php> (e.g., $this->settings['my_indent']) so the scoping problems of local variables isn't affected by the out of line functions.

[KT Walrus]

One more thing... If the code inside the <php> were put in a function that was called in the position of the <php>, we could use the return statement to return HTML to be embedded inline.

This would be much more convenient as we could use switch statement to choose a number of different HTML strings based on some variable. This is often much cleaner than doing cascading <if>s and much more flexible.

Maybe you didn't do this because you were concerned about <php> inserting malicious unsecure HTML onto the page?

[bfarber]

I have no idea, really. It was done probably in the easiest and most reliable fashion. The skin template parsing engine uses a whole bunch of voodoo magic to get it running as reliably as it runs. ;)

Joking aside, I don't know why it's not executed in place, and I don't know that this will change. Probably because the most common use/need is to set a quick variable that you will use within the same template bit, and by calling a separate function you can't (as easily) do that.