    001// Copyright 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
    015package org.apache.tapestry5;
    016
    017import org.apache.tapestry5.dom.Element;
    018
    019/**
    020 * An object responsible for performing decorations around fields and field labels. The decorator is notified at
    021 * intervals by the fields and labels.
    022 * <p/>
    023 * In most western languages (written left to right) the label will render before the field, so the properties of the
    024 * Field may not be set yet (or may reflect a previous looping's rendering). It may be necessary to {@linkplain
    025 * org.apache.tapestry5.services.Heartbeat#defer(Runnable)} defer any rendering} until after the Label and the Field have
    026 * both had their change to initialize and render.
    027 * <p/>
    028 * Modern HTML and CSS, especially under HTML5 and CSS3, really makes this pointless; it is possible to handle all
    029 * of these issues directly in the client. ValidationDecorator will be supported in Tapestry 5.4,
    030 * but the default implementation will be changed to do nothing.
    031 *
    032 * @deprecated Deprecated in 5.4 with no replacement.
    033 */
    034public interface ValidationDecorator
    035{
    036    /**
    037     * Invoked by a {@link org.apache.tapestry5.corelib.components.Label} before rendering itself.
    038     *
    039     * @param field
    040     *         for this label
    041     */
    042    void beforeLabel(Field field);
    043
    044    /**
    045     * Invoked after the label has rendered its tag, but before it has rendered content inside the tag, to allow the
    046     * decorator to write additional attributes.
    047     *
    048     * @param field
    049     *         the field corresponding to the label
    050     * @param labelElement
    051     *         the element for this label
    052     */
    053    void insideLabel(Field field, Element labelElement);
    054
    055
    056    /**
    057     * Invoked by {@link org.apache.tapestry5.corelib.components.Label} after rendering itself.
    058     *
    059     * @param field
    060     */
    061    void afterLabel(Field field);
    062
    063    /**
    064     * Renders immediately before the field itself. The field will typically render a single element, though a complex
    065     * field may render multiple elements or even some JavaScript.
    066     *
    067     * @param field
    068     */
    069    void beforeField(Field field);
    070
    071    /**
    072     * Invoked at a point where the decorator may write additional attributes into the field. Generally speaking, you
    073     * will want to {@linkplain ComponentResources#renderInformalParameters(MarkupWriter) render informal parameters}
    074     * <strong>before</strong> invoking this method.
    075     *
    076     * @param field
    077     */
    078    void insideField(Field field);
    079
    080    /**
    081     * Invoked after the field has completed rendering itself.
    082     */
    083    void afterField(Field field);
    084}