====== List Tag ======

===== Description =====

Allows "loops" in the template to be defined, as might be required when display the contents of the database query result, row by row. For example a list of user names;

<code xml>
<list:list id="Users">
  <table>
      <tr>
        <th>Username</th>
        <th>Email</th>
        <th>Full Name</th>
      </tr>
    <list:item>
      <tr>
        <td>{$Username}</td>
        <td>{$Email}</td>
        <td>{$Fullname}</td>
      </tr>
    </list:item>
  </table>
</list:list>
</code>

You can use the [[tag:list:default|list:default]] to contain some default content, should there be no data to iterate over in the list:

<code xml>
<list:list id="Users">
  <ul>
   <list:item><li>{$Username} ($Email)</li></list:item>
   <list:default><li>No currently active users</li></list:default>
  </ul>
</list:list>
</code>

The 'code behind' which populates these template fragments with data might look like:
<code php>
require 'framework/common.inc.php';
require WACT_ROOT . '/template/template.inc.php';

define('DB_DATABASE', 'wack');
define('DB_HOST', 'localhost');
define('DB_USER', 'wack');
define('DB_PASSWORD', 'wacky');

// Make MySqlRecordSet et al. available
require WACT_ROOT . '/db/mysql.inc.php';

// Load the template
$Page =& new Template('/users.html');

// Find the runtime component
$UserList =& $Page->findChild('Users');

// Get the users record set
$UserSet = & NewRecordSet('SELECT * FROM users')

// Register the record set as the data source for the runtime component
$UserList->registerDataSet($UserSet);

// Display the page
$Page->display();
</code>

The list tag might form the basis for building more complex components which simplify the construction of HTML, for example a ''<calendar:Calendar/>'' tag which significantly reduces the amount of HTML required for constructing a calendar.

===== Set A List From a Data Set =====
A List can be populated directly from a data set using the ''from'' attribute.

<code xml>
<list:list from="Users">
  <ul>
   <list:item><li>{$Firstname} {$Lastname}</li></list:item>
  </ul>
</list:list>
</code>
<code php>
$Page->set('Users', $UserSet);
</code>

When is this "pull"-assignment preferable to registerDataSet() as shown above?  The from attribute syntax helps eliminate a couple of lines of code from the view and for simple views can allow you to use a standard view instead of a custom view class.