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 }