vlibTemplate

vLib Logo

5.2. <TMPL_LOOP name='LOOP_NAME'>

There are 3 ways of assigning a vlibTemplate loop in PHP. The first way is the most complicated using the function setLoop().
This will be described first, and then the more recent methods, the 3 stage method and the Db result method.
All methods use 'exactly' the same template tags. They're just programmed differently in PHP.


The <TMPL_LOOP> tag is a bit more complicated. The <TMPL_LOOP> tag allows you to delimit a section of text and give it a name. Inside the <TMPL_LOOP> you place <TMPL_VAR>s.
Now you pass an array to setLoop() with a list of variable assignments.
The loop iterates over this list and produces output from the text block for each pass. Here's an example:



Example
   In the template:



   <TMPL_LOOP NAME='EMPLOYEE_INFO'>

         Name: <TMPL_VAR NAME='NAME'>

         Job: <TMPL_VAR NAME='JOB'>

   </TMPL_LOOP>



   In the script:

   $employee_array = array();

   array_push ($employee_arr, array('NAME' => 'Sam', 'JOB' => 'programmer' ));

   array_push ($employee_arr, array('NAME' => 'Steve', 'JOB' => 'designer' ));



   $tmpl->setLoop('EMPLOYEE_INFO', $employee_array);

   $tmpl->pparse();



   The output:

   Name: Sam
   Job: programmer

   Name: Steve
   Job: designer


As you can see above the <TMPL_LOOP> takes a list of variable assignments and then iterates over the loop body producing output.

Often you'll want to generate a <TMPL_LOOP>'s contents programmatically. Here's an example of how this can be done (many other ways are possible!):



Example
   // a couple of arrays of data to put in a loop:

   $words = array('I', 'Am', 'Cool');

   $numbers = array(1, 2, 3);



   $loop_data = array();  // initialize an array to hold your loop



   for ($i=0; $i < count($words); $i++) {

     array_push($loop_data, array('

                                 'WORD' => $words[$i],

                                 'NUMBER' => $numbers[$i]

                                ));

   }



   // finally, assign the loop data to the loop variable

   $template->setLoop('THIS_LOOP', $loop_data);


The above example would work with a template like:



Example
   <TMPL_LOOP NAME="THIS_LOOP">

      Word: <TMPL_VAR NAME="WORD"><BR>

      Number: <TMPL_VAR NAME="NUMBER"><BR>

   </TMPL_LOOP>


It would produce output like:



Example
   Word: I

   Number: 1



   Word: Am

   Number: 2



   Word: Cool

   Number: 3


<TMPL_LOOP>s within <TMPL_LOOP>s are fine and work as you would expect. If the syntax for the setLoop() call has you stumped, here's an example of a setLoop() call with one nested loop:



Example
  $template->setLoop('OUTER',array(

            0 => array(

                'name' => 'Steve',

                'surname' => 'Owen'

                'owns' => array(

                            0 => array(

                                    'est' => 'E20'),

                            1 => array(

                                    'est' => 'Flat 42B')

                            ),

            1 => array(

                'name' => 'Phil',

                'surname' => 'Mitchel'

                'owns' => array(

                            0 => array(

                                    'est' => 'The Vic'),

                                            1 => array(

                                    'est' => 'The Arches'),

                            2 => array(

                                    'est' => 'Snooker Club')

                            )

                 );


Basically, the loop must consist of an array where each array row represents a row of a loop. Therefore the values of each array must be an associative array of.. $variable_name => $variable_value.
If you build an inner loop, the $variable_name becomes the name of the loop, and you start again with the same structure.

NB: There is no limit to the amount of nested loops. Be aware that many loops (as in any php code), may slow down performance.

Inside a <TMPL_LOOP>, the only variables available are those defined within the setLoop() call. There are however work arounds to getting variables outside of the scope of the current loop.
If you wish to access a variable in a parent loop, you can prepend the variable name with the name of the loop, i.e.:



Example
  <TMPL_LOOP name="outer">
      <TMPL_VAR name="__ROWNUM__">

      <TMPL_LOOP name="inner">
          Inner loop row number is: <TMPL_VAR name="__ROWNUM__">,
          the outer loop row number is: <TMPL_VAR name="outer.__ROWNUM__">
      </TMPL_LOOP>
  </TMPL_LOOP>


To access the variables within the global namespace, you can either set the OPTION 'GLOBAL_VARS' to 1, or you can use the above syntax but use the vlibTemplate reserved word 'global' (always lowercase) like <TMPL_VAR name="global.TITLE">.

NB: '__ROWNUM__' is one of many vlibTemplate variables which is set when the OPTION 'LOOP_CONTEXT_VARS' is set to 1. See the OPTIONS section to see other variable and their meanings.


The second method for adding loops is the 3 stage method, a later addition to the class, using newLoop(), addRow() and addLoop() functions.
It uses the same template as before but the PHP side is much more simple.



Example
<?php
    [assign template .......]

   // a couple of arrays of data to put in a loop:

   $words = array('I', 'Am', 'Cool');

   $numbers = array(1, 2, 3);



   $tmpl->newLoop('THIS_LOOP');  // initialize a new loop


   for ($i=0; $i < count($words); $i++) {

     $tmpl->addRow(array('WORD' => $words[$i],'NUMBER' => $numbers[$i])); //adds a row

   }

   $tmpl->addLoop(); // adds the loop to the template

    [parse template .....]
?>


To see a working example have a look at the 'vlibTemplate_basicloop.php' example in the EXAMPLES folder of your vLIB distribution.


The third method for adding loops is an experimental function which takes the result resource of a database call, and generates the output. The PHP-side is even simpler than the 3 stage method. Here's an example:



Example
<?php
    [assign template .......]
   $cnx = mysql_connect('localhost','user','pass');
   mysql_select_db('test');

   $r = mysql_query('SELECT * FROM test_table LIMIT 0, 50', $cnx);


   $tmpl->setDbLoop('THIS_LOOP', $r, 'MYSQL');  // initialize a new loop


    [parse template .....]
?>


How simple was that!