Preparing for ccHost 5.0 - Revision history

Fourstones at 19:38, 25 September 2007

2007-09-25T19:38:17Z

Fourstones: /* Double Indirection */

2007-09-25T19:19:01Z

‎Double Indirection

Fourstones: /* Double Indirection*/

2007-09-25T19:11:10Z

‎Double Indirection

Fourstones: /* Change list */

2007-09-24T16:38:20Z

‎Change list

Fourstones: /* Change list */

2007-09-24T16:27:45Z

‎Change list

Show changes

Fourstones: New page: 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. Ear...

2007-09-24T16:20:54Z

New page: 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. Ear...

New page

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 translate the templates to PHP modules suitable for 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 '>' allowed in define clause
<tal:block define="R php: array( 'cart_id' => 1 );" />
becomes:
<tal:block define="R php: array_combine( array('cart_id'), array( 1 ) );" />

* templates should have tal:block outer-most tags, nothing that outputs HTML (e.g. <div>)

* no duplicate metal macros in the same xml template file

* no parse-able HTML tags within javascript tags
<script>
var t = '<div>hello</div>';
</script>

must be re-written:
<script>
var t = '<' + 'div>hello<' + '/div>';
</script>

* variables won't expand properly in script attributes, move them to script blocks

<select onchange="cc_get_obj('${home-url}');" >

re-written as:

<script>
function do_change(obj) {
cc_get_obj('${home-url}');
}
</script>
<select onchange="do_change(this);" >

* simple '$' variable won't expand properly in normal attributes, use ${} format

<a href="$home-url"

becomes

<a href="${home-url}"

* get rid of redundant tal: prefixes on attributes (should have been done anyway)

<tal:block tal:repeat="r records"

should be

<tal:block repeat="r records"

* repeat/* syntax will not work across macro calls. This scenario won't work anymore:

<metal:block define-macro="foo">
<tal:block repeat="r records">
<metal:block use-macro="bar" />
</tal:block>
</metal:block>

<metal:block define-macro="bar">
<tal:block condition="repeat/r/last">
last one!
</tal:block>
</metal:block>

But there is a simple work around, pass the condition as a define:

<metal:block define-macro="foo">
<tal:block repeat="r records">
<tal:block define="is_last repeat/r/last" />
<metal:block use-macro="bar" />
</tal:block>
</metal:block>

<metal:block define-macro="bar">
<tal:block condition="is_last">
last one!
</tal:block>
</metal:block>

* General note: 'php:' works better than 'string:'. What was:

<tal:block define="foo string: ${bar} ${baz}" />

Seems to be happier when it's

<tal:block define="foo php: ${bar} . ' ' . ${baz}" />

Another example:

<tal:block define="K string:tags$repeat/R/key$repeat/C/key" />

The above will not compile without some help like below:

<tal:block define="K php: 'tags' . ${repeat/R/key} . ${repeat/C/key}" />

* How to do variable array indexing. This was crazy to try in the first place but here it was:

<tal:block define="thiskey repeat/item/key" />
<tal:block define="avalue some_array/$thiskey" />

Note the '$' in the second line. The only way I could keep this functionality and come up with syntax that would work in bothPHPTAL and the new system was to create a helper function in PHP. So the second line above is replaced with:

<tal:block define="avalue php: cc_get_value( ${some_array}, ${thiskey}) />

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

if( !function_exists("cc_get_value") ) {
function cc_get_value($arr,$key) {
return is_array($arr) && array_key_exists($key,$arr) ? $arr[$key] : null;
} }

* Qualify macro source files when calling macros by name. PHPTAL has a more sophisticated lookup algorithm so:

<metal:block use-macro="some_macro" />

would "do the right thing" and look in the current XML file. The new runtime needs more help.

<metal:block use-macro="some_file.xml/some_macro" />

@@ Line 155: / Line 155: @@
       &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 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:
+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;
@@ Line 161: / Line 161: @@
       &lt;metal:block use-macro="${bvalue}" /&gt;
 </pre>
-The runtime will try to locate a macro called 'avalue', if not found it assumes 'avalue' is an variable name and look it up and find 'foo.xml/foo'
+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 ====

@@ Line 136: / Line 136: @@
       &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 bothPHPTAL and the new system was to create a helper function in PHP. So the second line above is replaced with:
+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;
+      &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
@@ Line 147: / Line 147: @@
       } }
 </pre>
 ==== Qualified Macro Names ====

@@ Line 17: / Line 17: @@
 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
+==== no '&gt;' allowed in define clause ====
 <pre>
    &lt;tal:block define="R php: array( 'cart_id' =&gt; 1 );" /&gt;
@@ Line 26: / Line 26: @@
 </pre>
-* templates should have tal:block outer-most tags, nothing that outputs HTML (e.g. &lt;div&gt;)
+==== Outer tags should be tal ====
-* no duplicate metal macros in the same xml template file
+==== Duplicate Macro Names ====
-* no parse-able HTML tags within javascript tags
+==== No HTML tags in Javascript ====
 <pre>
      &lt;script&gt;
@@ Line 43: / Line 46: @@
 </pre>
-* variables won't expand properly in script attributes, move them to script blocks
+==== No Variables in 'On' Handlers ====
 <pre>
      &lt;select onchange="cc_get_obj('${home-url}');" &gt;
@@ Line 57: / Line 61: @@
 </pre>
-* simple '$' variable won't expand properly in normal attributes, use ${} format
+==== Use Curlys for All Variables ====
 <pre>
      &lt;a href="$home-url"
@@ Line 66: / Line 71: @@
 </pre>
-* get rid of redundant tal: prefixes on attributes (should have been done anyway)
+==== Trim Excess tal: Prefixes ====
 <pre>
      &lt;tal:block tal:repeat="r records"
@@ Line 75: / Line 81: @@
 </pre>
-* repeat/* syntax will not work across macro calls. This scenario won't work anymore:
+==== repeat/* Variables Are Local Only ====
 <pre>
      &lt;metal:block define-macro="foo"&gt;
@@ Line 105: / Line 112: @@
 </pre>
-* General note: 'php:' works better than 'string:'. What was:
+==== php: Preferred Over string: ====
 <pre>
         &lt;tal:block define="foo string: ${bar} ${baz}" /&gt;
@@ Line 117: / Line 125: @@
         &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:
+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>
-* How to do variable array indexing. This was crazy to try in the first place but here it was:
+==== Variable Indexing ====
 <pre>
       &lt;tal:block define="thiskey repeat/item/key" /&gt;
@@ Line 139: / Line 148: @@
 </pre>
+==== Qualified Macro Names ====
-* Qualify macro source files when calling macros by name. PHPTAL has a more sophisticated lookup algorithm so:
+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;

@@ Line 1: / Line 1: @@
 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 translate the templates to PHP modules suitable for ccHost.
+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? ==