Velocity Response Writer | Apache Solr Reference Guide 6.6

The VelocityResponseWriter is an optional plugin available in the contrib/velocity directory. It powers the /browse user interfaces when using configurations such as "basic_configs", "techproducts", and "example/files".

Its JAR and dependencies must be added (via <lib> or solr/home lib inclusion), and must be registered in solrconfig.xml like this:

<queryResponseWriter name="velocity" class="solr.VelocityResponseWriter">
  <str name="template.base.dir">${velocity.template.base.dir:}</str>

<!--
  <str name="init.properties.file">velocity-init.properties</str>
  <bool name="params.resource.loader.enabled">true</bool>
  <bool name="solr.resource.loader.enabled">false</bool>
  <lst name="tools">
    <str name="mytool">com.example.MyCustomTool</str>
  </lst>
-->
</queryResponseWriter>

The above example shows the optional initialization and custom tool parameters used by VelocityResponseWriter; these are detailed in the following table. These initialization parameters are only specified in the writer registration in solrconfig.xml, not as request-time parameters. See further below for request-time parameters.

Configuration & Usage

VelocityResponseWriter Initialization Parameters

Parameter Description Default value

Parameter	Description	Default value
template.base.dir	If specified and exists as a file system directory, a file resource loader will be added for this directory. Templates in this directory will override "solr" resource loader templates.
init.properties.file	Specifies a properties file name which must exist in the Solr `conf/` directory (not under a `velocity/` subdirectory) or root of a JAR file in a <lib>.
params.resource.loader.enabled	The "params" resource loader allows templates to be specified in Solr request parameters. For example: `http://localhost:8983/solr/gettingstarted/select?q=:&wt=velocity&v.template=custom&v.template.custom=CUSTOM%3A%20%23core_name` where `v.template=custom` says to render a template called "custom" and `v.template.custom’s value is the actual custom template. This is disabled by default; it’d be a niche, unusual, use case to need this enabled.	false
solr.resource.loader.enabled	The "solr" resource loader is the only template loader registered by default. Templates are served from resources visible to the SolrResourceLoader under a `velocity/` subdirectory. The VelocityResponseWriter itself has some built-in templates (in its JAR file, under velocity/) that are available automatically through this loader. These built-in templates can be overridden when the same template name is in conf/velocity/ or by using the `template.base.dir` option.	true
tools	External "tools" can be specified as list of string name/value (tool name / class name) pairs. Tools, in the Velocity context, are simply Java objects. Tool classes are constructed using a no-arg constructor (or a single-SolrCore-arg constructor if it exists) and added to the Velocity context with the specified name. A custom registered tool can override the built-in context objects with the same name, except for $request, $response, $page, and $debug (these tools are designed to not be overridden).

template.base.dir

If specified and exists as a file system directory, a file resource loader will be added for this directory. Templates in this directory will override "solr" resource loader templates.

init.properties.file

Specifies a properties file name which must exist in the Solr conf/ directory (not under a velocity/ subdirectory) or root of a JAR file in a <lib>.

params.resource.loader.enabled

The "params" resource loader allows templates to be specified in Solr request parameters. For example:

http://localhost:8983/solr/gettingstarted/select?q=*:*&wt=velocity&v.template=custom&v.template.custom=CUSTOM%3A%20%23core_name

where v.template=custom says to render a template called "custom" and `v.template.custom’s value is the actual custom template. This is disabled by default; it’d be a niche, unusual, use case to need this enabled.

false

solr.resource.loader.enabled

The "solr" resource loader is the only template loader registered by default. Templates are served from resources visible to the SolrResourceLoader under a velocity/ subdirectory. The VelocityResponseWriter itself has some built-in templates (in its JAR file, under velocity/) that are available automatically through this loader. These built-in templates can be overridden when the same template name is in conf/velocity/ or by using the template.base.dir option.

true

tools

External "tools" can be specified as list of string name/value (tool name / class name) pairs. Tools, in the Velocity context, are simply Java objects. Tool classes are constructed using a no-arg constructor (or a single-SolrCore-arg constructor if it exists) and added to the Velocity context with the specified name. A custom registered tool can override the built-in context objects with the same name, except for $request, $response, $page, and $debug (these tools are designed to not be overridden).

VelocityResponseWriter Request Parameters

Parameter Description Default value

Parameter	Description	Default value
v.template	Specifies the name of the template to render.
v.layout	Specifies a template name to use as the layout around the main, `v.template`, specified template. The main template is rendered into a string value included into the layout rendering as `$content`.
v.layout.enabled	Determines if the main template should have a layout wrapped around it. True by default, but requires `v.layout` to specified as well.	true
v.contentType	Specifies the content type used in the HTTP response. If not specified, the default will depend on whether `v.json` is specified or not.	without json.wrf: text/html;charset=UTF-8 with json.wrf: application/json;charset=UTF-8
v.json	Specifies a function name to wrap around the response rendered as JSON. If specified, the content type used in the response will be "application/json;charset=UTF-8", unless overridden by `v.contentType`. Output will be in this format (with v.json=wrf): `wrf("result":"<Velocity generated response string, with quotes and backslashes escaped>")`
v.locale	Locale to use with the `$resource` tool and other LocaleConfig implementing tools. The default locale is `Locale.ROOT`. Localized resources are loaded from standard Java resource bundles named `resources[_locale-code].properties`. Resource bundles can be added by providing a JAR file visible by the SolrResourceLoader with resource bundles under a velocity sub-directory. Resource bundles are not loadable under conf/, as only the class loader aspect of SolrResourceLoader can be used here.
v.template.<template_name>	When the "params" resource loader is enabled, templates can be specified as part of the Solr request.

v.template

Specifies the name of the template to render.

v.layout

Specifies a template name to use as the layout around the main, v.template, specified template.

The main template is rendered into a string value included into the layout rendering as $content.

v.layout.enabled

Determines if the main template should have a layout wrapped around it. True by default, but requires v.layout to specified as well.

true

v.contentType

Specifies the content type used in the HTTP response. If not specified, the default will depend on whether v.json is specified or not.

without json.wrf: text/html;charset=UTF-8

with json.wrf: application/json;charset=UTF-8

v.json

Specifies a function name to wrap around the response rendered as JSON. If specified, the content type used in the response will be "application/json;charset=UTF-8", unless overridden by v.contentType.

Output will be in this format (with v.json=wrf):

wrf("result":"<Velocity generated response string, with quotes and backslashes escaped>")

v.locale

Locale to use with the $resource tool and other LocaleConfig implementing tools. The default locale is Locale.ROOT. Localized resources are loaded from standard Java resource bundles named resources[_locale-code].properties. Resource bundles can be added by providing a JAR file visible by the SolrResourceLoader with resource bundles under a velocity sub-directory. Resource bundles are not loadable under conf/, as only the class loader aspect of SolrResourceLoader can be used here.

v.template.<template_name>

When the "params" resource loader is enabled, templates can be specified as part of the Solr request.

VelocityResponseWriter Context Objects

Context Reference Description

Context Reference	Description
request	SolrQueryRequest javadocs
response	QueryResponse most of the time, but in some cases where QueryResponse doesn’t like the request handlers output (AnalysisRequestHandler, for example, causes a ClassCastException parsing "response"), the response will be a SolrResponseBase object.
esc	A Velocity EscapeTool instance
date	A Velocity ComparisonDateTool instance
list	A Velocity ListTool instance
math	A Velocity MathTool instance
number	A Velocity NumberTool instance
sort	A Velocity SortTool instance
display	A Velocity DisplayTool instance
resource	A Velocity ResourceTool instance
engine	The current VelocityEngine instance
page	An instance of Solr’s PageTool (only included if the response is a QueryResponse where paging makes sense)
debug	A shortcut to the debug part of the response, or null if debug is not on. This is handy for having debug-only sections in a template using `#if($debug)…#end`
content	The rendered output of the main template, when rendering the layout (v.layout.enabled=true and v.layout=<template>).
[custom tool(s)]	Tools provided by the optional "tools" list of the VelocityResponseWriter registration are available by their specified name.

request

SolrQueryRequest javadocs

response

QueryResponse most of the time, but in some cases where QueryResponse doesn’t like the request handlers output (AnalysisRequestHandler, for example, causes a ClassCastException parsing "response"), the response will be a SolrResponseBase object.

esc

A Velocity EscapeTool instance

date

A Velocity ComparisonDateTool instance

list

A Velocity ListTool instance

math

A Velocity MathTool instance

number

A Velocity NumberTool instance

sort

A Velocity SortTool instance

display

A Velocity DisplayTool instance

resource

A Velocity ResourceTool instance

engine

The current VelocityEngine instance

page

An instance of Solr’s PageTool (only included if the response is a QueryResponse where paging makes sense)

debug

A shortcut to the debug part of the response, or null if debug is not on. This is handy for having debug-only sections in a template using #if($debug)…#end

content

The rendered output of the main template, when rendering the layout (v.layout.enabled=true and v.layout=<template>).

[custom tool(s)]

Tools provided by the optional "tools" list of the VelocityResponseWriter registration are available by their specified name.

Response Writers Near Real Time Searching