    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005//     http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5;
    014
    015import org.apache.tapestry5.dom.Element;
    016
    017/**
    018 * An object responsible for performing decorations around fields and field labels. The decorator is notified at
    019 * intervals by the fields and labels.
    020 *
    021 * In most western languages (written left to right) the label will render before the field, so the properties of the
    022 * Field may not be set yet (or may reflect a previous looping's rendering). It may be necessary to {@linkplain
    023 * org.apache.tapestry5.services.Heartbeat#defer(Runnable)} defer any rendering} until after the Label and the Field have
    024 * both had their change to initialize and render.
    025 *
    026 * Modern HTML and CSS, especially under HTML5 and CSS3, really makes this pointless; it is possible to handle all
    027 * of these issues directly in the client. ValidationDecorator will be supported in Tapestry 5.4,
    028 * but the default implementation will be changed to do nothing.
    029 *
    030 * @deprecated Deprecated in 5.4 with no replacement.
    031 */
    032public interface ValidationDecorator
    033{
    034    /**
    035     * Invoked by a {@link org.apache.tapestry5.corelib.components.Label} before rendering itself.
    036     *
    037     * @param field
    038     *         for this label
    039     */
    040    void beforeLabel(Field field);
    041
    042    /**
    043     * Invoked after the label has rendered its tag, but before it has rendered content inside the tag, to allow the
    044     * decorator to write additional attributes.
    045     *
    046     * @param field
    047     *         the field corresponding to the label
    048     * @param labelElement
    049     *         the element for this label
    050     */
    051    void insideLabel(Field field, Element labelElement);
    052
    053
    054    /**
    055     * Invoked by {@link org.apache.tapestry5.corelib.components.Label} after rendering itself.
    056     *
    057     * @param field
    058     */
    059    void afterLabel(Field field);
    060
    061    /**
    062     * Renders immediately before the field itself. The field will typically render a single element, though a complex
    063     * field may render multiple elements or even some JavaScript.
    064     *
    065     * @param field
    066     */
    067    void beforeField(Field field);
    068
    069    /**
    070     * Invoked at a point where the decorator may write additional attributes into the field. Generally speaking, you
    071     * will want to {@linkplain ComponentResources#renderInformalParameters(MarkupWriter) render informal parameters}
    072     * <strong>before</strong> invoking this method.
    073     *
    074     * @param field
    075     */
    076    void insideField(Field field);
    077
    078    /**
    079     * Invoked after the field has completed rendering itself.
    080     */
    081    void afterField(Field field);
    082}