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}