001// Copyright 2004, 2005 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry.form;
016
017import org.apache.tapestry.IComponent;
018import org.apache.tapestry.IForm;
019
020/**
021 * A common interface implemented by all form components (components that create interactive
022 * elements in the rendered page).
023 * 
024 * @author Howard Lewis Ship
025 */
026
027public interface IFormComponent extends IComponent
028{
029    /**
030     * Returns the {@link org.apache.tapestry.IForm} which contains the component, or null if the
031     * component is not contained by a form, of if the containing Form is not currently renderring.
032     */
033
034    public IForm getForm();
035
036    /**
037     * Returns the name of the component, which is automatically generated during renderring.
038     * <p>
039     * This value is set inside the component's render method and is <em>not</em> cleared. If the
040     * component is inside a {@link org.apache.tapestry.components.Foreach}, the value returned is
041     * the most recent name generated for the component.
042     * <p>
043     * This property is made available to facilitate writing JavaScript that allows components (in
044     * the client web browser) to interact.
045     * <p>
046     * In practice, a {@link org.apache.tapestry.html.Script} component works with the
047     * {@link org.apache.tapestry.html.Body} component to get the JavaScript code inserted and
048     * referenced.
049     */
050
051    public String getName();
052
053    /**
054     * Invoked by {@link IForm#getElementId(IFormComponent)} when a name is created for a form
055     * component.
056     * 
057     * @since 3.0
058     * @see org.apache.tapestry.FormBehavior#getElementId(IFormComponent)
059     */
060
061    public void setName(String name);
062
063    /**
064     * May be implemented to return a user-presentable, localized name for the component, which is
065     * used in labels or error messages. Most components simply return null.
066     * 
067     * @since 1.0.9
068     */
069
070    public String getDisplayName();
071
072    /**
073     * Returns true if the component is disabled. This is important when the containing form is
074     * submitted, since disabled parameters do not update their bindings.
075     * 
076     * @since 2.2
077     */
078
079    public boolean isDisabled();
080
081    /**
082     * Returns the component's client-side element id. Typically, this is specified using an id
083     * parameter on the component and is passed through
084     * {@link org.apache.tapestry.IRequestCycle#getUniqueId(String)} to ensure that it is unique.
085     * The component is expected to write an id attribute (if it has a non null id). As with
086     * {@link #getName()}, if a component renders more than once (such as inside a loop) then on
087     * each render it will have a different clientId.
088     * 
089     * @return the id, or null if the component doesn't support an id.
090     * @since 4.0
091     */
092
093    public String getClientId();
094
095    /**
096     * Returns true if the field is required. This will (typically) involve consulting the
097     * component's validators.
098     * 
099     * @since 4.0
100     */
101
102    public boolean isRequired();
103}