////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

== render

=== Description

Renders a GSP template and caches the result so that the next time the same
template is rendered it doesn't have to be evaluated again.  Optionally, a key
may be provided which can be helpful if the cached content is different per
user, for example.

This tag behaves just like the `g:render` tag provided by Grails except this one
caches the rendered result so the template doesn't have to be re-evaluated each
time it is rendered.

By default the key used in the cache is the path to the template.  If the same
template is rendered multiple times with a different model, an explicit key
should be provided, otherwise the separate invocations (with different models)
will share the same cache entry.

[source,xml]
----
<cache:render template="myTemplate" model="[user: currentUser]" key="${currentUser.id}"/>
----

Note that the key's namespace is confined to a particular template.  This means
that if there are 2 separate GSP templates cached with the same key value, the 2
will not collide with each other.  Each cached GSP template has its own set of
keys.


=== Examples


[source,xml]
----
<cache:render template="myTemplate" model="[name: 'Some Value']"/>
----

[source,xml]
----
<cache:render template="myTemplate" model="[name: 'Some Value']" key="${currentUser.id}"/>
----

[source,xml]
----
<cache:render template="myTemplate" model="[name: 'Some Value']" key="${currentUser.id}" ttl="${60*60*24*7}" />
----

=== Attributes


* `template` (required) - The name of the template to apply
* `key` (optional) - An optional key that may be provided to allow for different instances of the rendered template to be held in the cache, presumably with different content.
* `contextPath` (optional) - the context path to use (relative to the application context path). Defaults to "" or path to the plugin for a plugin view or template.
* `bean` (optional) - The bean to apply the template against
* `model` (optional) - The model to apply the template against as a `java.util.Map`
* `collection` (optional) - A collection of model objects to apply the template to
* `var` (optional) - The variable name of the bean to be referenced in the template
* `plugin` (optional) - The plugin to look for the template in
* `ttl` (optional) - An optional ttl (seconds) may be provided to allow the blocks to automatically evict a specified number of seconds after first insertion.

See the documentation for the core `g.render` tag for details on each of the optional attributes.
