001 // Copyright 2006, 2007, 2008, 2009 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.corelib.components;
016
017 import org.apache.tapestry5.*;
018 import org.apache.tapestry5.annotations.Environmental;
019 import org.apache.tapestry5.annotations.Parameter;
020 import org.apache.tapestry5.annotations.SupportsInformalParameters;
021 import org.apache.tapestry5.dom.Element;
022 import org.apache.tapestry5.ioc.annotations.Inject;
023 import org.apache.tapestry5.ioc.internal.util.InternalUtils;
024 import org.apache.tapestry5.services.Heartbeat;
025
026 /**
027 * Generates a <label> element for a particular field.
028 * <p/>
029 * A Label will render its body, if it has one. However, in most cases it will not have a body, and will render its
030 * {@linkplain org.apache.tapestry5.Field#getLabel() field's label} as it's body. Remember, however, that it is the
031 * field label that will be used in any error messages. The Label component allows for client- and server-side
032 * validation error decorations.
033 */
034 @SupportsInformalParameters
035 public class Label
036 {
037 /**
038 * The for parameter is used to identify the {@link Field} linked to this label (it is named this way because it
039 * results in the for attribute of the label element).
040 */
041 @Parameter(name = "for", required = true, allowNull = false, defaultPrefix = BindingConstants.COMPONENT)
042 private Field field;
043
044 @Environmental
045 private Heartbeat heartbeat;
046
047 @Environmental
048 private ValidationDecorator decorator;
049
050 @Inject
051 private ComponentResources resources;
052
053 private Element labelElement;
054
055 /**
056 * If true, then the body of the label element (in the template) is ignored. This is used when a designer places a
057 * value inside the <label> element for WYSIWYG purposes, but it should be replaced with a different
058 * (probably, localized) value at runtime. The default is false, so a body will be used if present and the field's
059 * label will only be used if the body is empty or blank.
060 */
061 @Parameter
062 private boolean ignoreBody;
063
064 boolean beginRender(MarkupWriter writer)
065 {
066 final Field field = this.field;
067
068 decorator.beforeLabel(field);
069
070 labelElement = writer.element("label");
071
072 resources.renderInformalParameters(writer);
073
074 // Since we don't know if the field has rendered yet, we need to defer writing the for and id
075 // attributes until we know the field has rendered (and set its clientId property). That's
076 // exactly what Heartbeat is for.
077
078 Runnable command = new Runnable()
079 {
080 public void run()
081 {
082 String fieldId = field.getClientId();
083
084 labelElement.forceAttributes("for", fieldId, "id", fieldId + "-label");
085
086 decorator.insideLabel(field, labelElement);
087 }
088 };
089
090 heartbeat.defer(command);
091
092 return !ignoreBody;
093 }
094
095 void afterRender(MarkupWriter writer)
096 {
097 // If the Label element has a body that renders some non-blank output, that takes precendence
098 // over the label string provided by the field.
099
100 boolean bodyIsBlank = InternalUtils.isBlank(labelElement.getChildMarkup());
101
102 if (bodyIsBlank) writer.write(field.getLabel());
103
104 writer.end(); // label
105
106 decorator.afterLabel(field);
107 }
108 }