src/site/apt/tutorial/advanced/list-attributes.apt

~~ $Id$
~~
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~ http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.
~~
         -----------
         List Attributes
         -----------

List Attributes

  Up to now we have seen simple attributes, i.e. attributes that have a simple
  value: a template, a string or a definition. But there are cases where you
  need a <collection> of values, for example a list of definitions to be
  redendered one below the other.

* Simple usage

  To include a list attribute you can use the <<<\<put-list-attribute\>>>> tag
  in your Tiles definitions file:

---------------------------------------
<definition name="myapp.homepage.body" template="/layouts/variable_rows.jsp">
  <put-list-attribute name="items">
    <add-attribute value="/tiles/banner.jsp" />
    <add-attribute value="/tiles/common_menu.jsp" />
    <add-attribute value="/tiles/credits.jsp" />
  </put-list-attribute>
</definition>
---------------------------------------

  In your template page, you can read the list attribute iterating over its
  elements:

---------------------------------------
<%@ taglib uri="http://tiles.apache.org/tags-tiles" prefix="tiles" %>
<%@ taglib uri="http://tiles.apache.org/tags-tiles-extras" prefix="tilesx" %>
<%@ taglib uri="http://java.sun.com/jstl/core_rt" prefix="c" %>
<tilesx:useAttribute id="list" name="items" classname="java.util.List" />
<c:forEach var="item" items="${list}">
  <tiles:insertAttribute value="${item}" flush="true" />
  <br/>
</c:forEach>
---------------------------------------

  The list attribute is first converted into a scripting variable; after that
  it is iterated using the <<<\<c:forEach\>>>> tag. The compound attributes are
  then rendered one after the other.

* {List attribute inheritance}

  When you extend a definition that contains a list attribute, you can
  "inherit" its elements. For example:

---------------------------------------
<definition name="myapp.homepage.body" template="/layouts/variable_rows.jsp">
  <put-list-attribute name="items">
    <add-attribute value="/tiles/banner.jsp" />
    <add-attribute value="/tiles/common_menu.jsp" />
    <add-attribute value="/tiles/credits.jsp" />
  </put-list-attribute>
</definition>

<definition name="myapp.homepage.body.extended" extends="myapp.homepage.body">
  <put-list-attribute name="items" inherit="true">
    <add-attribute value="/tiles/greetings.jsp" />
  </put-list-attribute>
</definition>
---------------------------------------

  In this case, the <<<myapp.homepage.body.extended>>> has the <<<items>>>
  attribute that inherits the content of the <<<items>>> attribute of its
  parent definition. In other words, the <<<items>>> attribute will container
  the following elements:

  * /tiles/banner.jsp

  * /tiles/common_menu.jsp

  * /tiles/credits.jsp

  * /tiles/greetings.jsp