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.