001/* 002 * Copyright 2002-2012 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 * https://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 017package org.springframework.web.servlet.view.velocity; 018 019import java.io.StringWriter; 020import java.util.Locale; 021import javax.servlet.http.HttpServletResponse; 022 023import org.apache.velocity.Template; 024import org.apache.velocity.context.Context; 025import org.apache.velocity.exception.ResourceNotFoundException; 026 027import org.springframework.core.NestedIOException; 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} property should be set to the content template 034 * for the view, and the layout template location should be specified as 035 * {@code layoutUrl} 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} 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 * @deprecated as of Spring 4.3, in favor of FreeMarker 054 */ 055@Deprecated 056public class VelocityLayoutView extends VelocityToolboxView { 057 058 /** 059 * The default {@link #setLayoutUrl(String) layout url}. 060 */ 061 public static final String DEFAULT_LAYOUT_URL = "layout.vm"; 062 063 /** 064 * The default {@link #setLayoutKey(String) layout key}. 065 */ 066 public static final String DEFAULT_LAYOUT_KEY = "layout"; 067 068 /** 069 * The default {@link #setScreenContentKey(String) screen content key}. 070 */ 071 public static final String DEFAULT_SCREEN_CONTENT_KEY = "screen_content"; 072 073 074 private String layoutUrl = DEFAULT_LAYOUT_URL; 075 076 private String layoutKey = DEFAULT_LAYOUT_KEY; 077 078 private String screenContentKey = DEFAULT_SCREEN_CONTENT_KEY; 079 080 081 /** 082 * Set the layout template to use. Default is {@link #DEFAULT_LAYOUT_URL "layout.vm"}. 083 * @param layoutUrl the template location (relative to the template 084 * root directory) 085 */ 086 public void setLayoutUrl(String layoutUrl) { 087 this.layoutUrl = layoutUrl; 088 } 089 090 /** 091 * Set the context key used to specify an alternate layout to be used instead 092 * of the default layout. Screen content templates can override the layout 093 * template that they wish to be wrapped with by setting this value in the 094 * template, for example:<br> 095 * {@code #set($layout = "MyLayout.vm" )} 096 * <p>Default key is {@link #DEFAULT_LAYOUT_KEY "layout"}, as illustrated above. 097 * @param layoutKey the name of the key you wish to use in your 098 * screen content templates to override the layout template 099 */ 100 public void setLayoutKey(String layoutKey) { 101 this.layoutKey = layoutKey; 102 } 103 104 /** 105 * Set the name of the context key that will hold the content of 106 * the screen within the layout template. This key must be present 107 * in the layout template for the current screen to be rendered. 108 * <p>Default is {@link #DEFAULT_SCREEN_CONTENT_KEY "screen_content"}: 109 * accessed in VTL as {@code $screen_content}. 110 * @param screenContentKey the name of the screen content key to use 111 */ 112 public void setScreenContentKey(String screenContentKey) { 113 this.screenContentKey = screenContentKey; 114 } 115 116 117 /** 118 * Overrides {@code VelocityView.checkTemplate()} to additionally check 119 * that both the layout template and the screen content template can be loaded. 120 * Note that during rendering of the screen content, the layout template 121 * can be changed which may invalidate any early checking done here. 122 */ 123 @Override 124 public boolean checkResource(Locale locale) throws Exception { 125 if (!super.checkResource(locale)) { 126 return false; 127 } 128 129 try { 130 // Check that we can get the template, even if we might subsequently get it again. 131 getTemplate(this.layoutUrl); 132 return true; 133 } 134 catch (ResourceNotFoundException ex) { 135 throw new NestedIOException("Cannot find Velocity template for URL [" + this.layoutUrl + 136 "]: Did you specify the correct resource loader path?", ex); 137 } 138 catch (Exception ex) { 139 throw new NestedIOException( 140 "Could not load Velocity template for URL [" + this.layoutUrl + "]", ex); 141 } 142 } 143 144 /** 145 * Overrides the normal rendering process in order to pre-process the Context, 146 * merging it with the screen template into a single value (identified by the 147 * value of screenContentKey). The layout template is then merged with the 148 * modified Context in the super class. 149 */ 150 @Override 151 protected void doRender(Context context, HttpServletResponse response) throws Exception { 152 renderScreenContent(context); 153 154 // Velocity context now includes any mappings that were defined 155 // (via #set) in screen content template. 156 // The screen template can overrule the layout by doing 157 // #set( $layout = "MyLayout.vm" ) 158 String layoutUrlToUse = (String) context.get(this.layoutKey); 159 if (layoutUrlToUse != null) { 160 if (logger.isDebugEnabled()) { 161 logger.debug("Screen content template has requested layout [" + layoutUrlToUse + "]"); 162 } 163 } 164 else { 165 // No explicit layout URL given -> use default layout of this view. 166 layoutUrlToUse = this.layoutUrl; 167 } 168 169 mergeTemplate(getTemplate(layoutUrlToUse), context, response); 170 } 171 172 /** 173 * The resulting context contains any mappings from render, plus screen content. 174 */ 175 private void renderScreenContent(Context velocityContext) throws Exception { 176 if (logger.isDebugEnabled()) { 177 logger.debug("Rendering screen content template [" + getUrl() + "]"); 178 } 179 180 StringWriter sw = new StringWriter(); 181 Template screenContentTemplate = getTemplate(getUrl()); 182 screenContentTemplate.merge(velocityContext, sw); 183 184 // Put rendered content into Velocity context. 185 velocityContext.put(this.screenContentKey, sw.toString()); 186 } 187 188}