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, or if the containing Form is not currently rendering.
032 */
033
034 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.ForBean}, 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 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 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 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 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 * <p>
090 * <b>Note:</b>Though semantically this method should result in the roughly the same results,
091 * the method used to create unique client ID's on form components is <i>not</i> the same as that
092 * defined in {@link IComponent}.
093 * </p>
094 *
095 * @return the id, or null if the component doesn't support an id.
096 * @since 4.0
097 */
098
099 String getClientId();
100
101 /**
102 * Returns true if the field is required. This will (typically) involve consulting the
103 * component's validators.
104 *
105 * @since 4.0
106 */
107
108 boolean isRequired();
109 }