<?xml version="1.0"?>
<document url="struts-tiles.html" authors="false">

<properties>
  <author>Cedric Dumoulin</author>
  <title>Tiles Tag Library</title>
</properties>

<body>


<taglib>

  <!-- ============== Tag Library Description Elements ============= -->

  <tlibversion>1.2</tlibversion>
  <jspversion>1.1</jspversion>
  <shortname>tiles</shortname>
  <display-name>Tiles Tag Library</display-name>
  <uri>http://struts.apache.org/tags-tiles</uri>
  <info>
    <p>This tag library provides tiles tags.</p>
    <p>Tiles were previously called Components. For historical reasons, names, pages, components and templates
    are used indifferently to design a tile. Also, a lot of tags and attribute names are
    left for backward compatibility.</p>
    <p>To know more about tags defined in this library, check the associated documentation:
    tiles-doc.</p>
  </info>

 <!-- ===================== Include Tags ====================== -->

  <tag>
    <name>insert</name>
    <summary>
    Insert a tiles/component/template.
    </summary>
    <info>
    <p>Insert a tiles/component/template with the possibility to pass parameters
    (called attribute).
    A tile can be seen as a procedure that can take parameters or attributes.
    <code>&lt;tiles:insert&gt;</code> allows to define these attributes and pass them to the inserted jsp page,
    called template.
    Attributes are defined using nested tag <code>&lt;tiles:put&gt;</code> or
    <code>&lt;tiles:putList&gt;</code>.
    </p>
    <p>
    You must specify one of this tag attribute :
    </p>
      <ul>
      <li><code>template</code>, for inserting a tiles/component/template page,</li>
      <li><code>component</code>, for inserting a tiles/component/template page, (same as template)</li>
      <li><code>page</code> for inserting a JSP page, (same as template)</li>
      <li><code>definition</code>, for inserting a definition from definitions factory</li>
      <li><code>attribute</code>, surrounding tiles's attribute name whose value is used.
        <br/>If attribute is associated to 'direct' flag (see put), and flag is true, write
        attribute value (no insertion).
      </li>
      <li><code>name</code>, to let 'insert' determine the type of entities to insert. In this later
      case, search is done in this order : definitions, tiles/components/templates, pages.
      </li>
      </ul>
      <p>
      In fact, Page, component and template, are equivalent as a tile, component or template are jsp page.
      </p>
      <p><strong>Example : </strong></p>
        <pre><code>
          &lt;tiles:insert page="/basic/myLayout.jsp" flush="true"&gt;
            &lt;tiles:put name="title"  value="My first page" /&gt;
            &lt;tiles:put name="header" value="/common/header.jsp" /&gt;
            &lt;tiles:put name="footer" value="/common/footer.jsp" /&gt;
            &lt;tiles:put name="menu"   value="/basic/menu.jsp" /&gt;
            &lt;tiles:put name="body"   value="/basic/helloBody.jsp" /&gt;
          &lt;/tiles:insert&gt;</code></pre>
    </info>
    <tagclass>org.apache.struts.taglib.tiles.InsertTag</tagclass>
    <bodycontent>JSP</bodycontent>

    <attribute>
      <name>template</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
        <p>A string representing the URI of a tile or template (a JSP page).</p>
        <p>'page', 'component' and 'template' are synonyms : they have exactly the same behavior.</p>
      </info>
    </attribute>

    <attribute>
      <name>component</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
        <p>Path (relative or absolute to webapps) of the component to insert.</p>
        <p>'page', 'component' and 'template' are synonyms : they have exactly the same behavior.</p>
      </info>
   </attribute>

    <attribute>
      <name>page</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
        <p>Path (relative or absolute to webapps) of the page to insert.</p>
        <p>'page', 'component' and 'template' are synonyms : they have exactly the same behavior.</p>
      </info>
    </attribute>

    <attribute>
      <name>definition</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
        Name of the definition to insert. Definition are defined in a centralized file.
        For now, only definition from factory can be inserted with this attribute.
        To insert a definition defined with tag &lt;tiles:definition&gt;, use beanName="".
      </info>
    </attribute>

    <attribute>
      <name>attribute</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        Name of an attribute in current tile/component context. Value of this attribute is passed to
        'name' (see attribute 'name').
      </info>
    </attribute>

    <attribute>
      <name>name</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
        Name of an entity to insert. Search is done in this order : definition, attribute,
        [tile/component/template/page].
      </info>
    </attribute>

    <attribute>
      <name>beanName</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      <p>Name of the bean used as value. Bean is retrieved from specified context, if any. Otherwise,
      method pageContext.findAttribute is used.
      If beanProperty is also specified, retrieve value from the corresponding bean property.</p>
      <p>If found bean (or property value) is instance of one of Attribute class (Direct,
      Instance, ...), insertion is done according to the class type. Otherwise, the toString method is
      called on the bean, and returned String is used as name to insert (see 'name' attribute).</p>
      </info>
    </attribute>

    <attribute>
      <name>beanProperty</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      Bean property name. If specified, value is retrieve from this property. Support nested/indexed
      properties.
      </info>
    </attribute>

    <attribute>
      <name>beanScope</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
      Scope into which bean is searched. If not specified, method pageContext.findAttribute is used.
      Scope can be any JSP scope, 'component', or 'template'.
      In these two later cases, bean is search in tile/component/template context.
      </info>
    </attribute>

    <attribute>
      <name>flush</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        True or false. If true, current page out stream is flushed before insertion.
      </info>
    </attribute>

    <attribute>
      <name>ignore</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      If this attribute is set to true, and the attribute specified by the name
      does not exist, simply return without writing anything. The default value is false, which will
      cause a runtime exception to be thrown.
      </info>
    </attribute>

    <attribute>
      <name>role</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      If the user is in the specified role, the tag is taken into account;
      otherwise, the tag is ignored (skipped).
      </info>
    </attribute>

    <attribute>
      <name>controllerUrl</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      <p>Url of a controller called immediately before page is inserted.</p>
      <p>
      Url usually denote a Struts action. Controller (action) is used to prepare data
      to be render by inserted Tile.
      </p>
      <p>See also controlerClass. Only one of controllerUrl or controllerClass should be used.</p>
      </info>
    </attribute>

    <attribute>
      <name>controllerClass</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      <p>Class type of a controller called immediately before page is inserted.</p>
      <p>Controller is used to prepare data to be render by inserted Tile.</p>
      <p>See also controlerUrl</p>
      <p>Class must implements or extends one of the following :</p>
      <ul>
        <li>org.apache.struts.tiles.Controller</li>
        <li>org.apache.struts.tiles.ControllerSupport</li>
        <li>org.apache.struts.action.Action (wrapper org.apache.struts.action.ActionController is used)</li>
      </ul>
      <p>
      See also controllerUrl. Only one of controllerUrl or controllerClass should be used.
      </p>
      </info>
    </attribute>

  </tag>

  <tag>
    <name>definition</name>
    <summary>
    Create a tile /component / template definition bean.
    </summary>
    <info>
    Create a tile/component/template definition as a bean.
    Newly created bean will be saved under specified "id", in the requested "scope".
    Definition tag has same syntax as <code>insert</code> tag.
    The new definition can extends a definition described in factory (XML file), and overload
    any previously defined parameters.
    </info>
        <tagclass>org.apache.struts.taglib.tiles.DefinitionTag</tagclass>
        <bodycontent>JSP</bodycontent>

    <attribute>
      <name>id</name>
      <required>true</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
      Specifies the name under which the newly created definition bean will be saved.
      </info>
    </attribute>

    <attribute>
      <name>scope</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
      Specifies the variable scope into which the newly defined bean will be created.
      If not specified, the bean will be created in page scope.
      </info>
    </attribute>

    <attribute>
      <name>template</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      A string representing the URI of a tile/component/template (a JSP page).
      </info>
    </attribute>

    <attribute>
      <name>page</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      URL of the template / component to insert. Same as "template".
      </info>
    </attribute>

    <attribute>
      <name>role</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      Role to check before inserting this definition. If role is not defined for current user,
      definition is not inserted. Checking is done at insert time, not during definition process.
      </info>
    </attribute>

    <attribute>
      <name>extends</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      Name of a parent definition that is used to initialize this new definition.
      Parent definition is searched in definitions factory.
      </info>
    </attribute>

  </tag>

  <tag>
    <name>put</name>
    <summary>
      Put an attribute into tile/component/template context.
    </summary>
    <info>
      Define an attribute to pass to tile/component/template.
      This tag can only be used inside 'insert' or 'definition' tag.
      Value (or content) is specified using attribute 'value' (or 'content'), or using the tag body.
      It is also possible to specify the type of the value :
      <ul>
      <li>string : Content is written directly.</li>
      <li>page | template : Content is included from specified URL. Name is used as an URL.</li>
      <li>definition : Content come from specified definition (from factory). Name is used as definition name.</li>
      </ul>
      If type is specified, it is taken into account by 'get' or 'insert' inside the inserted tile.
      <p>If 'type' attribute is not specified, content is 'untyped', unless it comes from a typed bean.</p>
      <p>Note that using 'direct="true"' is equivalent to 'type="string"'.</p>
    </info>
    <tagclass>org.apache.struts.taglib.tiles.PutTag</tagclass>
    <bodycontent>JSP</bodycontent>

    <attribute>
      <name>name</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        Name of the attribute.
      </info>
    </attribute>

    <attribute>
      <name>value</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
        Attribute value. Could be a String or an Object.
       Value can come from a direct assignment (value="aValue") or from a bean.
       One of 'value' 'content' or 'beanName' must be present.
      </info>
    </attribute>

    <attribute>
      <name>content</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      Content that's put into tile scope.
      Synonym to value. Attribute added for compatibility with JSP Template.
      </info>
    </attribute>

    <attribute>
      <name>direct</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
      Determines how content is handled: true means content is
      printed <em>direct</em>ly; false, the default, means content
      is included.
      This is another way to specify content type. If 'direct=true' content is 'string', if
      'direct=false', content is 'page'.
      Attribute added for compatibility with JSP Template.
      </info>
    </attribute>

    <attribute>
      <name>type</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
      Specify content type: string, page, template or definition.
      <ul>
      <li>String : Content is printed directly.</li>
      <li>page | template : Content is included from specified URL. Name is used as an URL.</li>
      <li>definition : Value is the name of a definition defined in factory (xml file). Definition will be searched
      in the inserted tile, in a <code>&lt;tiles:insert attribute="attributeName"&gt;</code> tag, where 'attributeName'
      is the name used for this tag.</li>
      </ul>
      If 'type' attribute is not specified, content is 'untyped', unless it comes from a typed bean.
      </info>
    </attribute>

    <attribute>
      <name>beanName</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      Name of the bean used as value. Bean is retrieved from specified context, if any. Otherwise,
      method pageContext.findAttribute is used.
      If beanProperty is specified, retrieve value from the corresponding bean property.
      </info>
    </attribute>

    <attribute>
      <name>beanProperty</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      Bean property name. If specified, value is retrieve from this property. Support nested/indexed
      properties.
      </info>
    </attribute>

    <attribute>
      <name>beanScope</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
      Scope into which bean is searched. If not specified, method pageContext.findAttribute is used.
      Scope can be any JSP scope, 'tile', 'component', or 'template'.
      In these three later cases, bean is search in tile/component/template context.
      </info>
    </attribute>

    <attribute>
      <name>role</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      If the user is in the specified role, the tag is taken into account;
      otherwise, the tag is ignored (skipped).
      </info>
    </attribute>

  </tag>

  <tag>
    <name>putList</name>
    <summary>
      Declare a list that will be pass as attribute to tile.
    </summary>
    <info>
      Declare a list that will be pass as attribute to tile.
      List elements are added using the tag 'add'.
      This tag can only be used inside 'insert' or 'definition' tag.
    </info>
    <tagclass>org.apache.struts.taglib.tiles.PutListTag</tagclass>
    <bodycontent>JSP</bodycontent>

    <attribute>
      <name>name</name>
      <required>true</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        Name of the list.
      </info>
    </attribute>
  </tag>

  <tag>
    <name>add</name>
    <summary>
       Add an element to the surrounding list.
       Equivalent to 'put', but for list element.
    </summary>
    <info>
       Add an element to the surrounding list.
       This tag can only be used inside putList tag.
       Value can come from a direct assignment (value="aValue") or from a bean.
       One of 'value' or 'beanName' must be present.
    </info>
    <tagclass>org.apache.struts.taglib.tiles.AddTag</tagclass>
    <bodycontent>JSP</bodycontent>

    <attribute>
      <name>value</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        Element value. Can be a String or Object.
      </info>
    </attribute>

    <attribute>
      <name>content</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      Element value. Can be a String or Object.
      Synonym to value. Attribute added for compatibility with JSP Template.
      </info>
    </attribute>

    <attribute>
      <name>direct</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
      Determines how content is handled: true means content is
      printed <em>direct</em>ly; false, the default, means content
      is included.
      This is another way to specify content type. If 'direct=true' content is 'string', if
      'direct=false', content is 'page'.
      Attribute added for compatibility with JSP Template.
      </info>
    </attribute>

    <attribute>
      <name>type</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
      Specify content type: string, page, template or instance.
      <ul>
      <li>String : Content is printed directly.</li>
      <li>page | template : Content is included from specified URL. Name is used as an URL.</li>
      <li>definition : Value denote a definition defined in factory (xml file). Definition will be searched
      in the inserted tile, in a <code>&lt;insert attribute="attributeName"&gt;</code> tag, where 'attributeName'
      is the name used for this tag.</li>
      </ul>
      If 'type' attribute is not specified, content is 'untyped', unless it comes from a typed bean.
      </info>
    </attribute>

    <attribute>
      <name>beanName</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      Name of the bean used as value. Bean is retrieved from specified context, if any. Otherwise,
      method pageContext.findAttribute is used.
      If beanProperty is specified, retrieve value from the corresponding bean property.
      </info>
    </attribute>

    <attribute>
      <name>beanProperty</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      Bean property name. If specified, value is retrieve from this property. Support nested/indexed
      properties.
      </info>
    </attribute>

    <attribute>
      <name>beanScope</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
      Scope into which bean is searched. If not specified, method pageContext.findAttribute is used.
      Scope can be any JSP scope, 'component', or 'template'.
      In these two later cases, bean is search in tile/component/template context.
      </info>
    </attribute>

    <attribute>
      <name>role</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      <p>If the user is in the specified role, the tag is taken into account;
      otherwise, the tag is ignored (skipped).</p>
      <p>
      The role isn't taken into account if &lt;add&gt; tag is used in a definition.</p>
      </info>
    </attribute>

  </tag>

  <tag>

    <name>get</name>
    <summary>
    Gets the content from request scope that was put there by a
    put tag.
    </summary>
    <tagclass>org.apache.struts.taglib.tiles.GetTag</tagclass>
    <bodycontent>empty</bodycontent>
    <info>
    <p>Retrieve content from tile context and include it.</p>
    <p>Take into account the 'type' attribute.</p>
    </info>

    <attribute>
      <name>name</name>
      <required>true</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      The name of the content to get from tile/component scope.
      </info>
    </attribute>

    <attribute>
      <name>ignore</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      If this attribute is set to true, and the attribute specified by the name
      does not exist, simply return without writing anything. The default value is false, which will
      cause a runtime exception to be thrown.
      </info>
    </attribute>

    <attribute>
      <name>flush</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        True or false. If true, current page  out stream is flushed before insertion.
      </info>
    </attribute>

    <attribute>
      <name>role</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      If the user is in the specified role, the tag is taken into account;
      otherwise, the tag is ignored (skipped).
      </info>
    </attribute>

  </tag>

  <tag>
    <name>getAsString</name>
    <summary>
      Render the value of the specified tile/component/template attribute to the current JspWriter
    </summary>
    <info>
      Retrieve the value of the specified tile/component/template attribute property, and render it to the current JspWriter as a String.
      The usual toString() conversions is applied on found value.
      <p>Throw a JSPException if named value is not found.</p>
    </info>
    <tagclass>org.apache.struts.taglib.tiles.GetAttributeTag</tagclass>
    <bodycontent>empty</bodycontent>
    <attribute>
      <name>name</name>
      <required>true</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
        Attribute name.
      </info>
    </attribute>

    <attribute>
      <name>ignore</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      If this attribute is set to true, and the attribute specified by the name
      does not exist, simply return without writing anything. The default value is false, which will
      cause a runtime exception to be thrown.
      </info>
    </attribute>

    <attribute>
      <name>role</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      If the user is in the specified role, the tag is taken into account;
      otherwise, the tag is ignored (skipped).
      </info>
    </attribute>

  </tag>

  <tag>
    <name>useAttribute</name>
    <summary>
      Use attribute value inside page.
    </summary>
    <info>
      <p>
      Declare a Java variable, and an attribute in the specified scope, using tile attribute value.
      </p>
      <p>
      Java variable and attribute will have the name specified by 'id', or the original name if not
      specified.
      </p>
    </info>
    <tagclass>org.apache.struts.taglib.tiles.UseAttributeTag</tagclass>
    <teiclass>org.apache.struts.taglib.tiles.UseAttributeTei</teiclass>
    <bodycontent>empty</bodycontent>
    <attribute>
      <name>id</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        Declared attribute and variable name.
      </info>
    </attribute>
    <attribute>
      <name>classname</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        Class of the declared variable.
      </info>
    </attribute>
    <attribute>
      <name>scope</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        Scope of the declared attribute. Default to 'page'.
      </info>
    </attribute>
    <attribute>
      <name>name</name>
      <required>true</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
        Tile's attribute name.
      </info>
    </attribute>

    <attribute>
      <name>ignore</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      If this attribute is set to true, and the attribute specified by the name
      does not exist, simply return without error. The default value is false, which will
      cause a runtime exception to be thrown.
      </info>
    </attribute>

  </tag>

  <tag>
    <name>importAttribute</name>
    <summary>
      Import Tile's attribute in specified context.
    </summary>
    <info>
      Import attribute from tile to requested scope.
      Attribute name and scope are optional. If not specified, all tile
      attributes are imported in page scope.
      Once imported, an attribute can be used as any other beans from jsp contexts.
    </info>
    <tagclass>org.apache.struts.taglib.tiles.ImportAttributeTag</tagclass>
    <bodycontent>empty</bodycontent>
    <attribute>
      <name>name</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
        Tile's attribute name. If not specified, all attributes are imported.
      </info>
    </attribute>
    <attribute>
      <name>scope</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        Scope into which attribute is imported. Default to page.
      </info>
    </attribute>

    <attribute>
      <name>ignore</name>
      <required>false</required>
      <rtexprvalue>true</rtexprvalue>
      <info>
      If this attribute is set to true, and the attribute specified by the name
      does not exist, simply return without error. The default value is false, which will
      cause a runtime exception to be thrown.
      </info>
    </attribute>

  </tag>

  <tag>
    <name>initComponentDefinitions</name>
    <summary>
      Initialize Tile/Component definitions factory.
    </summary>
    <info>
      <p>Initialize Tile/Components definitions factory.</p>
      <p>
      In order to use Tile/Component definitions factory, you need to initialize the factory.
      This is generally done in a initializing servlet. In particular, it is done in
      "ComponentActionServlet" if you use it.
      If you don't initialize factory in a servlet, you can initialize it using this tag. You need
      to provide the description file name, and optionally the factory classname.
      Initialization is done only once, at the first call of this tag. Subsequent calls
      are ignored (tag checks existence of the factory.
      </p>
    </info>
    <tagclass>org.apache.struts.taglib.tiles.InitDefinitionsTag</tagclass>
    <bodycontent>empty</bodycontent>
    <attribute>
      <name>file</name>
      <required>true</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        Definition file name.
      </info>
    </attribute>

    <attribute>
      <name>classname</name>
      <required>false</required>
      <rtexprvalue>false</rtexprvalue>
      <info>
        If specified, classname of the factory to create and initialized.
      </info>
    </attribute>

  </tag>

</taglib>

</body>

</document>
