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    
015    package org.apache.tapestry.form;
016    
017    import org.apache.tapestry.IComponent;
018    import 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    
027    public 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    }