Request for comments - nested sections/looping/padding

I've been thinking a lot about nested sections/looping/repeating values.
Here's what I came up with.

* I'm not sure 'repeat' is a good name. I think 'pad' would be better.

* 'pad' would have one of three values:
    * 'none'    - means stop looping when the variable with the minimum number
                  of values is done
    * 'default' - pad with the default value, or empty string if default is
                  not specified
    * 'last'    - pad with the last value of the variable (or the only value
                  if it's not an array)

    By default, I think, 'pad' should be 'default' for arrays, and 'last'
    for variables with single value. Some examples:

    1. Let's say we have $color = array("red", "green", "blue"), and $size =
    array("large", "small"). If we have this template piece:

    {{section}}
        {{ $color }} - {{ $size }}
    {{/section}}

    Then by default it will output:
        
        red   - large
        green - small
        blue  -
        
    If we use {{ $size default="none" }}, then we'd have:

        red   - large
        green - small
        blue  - none

    If we use {{ $size pad=none }}, we'd have:

        red   - large
        green - small

    2. Let's say we have $domain = "php.net", $name = array("joe",
    "andrei").

    {{section}}
        {{ $name }}@{{ $domain }}
    {{/section}}

    Then by default it will output:
        
        [email protected]
        [email protected]
    
    If we use {{ $size pad=last }}, we'd have:

        [email protected]
        andrei@
    
* Imagine this scenario:

    {{section category}}
        Category: {{ $catname }}
        {{section article}}
            {{ $headline }} - {{ $date }}
        {{/section article}}
    {{/section category}}

    What we want to do here is display a list of categories, and for each
    category, display the list of headlines and dates in it. So, we'll have
    to assign the data like this:

    tmpl_assign($id, "catname", array("Sports", "News"));
    tmpl_assign($id, "headline", array("Sports Headline 1"),
                                 array("News Headline 1", "News Headline 2"));
    tmpl_assign($id, "date", array("02/20/00", array("02/21/00", "02/23/00"));

    Or if you are receiving data incrementally, you'd use tmpl_add_value(),
    assuming $sql->record["headline"] contains all the headlines for a
    category, and so on:

    while ($sql->next()) {
        tmpl_add_value($id, "catname", $sql->record["Category"]);
        tmpl_add_value($id, "headline", $sql->record["headline"]);
        tmpl_add_value($id, "date", $sql->record["date"]);
    }

    Is this clear?

    Basically, after the section loops through one set of values, it
    increments internal pointer so that the next time 'article' section is
    entered into, it will loop through the next set of values.

* You can refer to the current value of variable as it exists in another
  section using $<section name>/<var name>, e.g. $category/catname

* The variables in outer sections are visible to inner ones, e.g.
  $category/catname, but outer sections cannot look inside inner ones, e.g.
  $article/headline will give you nothing when used outside the 'article'
  section. But it might be useful to do #article/TOTAL to get the total
  number of headlines/dates that were printed. We'll have to think more
  about what happens when you refer to $article/headline from outside.

* Imagine that we want to print the categories and articles like this:

    News        News Headline 1     02/21/00
                News Headline 2     02/23/00
    Sports      Sports Headline 1   02/20/00

  Now, how would you do this? Each row would have to be printed in the
  'article' section, but we need to loop through $catname too, getting each
  next value only when the 'article' section looping is done. I think we can
  do it like this:

    {{section category}}
        {{section article}}
        Category: {{ $category/catname pad=default }} {{ $headline }} {{ $date }}
        {{/section article}}
    {{/section category}}

  So, even though $catname is not seen in 'category' section, it is assigned
  to it by virtue of having been mentioned as $category/catname. Thus on the
  first iteration of the 'article' loop, we'll print:

    News        News Headline 1     02/21/00

  Then, since pad=default and $category/catname has only a single value,
  we're going to output default (which is empty here) and we'd have:

                News Headline 2     02/23/00

  Now, 'article' looping is done and it will increment internal pointer to
  go to the next set of values. 'category' looping is also done, so it's
  going to go to 'Sports' now, and the next printed thing will be:

    Sports      Sports Headline 1   02/20/00

  And we have our desired result.


I think the basic ideas are good and pretty flexible, we might want to come
up with really good names for attributes and values so that the designer is
not too confused.  I'm not sure about 'pad', 'default', 'last', etc.

-Andrei

"The galaxy is, in other words, an immensely, intrinsically,
and inexhaustibly interesting place." -- Iain M. Banks