    001    // Copyright 2006, 2007, 2008 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.tapestry5;
    016
    017    /**
    018     * Defines a field within a form.  Fields have a <a href="http://www.w3.org/TR/html4/interact/forms.html#control-name">control
    019     * name</a> that is used when rendering and, later, when the form is submitted, to identify the query parameter.
    020     * <p/>
    021     * Timing is important, as components may render multiple times, due to looping and other factors. Generally, a
    022     * component's {@link #getControlName()} will only be accurate after it has rendered.  In some cases, when generating
    023     * JavaScript for example, it is necessary to {@linkplain org.apache.tapestry5.services.Heartbeat#defer(Runnable) wait
    024     * until the end of the current Heartbeat} to ensure that all components have had thier chance to render.
    025     */
    026    public interface Field extends ClientElement
    027    {
    028        /**
    029         * Returns the value used as the name attribute of the rendered element. This value will be unique within an
    030         * enclosing form, even if the same component renders multiple times.
    031         *
    032         * @see org.apache.tapestry5.services.FormSupport#allocateControlName(String)
    033         */
    034        String getControlName();
    035
    036        /**
    037         * Returns a user presentable (localized) label for the field, which may be used inside &lt;label&gt; elements on
    038         * the client, and inside client or server-side validation error messages.
    039         *
    040         * @return the label
    041         * @see org.apache.tapestry5.corelib.components.Label
    042         */
    043        String getLabel();
    044
    045        /**
    046         * Returns true if the field is disabled; A disabled field will render a disabled attribute so that it is
    047         * non-responsive on the client (at least, until its disabled status is changed on the client using JavaScript). A
    048         * disabled field will ignore any value passed up in a form submit request. Care must be taken if the disabled
    049         * status of a field can change between the time the field is rendered and the time the enclosing form is
    050         * submitted.
    051         */
    052        boolean isDisabled();
    053
    054        /**
    055         * Returns true if this field required (as per {@link org.apache.tapestry5.FieldValidator#isRequired()}).
    056         *
    057         * @return true if a non-blank value is required for the field
    058         */
    059        boolean isRequired();
    060    }