Repeat.java

package com.google.sitebricks.core;

import java.util.Collection;

/**
 * <p>
 * Repeats tagged content over a collection. This widget is the equivalent of a
 * closure being projected across the given collection. Where the closure is around
 * the content of the annotated tag (and any nested tags). Use attribute {@code var}
 * to specify the name of the variable each collection entry will be bound to.
 * For example, to create a list of movie titles:
 * </p>
 *
 * <pre>
 * <ul>
 *   {@code @Repeat}(<b>items=movies</b>, var="movie")
 *   <li>${movie.title} starring ${movie.star}</li>
 * </ul>
 * </pre>
 *
 * <p>
 * This dynamically produces a repetition of {@code <li>} tags containing the movie title
 * and star for each entry in a collection property {@code movies}. Repeat widgets only
 * work on items in a {@code java.util.Collection} (or subtype like {@code java.util.List}).
 * It does *not* take arrays.
 * </p>
 *
 * <p>
 * Since the items attribute takes the result of an expression, you can place any expression in
 * it that evaluates to a collection:
 * </p>
 *
 * <pre>
 * <ul>
 *   {@code @Repeat}(<b>items=person.siblings</b>, var="sib")
 *   <li>${sib.name}</li>
 * </ul>
 * </pre>
 *
 * <p>
 *  This bit of code reads the siblings of a property {@code person} and binds it to a temporary
 * variable {@code sib} that when repeating the list elements.
 *
 * Of course, the repeat widget repeats *any* content inside it, so you are free to nest any
 * content you like inside, and they will be projected over the given collection:
 * </p>
 *
 * <pre>
 * <div>
 *   {@code @Repeat}(items=person.siblings, var="sib")
 *   <div>
 *      {@code @ShowIf}(sib.age > 1)
 *      <div>
 *          <p>${sib.name} is <b>${sib.age}</b> years old.</p>
 *      </div>
 *  </div>
 * </div>
 * </pre>
 *
 * 
 * <p>
 *
 * </p>
 *
 * @author Dhanji R. Prasanna (dhanji@gmail.com)
 */
@interface Repeat {
    /**
     * @instanceof java.util.Collection
     * @return Returns any subclass of collection to project across.
     */
    Class<? extends Collection> items();     //not really a Class

    String var() default "__this";
    String pageVar() default "__page";
}