001: /*
002: * Copyright 2002-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.web.servlet.view.velocity;
018:
019: import java.io.StringWriter;
020:
021: import javax.servlet.http.HttpServletResponse;
022:
023: import org.apache.velocity.Template;
024: import org.apache.velocity.context.Context;
025: import org.apache.velocity.exception.ResourceNotFoundException;
026:
027: import org.springframework.context.ApplicationContextException;
028:
029: /**
030: * VelocityLayoutView emulates the functionality offered by Velocity's
031: * VelocityLayoutServlet to ease page composition from different templates.
032: *
033: * <p>The <code>url</code> property should be set to the content template
034: * for the view, and the layout template location should be specified as
035: * <code>layoutUrl</code> property. A view can override the configured
036: * layout template location by setting the appropriate key (the default
037: * is "layout") in the content template.
038: *
039: * <p>When the view is rendered, the VelocityContext is first merged with
040: * the content template (specified by the <code>url</code> property) and
041: * then merged with the layout template to produce the final output.
042: *
043: * <p>The layout template can include the screen content through a
044: * VelocityContext variable (the default is "screen_content").
045: * At runtime, this variable will contain the rendered content template.
046: *
047: * @author Darren Davison
048: * @author Juergen Hoeller
049: * @since 1.2
050: * @see #setLayoutUrl
051: * @see #setLayoutKey
052: * @see #setScreenContentKey
053: */
054: public class VelocityLayoutView extends VelocityToolboxView {
055:
056: /**
057: * The default {@link #setLayoutUrl(String) layout url}.
058: */
059: public static final String DEFAULT_LAYOUT_URL = "layout.vm";
060:
061: /**
062: * The default {@link #setLayoutKey(String) layout key}.
063: */
064: public static final String DEFAULT_LAYOUT_KEY = "layout";
065:
066: /**
067: * The default {@link #setScreenContentKey(String) screen content key}.
068: */
069: public static final String DEFAULT_SCREEN_CONTENT_KEY = "screen_content";
070:
071: private String layoutUrl = DEFAULT_LAYOUT_URL;
072:
073: private String layoutKey = DEFAULT_LAYOUT_KEY;
074:
075: private String screenContentKey = DEFAULT_SCREEN_CONTENT_KEY;
076:
077: /**
078: * Set the layout template to use. Default is {@link #DEFAULT_LAYOUT_URL "layout.vm"}.
079: * @param layoutUrl the template location (relative to the template
080: * root directory)
081: */
082: public void setLayoutUrl(String layoutUrl) {
083: this .layoutUrl = layoutUrl;
084: }
085:
086: /**
087: * Set the context key used to specify an alternate layout to be used instead
088: * of the default layout. Screen content templates can override the layout
089: * template that they wish to be wrapped with by setting this value in the
090: * template, for example:<br>
091: * <code>#set( $layout = "MyLayout.vm" )</code>
092: * <p>Default key is {@link #DEFAULT_LAYOUT_KEY "layout"}, as illustrated above.
093: * @param layoutKey the name of the key you wish to use in your
094: * screen content templates to override the layout template
095: */
096: public void setLayoutKey(String layoutKey) {
097: this .layoutKey = layoutKey;
098: }
099:
100: /**
101: * Set the name of the context key that will hold the content of
102: * the screen within the layout template. This key must be present
103: * in the layout template for the current screen to be rendered.
104: * <p>Default is {@link #DEFAULT_SCREEN_CONTENT_KEY "screen_content"}:
105: * accessed in VTL as <code>$screen_content</code>.
106: * @param screenContentKey the name of the screen content key to use
107: */
108: public void setScreenContentKey(String screenContentKey) {
109: this .screenContentKey = screenContentKey;
110: }
111:
112: /**
113: * Overrides <code>VelocityView.checkTemplate()</code> to additionally check
114: * that both the layout template and the screen content template can be loaded.
115: * Note that during rendering of the screen content, the layout template
116: * can be changed which may invalidate any early checking done here.
117: */
118: protected void checkTemplate() throws ApplicationContextException {
119: super .checkTemplate();
120:
121: try {
122: // Check that we can get the template, even if we might subsequently get it again.
123: getTemplate(this .layoutUrl);
124: } catch (ResourceNotFoundException ex) {
125: throw new ApplicationContextException(
126: "Cannot find Velocity template for URL ["
127: + this .layoutUrl
128: + "]: Did you specify the correct resource loader path?",
129: ex);
130: } catch (Exception ex) {
131: throw new ApplicationContextException(
132: "Could not load Velocity template for URL ["
133: + this .layoutUrl + "]", ex);
134: }
135: }
136:
137: /**
138: * Overrides the normal rendering process in order to pre-process the Context,
139: * merging it with the screen template into a single value (identified by the
140: * value of screenContentKey). The layout template is then merged with the
141: * modified Context in the super class.
142: */
143: protected void doRender(Context context,
144: HttpServletResponse response) throws Exception {
145: renderScreenContent(context);
146:
147: // Velocity context now includes any mappings that were defined
148: // (via #set) in screen content template.
149: // The screen template can overrule the layout by doing
150: // #set( $layout = "MyLayout.vm" )
151: String layoutUrlToUse = (String) context.get(this .layoutKey);
152: if (layoutUrlToUse != null) {
153: if (logger.isDebugEnabled()) {
154: logger
155: .debug("Screen content template has requested layout ["
156: + layoutUrlToUse + "]");
157: }
158: } else {
159: // No explicit layout URL given -> use default layout of this view.
160: layoutUrlToUse = this .layoutUrl;
161: }
162:
163: mergeTemplate(getTemplate(layoutUrlToUse), context, response);
164: }
165:
166: /**
167: * The resulting context contains any mappings from render, plus screen content.
168: */
169: private void renderScreenContent(Context velocityContext)
170: throws Exception {
171: if (logger.isDebugEnabled()) {
172: logger.debug("Rendering screen content template ["
173: + getUrl() + "]");
174: }
175:
176: StringWriter sw = new StringWriter();
177: Template screenContentTemplate = getTemplate(getUrl());
178: screenContentTemplate.merge(velocityContext, sw);
179:
180: // Put rendered content into Velocity context.
181: velocityContext.put(this.screenContentKey, sw.toString());
182: }
183:
184: }
|