VelocityLayoutView (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.servlet.view.velocity

## Class VelocityLayoutView

- java.lang.Object
- - org.springframework.context.support.ApplicationObjectSupport
  - - org.springframework.web.context.support.WebApplicationObjectSupport
    - - org.springframework.web.servlet.view.AbstractView
      - - org.springframework.web.servlet.view.AbstractUrlBasedView
        - - org.springframework.web.servlet.view.AbstractTemplateView
          - - org.springframework.web.servlet.view.velocity.VelocityView
            - - org.springframework.web.servlet.view.velocity.VelocityToolboxView
              - - org.springframework.web.servlet.view.velocity.VelocityLayoutView

- All Implemented Interfaces:
    Aware, BeanNameAware, InitializingBean, ApplicationContextAware, ServletContextAware, View

      public class VelocityLayoutView
      extends VelocityToolboxView

  VelocityLayoutView emulates the functionality offered by Velocity's VelocityLayoutServlet to ease page composition from different templates.

  The `url` property should be set to the content template for the view, and the layout template location should be specified as `layoutUrl` property. A view can override the configured layout template location by setting the appropriate key (the default is "layout") in the content template.

  When the view is rendered, the VelocityContext is first merged with the content template (specified by the `url` property) and then merged with the layout template to produce the final output.

  The layout template can include the screen content through a VelocityContext variable (the default is "screen_content"). At runtime, this variable will contain the rendered content template.

  Since:
    1.2
  Author:
    Darren Davison, Juergen Hoeller
  See Also:
    `setLayoutUrl(java.lang.String)`, `setLayoutKey(java.lang.String)`, `setScreenContentKey(java.lang.String)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_LAYOUT_KEY` The default `layout key`.
    `static String` | `DEFAULT_LAYOUT_URL` The default `layout url`.
    `static String` | `DEFAULT_SCREEN_CONTENT_KEY` The default `screen content key`.

    - ### Fields inherited from class org.springframework.web.servlet.view.AbstractTemplateView

      `SPRING_MACRO_REQUEST_CONTEXT_ATTRIBUTE`

    - ### Fields inherited from class org.springframework.web.servlet.view.AbstractView

      `DEFAULT_CONTENT_TYPE`

    - ### Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

      `logger`

    - ### Fields inherited from interface org.springframework.web.servlet.View

      `PATH_VARIABLES, RESPONSE_STATUS_ATTRIBUTE, SELECTED_CONTENT_TYPE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `VelocityLayoutView()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `checkResource(Locale locale)` Overrides `VelocityView.checkTemplate()` to additionally check that both the layout template and the screen content template can be loaded.
    `protected void` | `doRender(org.apache.velocity.context.Context context, HttpServletResponse response)` Overrides the normal rendering process in order to pre-process the Context, merging it with the screen template into a single value (identified by the value of screenContentKey).
    `void` | `setLayoutKey(String layoutKey)` Set the context key used to specify an alternate layout to be used instead of the default layout.
    `void` | `setLayoutUrl(String layoutUrl)` Set the layout template to use.
    `void` | `setScreenContentKey(String screenContentKey)` Set the name of the context key that will hold the content of the screen within the layout template.

    - ### Methods inherited from class org.springframework.web.servlet.view.velocity.VelocityToolboxView

      `createVelocityContext, getToolboxConfigLocation, initTool, setToolboxConfigLocation`

    - ### Methods inherited from class org.springframework.web.servlet.view.velocity.VelocityView

      `autodetectVelocityEngine, createVelocityContext, exposeHelpers, exposeHelpers, exposeHelpers, exposeToolAttributes, getEncoding, getTemplate, getTemplate, getVelocityEngine, initApplicationContext, isCacheTemplate, mergeTemplate, renderMergedTemplateModel, setCacheTemplate, setDateToolAttribute, setEncoding, setNumberToolAttribute, setToolAttributes, setVelocityEngine`

    - ### Methods inherited from class org.springframework.web.servlet.view.AbstractTemplateView

      `applyContentType, renderMergedOutputModel, setAllowRequestOverride, setAllowSessionOverride, setExposeRequestAttributes, setExposeSessionAttributes, setExposeSpringMacroHelpers`

    - ### Methods inherited from class org.springframework.web.servlet.view.AbstractUrlBasedView

      `afterPropertiesSet, getUrl, isUrlRequired, setUrl, toString`

    - ### Methods inherited from class org.springframework.web.servlet.view.AbstractView

      `addStaticAttribute, createMergedOutputModel, createRequestContext, createTemporaryOutputStream, exposeModelAsRequestAttributes, generatesDownloadContent, getAttributesMap, getBeanName, getContentType, getRequestContextAttribute, getStaticAttributes, isExposePathVariables, prepareResponse, render, setAttributes, setAttributesCSV, setAttributesMap, setBeanName, setContentType, setExposePathVariables, setRequestContextAttribute, setResponseContentType, writeToResponse`

    - ### Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

      `getServletContext, getTempDir, getWebApplicationContext, initApplicationContext, initServletContext, isContextRequired, setServletContext`

    - ### Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

      `getApplicationContext, getMessageSourceAccessor, requiredContextClass, setApplicationContext`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_LAYOUT_URL

          public static final String DEFAULT_LAYOUT_URL

      The default `layout url`.
      See Also:
        Constant Field Values

    - #### DEFAULT_LAYOUT_KEY

          public static final String DEFAULT_LAYOUT_KEY

      The default `layout key`.
      See Also:
        Constant Field Values

    - #### DEFAULT_SCREEN_CONTENT_KEY

          public static final String DEFAULT_SCREEN_CONTENT_KEY

      The default `screen content key`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### VelocityLayoutView

          public VelocityLayoutView()

  - ### Method Detail

    - #### setLayoutUrl

          public void setLayoutUrl(String layoutUrl)

      Set the layout template to use. Default is `"layout.vm"`.
      Parameters:
        `layoutUrl` - the template location (relative to the template root directory)

    - #### setLayoutKey

          public void setLayoutKey(String layoutKey)

      Set the context key used to specify an alternate layout to be used instead of the default layout. Screen content templates can override the layout template that they wish to be wrapped with by setting this value in the template, for example:
      `#set($layout = "MyLayout.vm" )`

      Default key is `"layout"`, as illustrated above.

      Parameters:
        `layoutKey` - the name of the key you wish to use in your screen content templates to override the layout template

    - #### setScreenContentKey

          public void setScreenContentKey(String screenContentKey)

      Set the name of the context key that will hold the content of the screen within the layout template. This key must be present in the layout template for the current screen to be rendered.

      Default is `"screen_content"`: accessed in VTL as `$screen_content`.

      Parameters:
        `screenContentKey` - the name of the screen content key to use

    - #### checkResource

          public boolean checkResource(Locale locale)
                                throws Exception

      Overrides `VelocityView.checkTemplate()` to additionally check that both the layout template and the screen content template can be loaded. Note that during rendering of the screen content, the layout template can be changed which may invalidate any early checking done here.
      Overrides:
        `checkResource` in class `VelocityView`
      Parameters:
        `locale` - the desired Locale that we're looking for
      Returns:
        `true` if the resource exists (or is assumed to exist); `false` if we know that it does not exist
      Throws:
        `Exception` - if the resource exists but is invalid (e.g. could not be parsed)

    - #### doRender

          protected void doRender(org.apache.velocity.context.Context context,
                      HttpServletResponse response)
                           throws Exception

      Overrides the normal rendering process in order to pre-process the Context, merging it with the screen template into a single value (identified by the value of screenContentKey). The layout template is then merged with the modified Context in the super class.
      Overrides:
        `doRender` in class `VelocityView`
      Parameters:
        `context` - the Velocity context to use for rendering
        `response` - servlet response (use this to get the OutputStream or Writer)
      Throws:
        `Exception` - if thrown by Velocity
      See Also:
        `AbstractUrlBasedView.setUrl(java.lang.String)`, `VelocityView.getTemplate()`, `VelocityView.mergeTemplate(org.apache.velocity.Template, org.apache.velocity.context.Context, javax.servlet.http.HttpServletResponse)`