Difference between revisions of "Preparing for ccHost 5.0"

From Creative Commons
Jump to: navigation, search
(Change list)
m
 
(3 intermediate revisions by the same user not shown)
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.
 
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? ==
 
== How does affect you? ==
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.
 
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
+
==== no '>' allowed in define clause ====
 
<pre>
 
<pre>
 
   &lt;tal:block define="R php: array( 'cart_id' =&gt; 1 );" /&gt;
 
   &lt;tal:block define="R php: array( 'cart_id' =&gt; 1 );" /&gt;
Line 26: Line 26:
 
</pre>
 
</pre>
  
* templates should have tal:block outer-most tags, nothing that outputs HTML (e.g. &lt;div&gt;)
+
==== Outer tags should be tal ====
 +
Templates should have tal:block outer-most tags, nothing that outputs HTML (e.g. &lt;div&gt;)
  
* no duplicate metal macros in the same xml template file
+
==== 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 parse-able HTML tags within javascript tags
+
==== No HTML tags in Javascript ====
 +
No parse-able HTML tags within javascript tags
 
<pre>
 
<pre>
 
     &lt;script&gt;
 
     &lt;script&gt;
Line 43: Line 46:
 
</pre>
 
</pre>
  
* variables won't expand properly in script attributes, move them to script blocks
+
==== No Variables in 'On' Handlers ====
 +
Variables won't expand properly in script attributes, move them to script blocks
 
<pre>
 
<pre>
 
     &lt;select onchange="cc_get_obj('${home-url}');" &gt;
 
     &lt;select onchange="cc_get_obj('${home-url}');" &gt;
Line 57: Line 61:
 
</pre>
 
</pre>
  
* simple '$' variable won't expand properly in normal attributes, use ${} format
+
==== Use Curlys for All Variables ====
 +
Simple '$' variable won't expand properly in normal attributes, use ${} format
 
<pre>
 
<pre>
 
     &lt;a href="$home-url"
 
     &lt;a href="$home-url"
Line 66: Line 71:
 
</pre>
 
</pre>
  
* get rid of redundant tal: prefixes on attributes (should have been done anyway)
+
==== Trim Excess tal: Prefixes ====
 +
Get rid of redundant tal: prefixes on attributes (should have been done anyway)
 
<pre>
 
<pre>
 
     &lt;tal:block tal:repeat="r records"
 
     &lt;tal:block tal:repeat="r records"
Line 75: Line 81:
 
</pre>
 
</pre>
  
* repeat/* syntax will not work across macro calls. This scenario won't work anymore:
+
==== 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>
 
<pre>
 
     &lt;metal:block define-macro="foo"&gt;
 
     &lt;metal:block define-macro="foo"&gt;
Line 105: Line 112:
 
</pre>
 
</pre>
  
* General note: 'php:' works better than 'string:'. What was:
+
==== php: Preferred Over string: ====
 +
Just a general note: 'php:' works better than 'string:'. What was:
 
<pre>
 
<pre>
 
       &lt;tal:block define="foo string: ${bar} ${baz}" /&gt;
 
       &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;
 
       &lt;tal:block define="K string:tags$repeat/R/key$repeat/C/key" /&gt;
 
</pre>
 
</pre>
    The above will not compile without some help like below:
+
The above will not compile without some help like below:
 
<pre>
 
<pre>
 
       &lt;tal:block define="K php: 'tags' . ${repeat/R/key} . ${repeat/C/key}" /&gt;
 
       &lt;tal:block define="K php: 'tags' . ${repeat/R/key} . ${repeat/C/key}" /&gt;
 
</pre>
 
</pre>
  
* How to do variable array indexing. This was crazy to try in the first place but here it was:
+
==== 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>
 
<pre>
 
     &lt;tal:block define="thiskey repeat/item/key" /&gt;
 
     &lt;tal:block define="thiskey repeat/item/key" /&gt;
 
     &lt;tal:block define="avalue  some_array/$thiskey" /&gt;
 
     &lt;tal:block define="avalue  some_array/$thiskey" /&gt;
 
</pre>
 
</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>
 
<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>
 
</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
 
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 139: Line 148:
 
</pre>
 
</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'
  
* Qualify macro source files when calling macros by name. PHPTAL has a more sophisticated lookup algorithm so:
+
==== Qualified Macro Names ====
 +
Qualify macro source files when calling macros by name. PHPTAL has a more sophisticated lookup algorithm so:
 
<pre>
 
<pre>
 
     &lt;metal:block use-macro="some_macro" /&gt;
 
     &lt;metal:block use-macro="some_macro" /&gt;

Latest revision as of 19:38, 25 September 2007

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?

  1. If you do not have custom PHPTAL XML templates then the transition will happen behind the scenes during the upgrade.
  2. 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.
  3. 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 ) );" />

Outer tags should be tal

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

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

    <script>
        var t = '<div>hello</div>';
    </script>

must be re-written:

     <script>
        var t = '<' + 'div>hello<' + '/div>';
     </script>

No Variables in 'On' Handlers

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);" >

Use Curlys for All Variables

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

    <a href="$home-url"

becomes

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

Trim Excess tal: Prefixes

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/* 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:

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

php: Preferred Over string:

Just a 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}" />

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.

     <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 both PHPTAL 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;
     } }

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:

     <tal:block define="avalue  string:foo" />
     <tal:block define="bvalue  string:avalue" />
     <span tal:content="${bvalue}" />

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:

     <tal:block define="avalue  string:foo.xml/foo" />
     <tal:block define="bvalue  string:avalue" />
     <metal:block use-macro="${bvalue}" />

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:

     <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" />