Apache Struts 2 Documentation > Home > Guides > Tag Developers Guide > Struts Tags > Tag Reference > UI Tag Reference > component |

Apache Struts 2 Documentation
component
Edit Page Browse Space Add Page Add News
Added by digi9ten, last edited by Don Brown on Jan 06, 2007 (view change)

## Description

Renders an custom UI widget using the specified templates. Additional objects can be passed in to the template using the param tags.

Freemarker:

Objects provided can be retrieve from within the template via $parameters.paramname.

Jsp:

Objects provided can be retrieve from within the template via <s:property value="%{parameters.paramname}" />

In the bottom JSP and Velocity samples, two parameters are being passed in to the component. From within the component, they can be accessed as:-

Freemarker:

$parameters.get('key1') and $parameters.get('key2') or $parameters.key1 and $parameters.key2

Jsp:

<s:property value="%{parameters.key1}" /> and <s:property value="%{'parameters.key2'}" /> or <s:property value="%{parameters.get('key1')}" /> and <s:property value="%{parameters.get('key2')}" />

Currently, your custom UI components can be written in Velocity, JSP, or Freemarker, and the correct rendering engine will be found based on file extension.

Remember: the value params will always be resolved against the ValueStack so if you mean to pass a string literal to your component, make sure to wrap it in quotes i.e. value="'value1'" otherwise, the the value stack will search for an Object on the stack with a method of getValue1(). (now that i've written this, i'm not entirely sure this is the case. i should verify this manana)

| If Jsp is used as the template, the jsp template itself must lie within the webapp itself and not the classpath. Unlike Freemarker or Velocity, JSP template could not be picked up from the classpath.

## Parameters

#### Name | #### Required | #### Default | #### Evaluated | #### Type | #### Description
--- | --- | --- | --- | --- | ---
accesskey | false |  | true | String | Set the html accesskey attribute on rendered html element
cssClass | false |  | true | String | The css class to use for element
cssStyle | false |  | true | String | The css style definitions for element ro use
disabled | false |  | true | String | Set the html disabled attribute on rendered html element
id | false |  | true | String | id for referencing element. For UI and form tags it will be used as HTML id attribute
key | false |  | true | String | Set the key (name, value, label) for this particular component
label | false |  | true | String | Label expression used for rendering a element specific label
labelposition | false |  | true | String | Define label position of form element (top/left)
name | false |  | true | String | The name to set for element
onblur | false |  | true | String | Set the html onblur attribute on rendered html element
onchange | false |  | true | String | Set the html onchange attribute on rendered html element
onclick | false |  | true | String | Set the html onclick attribute on rendered html element
ondblclick | false |  | true | String | Set the html ondblclick attribute on rendered html element
onfocus | false |  | true | String | Set the html onfocus attribute on rendered html element
onkeydown | false |  | true | String | Set the html onkeydown attribute on rendered html element
onkeypress | false |  | true | String | Set the html onkeypress attribute on rendered html element
onkeyup | false |  | true | String | Set the html onkeyup attribute on rendered html element
onmousedown | false |  | true | String | Set the html onmousedown attribute on rendered html element
onmousemove | false |  | true | String | Set the html onmousemove attribute on rendered html element
onmouseout | false |  | true | String | Set the html onmouseout attribute on rendered html element
onmouseover | false |  | true | String | Set the html onmouseover attribute on rendered html element
onmouseup | false |  | true | String | Set the html onmouseup attribute on rendered html element
onselect | false |  | true | String | Set the html onselect attribute on rendered html element
required | false | false | true | Boolean | If set to true, the rendered element will indicate that input is required
requiredposition | false |  | true | String | Define required position of required form element (left|right)
tabindex | false |  | true | String | Set the html tabindex attribute on rendered html element
template | false |  | true | String | The template (other than default) to use for rendering the element
templateDir | false |  | true | String | The template directory.
theme | false |  | true | String | The theme (other than default) to use for rendering the element
title | false |  | true | String | Set the html title attribute on rendered html element
tooltip | false |  | true | String | Set the tooltip of this particular component
tooltipConfig | false |  | true | String | Set the tooltip configuration
value | false |  | true | String | Preset the value of input element.

## Examples

    JSP
        <s:component template="/my/custom/component.vm"/>

          or

        <s:component template="/my/custom/component.vm">
          <s:param name="key1" value="value1"/>
          <s:param name="key2" value="value2"/>
        </s:component>

    Velocity
        #s-component( "template=/my/custom/component.vm" )

          or

        #s-component( "template=/my/custom/component.vm" )
          #s-param( "name=key1" "value=value1" )
          #s-param( "name=key2" "value=value2" )
        #end

    Freemarker
       <@s..component template="/my/custom/component.ftl" />

         or

       <@s..component template="/my/custom/component.ftl">
          <@s..param name="key1" value="%{'value1'}" />
          <@s..param name="key2" value="%{'value2'}" />
       </@s..component>