Zope Help

in: Loops over sequences

The in tag gives you powerful controls for looping over sequences and performing batch processing.

Syntax

in tag syntax:

      <dtml-in SequenceVariable|expr="SequenceExpression">
      [<dtml-else>]
      </dtml-in>

The in block is repeated once for each item in the sequence variable or sequence expression. The current item is pushed on to the DTML namespace during each executing of the in block.

If there are no items in the sequence variable or expression, the optional else block is executed.

Attributes

mapping

Iterates over mapping objects rather than instances. This allows values of the mapping objects to be accessed as DTML variables.

no_push_item

Inhibit pushing sequence-item onto the namespace stack.

reverse

Reverses the sequence.

sort=string

Sorts the sequence by the given attribute name.

start=int

The number of the first item to be shown, where items are numbered from 1.

end=int

The number of the last item to be shown, where items are numbered from 1.

size=int

The size of the batch.

skip_unauthorized

Don't raise an exception if an unauthorized item is encountered.

orphan=int

The desired minimum batch size. This controls how sequences are split into batches. If a batch smaller than the orphan size would occur, then no split is performed, and a batch larger than the batch size results.

For example, if the sequence size is 12, the batch size is 10 the orphan size is 3, then the result is one batch with all 12 items since splitting the items into two batches would result in a batch smaller than the orphan size.

The default value is 0.

overlap=int

The number of items to overlap between batches. The default is no overlap.

previous

Iterates once if there is a previous batch. Sets batch variables for previous sequence.

next

Iterates once if there is a next batch. Sets batch variables for the next sequence.

prefix=string

Provide versions of the tag variables that start with this prefix instead of "sequence", and that use underscores () instead of hyphens (-). The prefix must start with a letter and contain only alphanumeric characters and underscores ().

sort_expr=expression

Sorts the sequence by an attribute named by the value of the expression. This allows you to sort on different attributes.

reverse_expr=expression

Reverses the sequence if the expression evaluates to true. This allows you to selectively reverse the sequence.

Tag Variables

Current Item Variables

These variables describe the current item.

sequence-item: The current item.
sequence-key: The current key. When looping over tuples of the form (key,value), the in tag interprets them as (sequence-key, sequence-item).
sequence-index: The index starting with 0 of the current item.
sequence-number: The index starting with 1 of the current item.
sequence-roman: The index in lowercase Roman numerals of the current item.
sequence-Roman: The index in uppercase Roman numerals of the current item.
sequence-letter: The index in lowercase letters of the current item.
sequence-Letter: The index in uppercase letters of the current item.
sequence-start: True if the current item is the first item.
sequence-end: True if the current item is the last item.
sequence-even: True if the index of the current item is even.
sequence-odd: True if the index of the current item is odd.
sequence-length: The length of the sequence.
sequence-var-variable: A variable in the current item. For example, sequence-var-title is the title variable of the current item. Normally you can access these variables directly since the current item is pushed on the DTML namespace. However these variables can be useful when displaying previous and next batch information.
sequence-index-variable: The index of a variable of the current item.

Summary Variables

These variable summarize information about numeric item variables. To use these variable you must loop over objects (like database query results) that have numeric variables.

total-variable: The total of all occurrences of an item variable.
count-variable: The number of occurrences of an item variable.
min-variable: The minimum value of an item variable.
max-variable: The maximum value of an item variable.
mean-variable: The mean value of an item variable.
variance-variable: The variance of an item variable with count-1 degrees of freedom.
variance-n-variable: The variance of an item variable with n degrees of freedom.
standard-deviation-variable: The standard-deviation of an item variable with count-1 degrees of freedom.
standard-deviation-n-variable: The standard-deviation of an item variable with n degrees of freedom.

Grouping Variables

These variables allow you to track changes in current item variables.

first-variable: True if the current item is the first with a particular value for a variable.
last-variable: True if the current item is the last with a particular value for a variable.

Batch Variables

sequence-query: The query string with the start variable removed. You can use this variable to construct links to next and previous batches.
sequence-step-size: The batch size.
previous-sequence: True if the current batch is not the first one. Note, this variable is only true for the first loop iteration.
previous-sequence-start-index: The starting index of the previous batch.
previous-sequence-start-number: The starting number of the previous batch. Note, this is the same as previous-sequence-start-index + 1.
previous-sequence-end-index: The ending index of the previous batch.
previous-sequence-end-number: The ending number of the previous batch. Note, this is the same as previous-sequence-end-index + 1.
previous-sequence-size: The size of the previous batch.
previous-batches: A sequence of mapping objects with information about all previous batches. Each mapping object has these keys batch-start-index, batch-end-index, and batch-size.
next-sequence: True if the current batch is not the last batch. Note, this variable is only true for the last loop iteration.
next-sequence-start-index: The starting index of the next sequence.
next-sequence-start-number: The starting number of the next sequence. Note, this is the same as next-sequence-start-index + 1.
next-sequence-end-index: The ending index of the next sequence.
next-sequence-end-number: The ending number of the next sequence. Note, this is the same as next-sequence-end-index + 1.
next-sequence-size: The size of the next index.
next-batches: A sequence of mapping objects with information about all following batches. Each mapping object has these keys batch-start-index, batch-end-index, and batch-size.

Examples

Looping over sub-objects:

      <dtml-in objectValues>
        title: <dtml-var title><br>
      </dtml-in>

Looping over two sets of objects, using prefixes:

      <dtml-let rows="(1,2,3)" cols="(4,5,6)">
        <dtml-in rows prefix="row">
          <dtml-in cols prefix="col">
            <dtml-var expr="row_item * col_item"><br>
            <dtml-if col_end>
              <dtml-var expr="col_total_item * row_mean_item">
            </dtml-if>
          </dtml-in>
        </dtml-in>
      </dtml-let>

Looping over a list of (key, value) tuples:

      <dtml-in objectItems>
        id: <dtml-var sequence-key>, title: <dtml-var title><br>
      </dtml-in>

Creating alternate colored table cells:

      <table>
      <dtml-in objectValues>
      <tr <dtml-if sequence-odd>bgcolor="#EEEEEE"
          <dtml-else>bgcolor="#FFFFFF"
          </dtml-if>
        <td><dtml-var title></td>
      </tr>
      </dtml-in>
      </table>

Basic batch processing:

      <p>
      <dtml-in largeSequence size=10 start=start previous>
        <a href="<dtml-var absolute_url><dtml-var sequence-query>start=<dtml-var previous-sequence-start-number>">Previous</a>
      </dtml-in>

      <dtml-in largeSequence size=10 start=start next>
        <a href="<dtml-var absolute_url><dtml-var sequence-query>start=<dtml-var next-sequence-start-number>">Next</a>
      </dtml-in>
      </p>

      <p>
      <dtml-in largeSequence size=10 start=start>
        <dtml-var sequence-item>
      </dtml-in>
      </p>

This example creates Previous and Next links to navigate between batches. Note, by using sequence-query, you do not lose any GET variables as you navigate between batches.