View source for Preparing for ccHost 5.0

In ccHost 5.0 we are abandoning the PHPTAL template engine. We are replacing it with no real template engine. The HTML pages and XML feeds will be rendered using "straight" PHP files. Early testing shows that removing PHPTAL from our runtime improves both memory and page rendering quite dramatically - half the memory and twice the speed to render each page. PHPTAL was often charging a ccHost over 4MB per page request. The overhead of the new system is approximately 100k.

If you choose, you can continue to use the same subset of the PHPTAL language we've been using for templates during your development and we will provide a tool that will import the templates to ccHost.

== How does affect you? ==

# If you do not have custom PHPTAL XML templates then the transition will happen behind the scenes during the upgrade.
# If you have some custom templates that followed the patterns of the templates in the /cctemplates directory then you will be able perform the upgrade after just a few minor tweaks (perhaps none) to your custom templates.
# If you have made extensive changes and/or have custom PHP code that takes advantage of PHPTAL's more exotic features then you will probably have to do a line by line check. For example:

* In PHPTAL you can pass class objects to a template. In the new system you can not, only arrays.
* The tal:on-error attribute is ignore
* The 'structure' keyword is ignored (everything is output as HTML/XML anyway)

== Change list ==

In any event the actual number of changes required for a smooth transition will be small, the changes themselves are typically adding or removing a few characters and the benefits will be huge. NOTE: All changes asked are compatible with the way we use PHPTAL in ccHost 4.x, so you can start making these tweaks today and they will not affect your current installation.

==== no '&gt;' allowed in define clause ====
<pre>
  &lt;tal:block define="R php: array( 'cart_id' =&gt; 1 );" /&gt;
</pre>
becomes:
<pre>
  &lt;tal:block define="R php: array_combine( array('cart_id'), array( 1 ) );" /&gt;
</pre>

==== Outer tags should be tal ====
Templates should have tal:block outer-most tags, nothing that outputs HTML (e.g. &lt;div&gt;)

==== Duplicate Macro Names ====
No duplicate metal macros in the same xml template file. PHPTAL allows this but only lets you use the last one anyway.

==== No HTML tags in Javascript ====
No parse-able HTML tags within javascript tags
<pre>
    &lt;script&gt;
        var t = '&lt;div&gt;hello&lt;/div&gt;';
    &lt;/script&gt;
</pre>
must be re-written:
<pre>
     &lt;script&gt;
        var t = '&lt;' + 'div&gt;hello&lt;' + '/div&gt;';
     &lt;/script&gt;
</pre>

==== No Variables in 'On' Handlers ====
Variables won't expand properly in script attributes, move them to script blocks
<pre>
    &lt;select onchange="cc_get_obj('${home-url}');" &gt;
</pre>
re-written as:
<pre>
    &lt;script&gt;
       function do_change(obj) {
            cc_get_obj('${home-url}');
       }
    &lt;/script&gt;
    &lt;select onchange="do_change(this);" &gt;
</pre>

==== Use Curlys for All Variables ====
Simple '$' variable won't expand properly in normal attributes, use ${} format
<pre>
    &lt;a href="$home-url"
</pre>
becomes
<pre>
    &lt;a href="${home-url}"
</pre>

==== Trim Excess tal: Prefixes ====
Get rid of redundant tal: prefixes on attributes (should have been done anyway)
<pre>
    &lt;tal:block tal:repeat="r records"
</pre>
should be
<pre>
    &lt;tal:block repeat="r records"
</pre>

==== repeat/* Variables Are Local Only ====
This one is kind of exotic but could apply if you copied code from upload_misc.xml. The repeat/* syntax will not work across macro calls. This scenario won't work anymore:
<pre>
    &lt;metal:block define-macro="foo"&gt;
          &lt;tal:block repeat="r records"&gt;
                 &lt;metal:block use-macro="bar" /&gt;
          &lt;/tal:block&gt;
    &lt;/metal:block&gt;

    &lt;metal:block define-macro="bar"&gt;
          &lt;tal:block condition="repeat/r/last"&gt;
                last one!
          &lt;/tal:block&gt;
    &lt;/metal:block&gt;
</pre>
But there is a simple work around, pass the condition as a define:
<pre>
    &lt;metal:block define-macro="foo"&gt;
          &lt;tal:block repeat="r records"&gt;
                 &lt;tal:block define="is_last repeat/r/last" /&gt;
                 &lt;metal:block use-macro="bar" /&gt;
          &lt;/tal:block&gt;
    &lt;/metal:block&gt;

    &lt;metal:block define-macro="bar"&gt;
          &lt;tal:block condition="is_last"&gt;
                last one!
          &lt;/tal:block&gt;
    &lt;/metal:block&gt;
</pre>

==== php: Preferred Over string: ====
Just a general note: 'php:' works better than 'string:'. What was:
<pre>
       &lt;tal:block define="foo string: ${bar} ${baz}" /&gt;
</pre>
Seems to be happier when it's
<pre>
       &lt;tal:block define="foo php: ${bar} . '  ' . ${baz}" /&gt;
</pre>
Another example:
<pre>
       &lt;tal:block define="K string:tags$repeat/R/key$repeat/C/key" /&gt;
</pre>
The above will not compile without some help like below:
<pre>
       &lt;tal:block define="K php: 'tags' . ${repeat/R/key} . ${repeat/C/key}" /&gt;
</pre>

==== Variable Indexing ====
This one is even more unlikely and bizzare but was used in cctemplates/howididit.xml for indexing into an array using a variable.
<pre>
     &lt;tal:block define="thiskey repeat/item/key" /&gt;
     &lt;tal:block define="avalue  some_array/$thiskey" /&gt;
</pre>
Note the '$' in the second line. The only way I could keep this functionality and come up with syntax that would work in both PHPTAL and the new system was to create a helper function in PHP. So the second line above is replaced with:
<pre>
     &lt;tal:block define="avalue  php: cc_get_value( ${some_array}, ${thiskey})" /&gt;
</pre>
NOTE: If you make this change you need to put the following code into a module with a .php extension into your local_files/lib directory
<pre>
    if( !function_exists("cc_get_value") ) {
      function cc_get_value($arr,$key) {
           return is_array($arr) && array_key_exists($key,$arr) ? $arr[$key] : null;
     } }
</pre>

==== Double Indirection ====
In a matter related to the one above, the new system does not know how to look up a variable through another variable. For example:
<pre>
     &lt;tal:block define="avalue  string:foo" /&gt;
     &lt;tal:block define="bvalue  string:avalue" /&gt;
     &lt;span tal:content="${bvalue}" /&gt;
</pre>
PHPTAL will "do the right thing" and display "foo" but the new system will display the string 'avalue'. The only place this is an issue in ccHost 4.x usage of PHPTAL is when calling macros under certain conditions. The 5.0 template runtime is aware of this and will, in fact, try to do the right thing. So in the case of:
<pre>
     &lt;tal:block define="avalue  string:foo.xml/foo" /&gt;
     &lt;tal:block define="bvalue  string:avalue" /&gt;
     &lt;metal:block use-macro="${bvalue}" /&gt;
</pre>
The runtime will notice no file qualifier (see below) on 'avalue' and assumes it is a variable name, look it up and find 'foo.xml/foo'

==== Qualified Macro Names ==== 
Qualify macro source files when calling macros by name. PHPTAL has a more sophisticated lookup algorithm so:
<pre>
     &lt;metal:block use-macro="some_macro" /&gt;
</pre>
would "do the right thing" and look in the current XML file. The new runtime needs more help.
<pre>
     &lt;metal:block use-macro="some_file.xml/some_macro" /&gt;
</pre>