Builtin Components</> <para> The Tapestry framework provides a large set of pre-written components to use as a starting point for building applications, or more complicated components. </> <para> This section will provide a brief overview of the available components and their most commonly used parameters. The Javadoc is the final reference for this information. </> <para> Each of these components is automatically added as an alias in an application specification. </> <section id="builtin.Action"> <title>Action</> <para> Creates an <sgmltag class=starttag>a</> hyperlink in the HTML response. If the link is triggered, then the <classname>Action</> retrieves its listener, and invokes <function>actionTriggered()</> on it. </> <variablelist> <title>Parameters</> <varlistentry> <term>listener</> <listitem> <para>The object notified if and when the link is triggered.</> </> </> <varlistentry> <term>disabled</> <listitem> <para>Controls whether the link is produced. If true, the link is not created (but wrapped elements are still rendered). </> </> </> </> </section> <section id="builtin.Any"> <title>Any</> <para> Used to make an existing HTML element dynamic. Informal parameters are used to fill in the attributes of the element. </> <variablelist> <title>Parameters</> <varlistentry> <term>element</> <listitem> <para>The element to be produced.</> </> </> </> </section> <section id="builtin.Block"> <title>Block</> <para> A block is used to prevent a section of an HTML template from being renderred. That is, a <classname>Block</classname> is allowed a body, but never renders it. Intead, an <classname>InsertBlock</classname> component is used to insert the body of the block. </> <para><classname>Block</>s are used to pass arbitrary blocks of HTML and components as parameters to a component. </> </section> <section id="builtin.Body"> <title>Body</> <para> Replaces the <sgmltag class=starttag>body</> tag. The <classname>Body</> component provides some support for other components, such as the <classname>Rollover</> component. </> </section> <section id="builtin.Checkbox"> <title>Checkbox</> <para> Used to implement a checkbox form element (<sgmltag class=starttag>input type=checkbox</>). Must be wrapped by a <classname>Form</> component. </> <variablelist> <title>Parameters</> <varlistentry> <term>selected</> <listitem> <para>Indicates whether the checkbox is selected or not.</> </> </> <varlistentry> <term>disabled</> <listitem> <para>Controls whether the text field is active or not. This attibute is ignored by Netscape Navigator 4.</> </> </> </> </section> <section id="builtin.Conditional"> <title>Conditional</> <para> Makes part of an HTML template conditional. The body of the <classname>Conditional</> component is only rendered if a specified condition is met. </> <variablelist> <title>Parameters</> <varlistentry> <term>condition</> <listitem> <para>The condition to be met.</> </> </> <varlistentry> <term>invert</> <listitem> <para>If true, then the condition is inverted. This is useful for simulating an else clause. </> </> </> </> </section> <section id="component.DateField"> <title>DateField</> <para> A kind of validating text field that allows a date to be entered. </> <variablelist> <title>Parameters</> <varlistentry> <term>date</> <listitem> <para>The date property to be editted.</> </> </> <varlistentry> <term>displayName</term> <listitem> <para> A name for the the component, used when formulating error messages. </> </> </> <varlistentry> <term>delegate</> <listitem> <para>An <classname>IValidationDelegate</> used to handle validation exceptions. </> </> </> <varlistentry> <term>maximum</> <listitem> <para>The lastest acceptible date (optional).</> </> </> <varlistentry> <term>minimum</> <listitem> <para>The earliest acceptible date (optional).</> </> </> <varlistentry> <term>required</> <listitem> <para>If true, a value must be entered.</> </> </> </> </section> <section id="builtin.Delegator"> <title>Delegator</> <para> A component which delegates its behavior (that is, the HTML rendered) to some other object. This is occasionally useful when the HTML to render is best generated from pure Java code (or has been provided from some source outside of Tapestry). </> <variablelist> <title>Parameters</> <varlistentry> <term>delegate</> <listitem> <para>The object which will provide the rendering for the component.</> </> </> </> </section> <section id="builtin.Direct"> <title>Direct</> <para> Creates a <sgmltag class=starttag>a</> hyperlink that notifies the component when the link is triggered. The link includes some context-specific data that is passed on to the component's listener. This is used in cases where the <classname>Action</> component can't be used (or is too inefficient). </> <variablelist> <title>Parameters</> <varlistentry> <term>listener</> <listitem> <para>Specifies an object that is notified when the link is clicked.</> </> </> <varlistentry> <term>context</> <listitem> <para>An array of Strings to be encoded into the URL. These parameters will be decoded when the link is triggered.</> </> </> <varlistentry> <term>disabled</> <listitem> <para>Controls whether the link is produced. If true, the portion of the template the link surrounds is still rendered, but not the link itself.</> </> </> </> </section> <section id="builtin.ExceptionDisplay"> <title>ExceptionDisplay</> <para> A component, used on the standard exception page, which renders a detailed list of the exceptions. </> <variablelist> <title>Parameters</> <varlistentry> <term>exceptions</> <listitem> <para>An array of <classname>com.primix.foundation.exception.ExceptionDescription</> objects. </> </> </> </> </section> <section id="builtin.FieldLabel"> <title>FieldLabel</> <para> A component, used with a ValidatingTextField (or similar component) that provides the label for the field. A delegate object may be specified that will change the visual formatting of the label to reflect the state of the field, for instance, to make the label red when the field itself is in error. </> <variablelist> <title>Parameters</> <varlistentry> <term>field</> <listitem> <para>The validating text field (type <classname>IValidatingTextField</>) associated with the label.</> </> </> <varlistentry> <term>delegate</> <listitem> <para>An optional <classname>IValidationDelegate</>, responsible for the visual look of the label.</> </> </> </> </section> <section id="builtin.Foreach"> <title>Foreach</> <para> A component that loops through a set of values, setting a property for each value before rendering its wrapped elements. </> <variablelist> <title>Parameters</> <varlistentry> <term>source</> <listitem> <para>The source of objects to be iterated, and array or <classname>List</> of objects. </> </> </> <varlistentry> <term>value</> <listitem> <para>Used to update the current value on each iteration.</> </> </> </> </section> <section id="builtin.Form"> <title>Form</> <para> A component that manages an HTML form. The other form-related components must be wrapped inside the <classname>Form</>. </> <variablelist> <title>Parameters</> <varlistentry> <term>method</> <listitem> <para>The value to use for the method attribute of the <sgmltag class=starttag>form</> tag.</> </> </> <varlistentry> <term>listener</> <listitem> <para>The listener, informed after the wrapped components of the form have had a chance to respond to the request.</> </> </> </> </section> <section id="builtin.Hidden"> <title>Hidden</> <para> Adds a hidden (<sgmltag class=starttag>input type=hidden</>) field to a <classname>Form</>. This is often used to synchronize data when the form is submitted with values known when the page was rendered . </> <variablelist> <title>Parameters</> <varlistentry> <term>value</> <listitem> <para>Property to store when the form is renderred and to restore when the form is submitted.</> </> </> </> </section> <section id="builtin.Image"> <title>Image</> <para> Used to insert a static image. </> <variablelist> <title>Parameters</> <varlistentry> <term>image</> <listitem> <para>The image to show, specified as an asset.</> </> </> </> </section> <section id="builtin.ImageSubmit"> <title>ImageSubmit</> <para> An image button inside a <classname>Form</>. Clicking the button submits the form. </> <variablelist> <title>Parameters</> <varlistentry> <term>disabled</> <listitem> <para>If true, the image button will be disabled (not respond to the mouse).</> <para>The disabled attribute is ignored by Netscape Navigator 4.</> </> </> <varlistentry> <term>image</> <listitem> <para>The default image to display.</> </> </> <varlistentry> <term>selected</> <listitem> <para>A property updated if the button is clicked.</> </> </> <varlistentry> <term>tag</> <listitem> <para>The value assigned to the selected property if the button is clicked.</> </> </> </> </section> <section id="builtin.Insert"> <title>Insert</> <para> Inserts dynamic text into the HTML response. Invalid characters (such as < and >) are converted into HTML entities (< and >). </> <variablelist> <title>Parameters</> <varlistentry> <term>value</> <listitem> <para>The value to be inserted, which may be a <classname>String</> or an arbitrary object (that is converted to a <classname>String</>). </> </> </> <varlistentry> <term>format</> <listitem> <para>A format (<classname>java.text.Format</>) object used to format the <classname>String</> or object. </> </> </> </> </section> <section id="builtin.InsertBlock"> <title>InsertBlock</> <para> Inserts the body of a <classname>Block</>. </> <variablelist> <title>Parameters</> <varlistentry> <term>block</> <listitem> <para>The <classname>Block</> to insert.</> </> </> </> </section> <section id="builtin.InsertWrapped"> <title>InsertWrapped</> <para> Renders the static HTML and components wrapped by the container of the <classname>InsertWrapped</> component. Components which have HTML templates and can wrap other elements should include exactly one <classname>InsertWrapped</> component in their template. </> </section> <section id="builtin.IntegerField"> <title>IntegerField</> <para> A type of validating text field that is used to edit an integer property. </> <variablelist> <title>Parameters</> <varlistentry> <term>value</> <listitem> <para>The property to edit.</> </> </> <varlistentry> <term>displayName</term> <listitem> <para> A name for the the component, used when formulating error messages. </> </> </> <varlistentry> <term>delegate</> <listitem> <para>An <classname>IValidationDelegate</> that is used to handle validation exceptions.</> </> </> <varlistentry> <term>required</> <listitem> <para>If true, a value must be provided by the user.</> </> </> <varlistentry> <term>minimum</> <listitem> <para>Optional minimum acceptible value.</> </> </> <varlistentry> <term>maximum</> <listitem> <para>Optional maximum acceptible value.</> </> </> </> </section> <section id="builtin.Option"> <title>Option</> <para> Implements a component that manages an HTML <sgmltag class=starttag>option</> form element, and must be wrapped by a <classname>Select</> component. </> <variablelist> <title>Parameters</> <varlistentry> <term>selected</> <listitem> <para>Used to indicate whether the given option is selected.</> </> </> </> </section> <section id="builtin.Page"> <title>Page</> <para> Creates a hyperlink to another page within the application. </> <variablelist> <title>Parameters</> <varlistentry> <term>page</> <listitem> <para>The name of a page to link to.</> </> </> <varlistentry> <term>disabled</> <listitem> <para>Controls whether the link is produced. If true, the portion of the template the link surrounds is still rendered, but not the link itself. </> </> </> </> </section> <section id="builtin.PropertySelection"> <title>PropertySelection</> <para> Creates form elements that allow a property of an object to be selected. This may take the form of a <sgmltag class=starttag>select</> or a sequence of <sgmltag class=starttag>input type=radio</> elements. </> <para> Uses a model to map between Java values that will be assigned, and textual labels that will appear in the HTML response. </> <variablelist> <title>Parameters</> <varlistentry> <term>value</> <listitem> <para>The property value to edit.</> </> </> <varlistentry> <term>model</> <listitem> <para>The model used to enumerate the potential values, and to produce text labels for each value. </> </> <varlistentry> <term>renderer</> <listitem> <para> An object used to render the property selection; two default implementations are provided (one creates a pop up list, the other a table of radio buttons). </> </> </> </> </section> <section id="builtin.Radio"> <title>Radio</> <para> A component used to manage an HTML radio form element. Such a component must be wrapped (possibly indirectly) inside a <classname>RadioGroup</> component. </> <variablelist> <title>Parameters <varlistentry> <term>value</> <listitem> <para> The value to be assigned through the <classname>RadioGroup</>'s selected parameter, if the <classname>Radio</> is selected by the user. </> </> </> <varlistentry> <term>disabled</> <listitem> <para> If true, then the <classname>Radio</> is disabled. It will write a disabled attribute into its tag when rendering, and will not update its selected binding. </> <para> The disabled attribute is ignored by Netscape Navigator 4.</> </> </> </> </section> <section id="builtin.RadioGroup"> <title>RadioGroup</> <para> A container of <classname>Radio</> components, which itself must be within a <classname>Form</> component. The <classname>RadioGroup</> and <classname>Radio</> components combined provide similar functionality to the <classname>PropertySelection</> component (though with some greater flexibility). </> <variablelist> <title>Parameters <varlistentry> <term>selected</> <listitem> <para>The property to be updated by the <classname>RadioGroup</> based on which <classname>Radio</> button is selected by the user. </> </> </> </> </section> <section id="builtin.Rollover"> <title>Rollover</> <para> Works with any kind of link component, which must wrap it, to provide a rollover image button ... a button where the image changes when the mouse move over it or off of it. A <classname>Rollover</> is disabled if the link that wraps it is disabled (in which case it doesn't respond to the mouse). </> <para> The component provides all the necessary JavaScript to swap the image when the mouse enters and exits the button. However, the <classname>Rollover</> must be wrapped (ultimately) by a <classname>Body</> component. </> <variablelist> <title>Parameters</> <varlistentry> <term>image</> <listitem> <para>The (initial) image to show (if not disabled).</> </> </> <varlistentry> <term>focus</> <listitem> <para>The image displayed when the mouse moves over the button (unless disabled).</> </> </> <varlistentry> <term>blur</> <listitem> <para>The image displayed when the mouse moves off of the button (unless disabled).</> </> </> <varlistentry> <term>disabled</> <listitem> <para>The image displayed if the link is itself disabled.</> </> </> </> </section> <section id="builtin.Script"> <title>Script</> <para> A component that accesses a script file and adds JavaScript functions and statements to the response page. The specified script file is read and parsed and substitutions are made before the final scripting code is inserted into the page. </> <variablelist> <title>Parameters</> <varlistentry> <term>script</> <listitem> <para>The resource path of the script file.</> </> </> </> </section> <section id="builtin.Select"> <title>Select</> <para> A component which creates a <sgmltag class=starttag>select</> form element (it is also a wrapper around <classname>Option</> components), within a <classname>Form</>. </> <para> It is generally easier to use a <classname>PropertySelection</>, unless multiple selections are desired. </> <variablelist> <title>Parameters</> <varlistentry> <term>multiple</> <listitem> <para>If true, the component allows multiple selection.</> </> </> </> </section> <section id="builtin.Service"> <title>Service</> <para> A component for creating a link for an arbitrary engine service that uses no parameters, such as the reset or home service. </> <variablelist> <title>Parameters</> <varlistentry> <term>service</> <listitem> <para>The name of the service.</> </> </> <varlistentry> <term>disabled</> <listitem> <para>Controls whether the link is produced. If true, the portion of the template the link surrounds is still rendered, but not the link itself. </> </> </> </> </section> <section id="builtin.Shell"> <title>Shell</> <para> Provides the outer "shell" of a page, including the <sgmltag class=starttag>html></>, <sgmltag class=starttag>head</> and <sgmltag class=starttag>title</> tags (but not the <sgmltag class=starttag>body</> tag). </> <variablelist> <title>Parameters</> <varlistentry> <term>title</> <listitem> <para>Title for the page, placed within a <sgmltag class=starttag>title</> element.</> </> </> <varlistentry> <term>stylesheet</> <listitem> <para>Stylesheet to be used for the page.</> </> </> </> </section> <section id="builtin.Submit"> <title>Submit</> <para> Provides a form submit button (<input type=submit>). This is most useful when the form contains multiple submit buttons and the application needs to know which was actually pressed. </> <variablelist> <title>Parameters</> <varlistentry> <term>disabled</> <listitem> <para>If true, the submit button will be disabled.</> <para>The disabled attribute is ignored by Netscape Navigator 4). </> </> </> <varlistentry> <term>label</> <listitem> <para>The label to put on the button.</> </> </> <varlistentry> <term>selected</> <listitem> <para>A property updated if the button is the one clicked to submit the form.</> </> </> <varlistentry> <term>tag</> <listitem> <para>The value applied to the selected property if the button is the one clicked to submit the form.</> </> </> </> </section> <section id="builtin.ShowInspector"> <title>ShowInspector</> <para> Adds a link to a page that is used to raise the Tapestry Inspector in a new window. This is generally added to the navigational border of an application, and is only enabled when developing the application (disabled in deployment). </> </section> <section id="builtin.Text"> <title>Text</> <para> Implements a component that manages an HTML <sgmltag class=starttag>textarea</> form element, within a <classname>Form</> component. </> <variablelist> <title>Parameters</> <varlistentry> <term>text</> <listitem> <para>The text inside the text area.</> </> </> <varlistentry> <term>disabled</> <listitem> <para> Controls whether the <classname>Text</> is active or not. </> <para>The disabled attribute is ignored by Netscape Navigator 4. </> </> </> <varlistentry> <term>columns</> <listitem> <para>The width of the <sgmltag class=starttag>textarea</>, in characters. </> </> </> <varlistentry> <term>rows</> <listitem> <para>The number of rows in the <sgmltag class=starttag>textarea</>. </> </> </> </> </section> <section id="builtin.TextField"> <title>TextField</> <para> Implements a component that manages an HTML <sgmltag class=starttag>input type=text</> or <sgmltag class=starttag>input type=password</> form element, within a <classname>Form</> component. </> <variablelist> <title>Parameters</> <varlistentry> <term>text</> <listitem> <para>The text inside the text field.</> </> </> <varlistentry> <term>hidden</> <listitem> <para>If true, then the text field is written as a <sgmltag class=starttag>input type=password</> form element. </> </> </> <varlistentry> <term>disabled</> <listitem> <para>Controls whether the text field is active or not. Netscape Navigator 4 ignores the disabled attribute. </> </> </> <varlistentry> <term>displayWidth</> <listitem> <para>Controls the display width of the text control in the client browser.</> </> </> <varlistentry> <term>maximumLength</> <listitem> <para>Controls the maximum number of characters that the text control will accept. </> </> </> </> </section> <section id="builtin.ValidatingTextField"> <title>ValidatingTextField</> <para> An improved <classname>TextField</> that can perform simple validations. The field may be required, and a minimum length may be specified. </> <variablelist> <title>Parameters <varlistentry> <term>text</> <listitem> <para>The text inside the text field.</> </> </> <varlistentry> <term>hidden</> <listitem> <para>If true, then the text field is written as a <sgmltag class=starttag>input type=password</> form element. </> </> </> <varlistentry> <term>displayName</term> <listitem> <para> A name for the the component, used when formulating error messages. </> </> </> <varlistentry> <term>delegate</> <listitem> <para>An <classname>IValidationDelegate</> used to handle validation exceptions. </> </> </> <varlistentry> <term>minimumLength</> <listitem> <para>The minimum number of characters allowed.</> </> </> <varlistentry> <term>required</> <listitem> <para>If true, a value must be entered.</> </> </> <varlistentry> <term>disabled</> <listitem> <para>Controls whether the text field is active or not. Netscape Navigator 4 ignores the disabled attribute. </> </> </> <varlistentry> <term>displayWidth</> <listitem> <para>Controls the display width of the text control in the client browser.</> </> </> <varlistentry> <term>maximumLength</> <listitem> <para>Controls the maximum number of characters that the text control will accept. </> </> </> </> </section> </chapter>