Velocity Response Writer

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

The VelocityResponseWriter has been deprecated and may be removed in a future version of Solr.

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=""></str>
  <lst name="tools">
    <str name="mytool">com.example.MyCustomTool</str>

Configuration & Usage

Template Rendering Protections

Velocity template rendering is largely controlled by the trusted configset flag. Templates built into (the /browse ones) the component library are always available with this component. In a trusted configset, templates in the velocity/ subdirectory of the configset are renderable. Also in a trusted configset, when template.base.dir is specified those templates are renderable.

VelocityResponseWriter Initialization Parameters

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.
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>.

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

Specifies the name of the template to render.

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.

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

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

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

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


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>")


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.

VelocityResponseWriter Context Objects

Context ReferenceDescription
requestSolrQueryRequest javadocs
responseQueryResponse most of the time, but in some cases where QueryResponse doesn’t like the request handler’s output (AnalysisRequestHandler, for example, causes a ClassCastException parsing "response"), the response will be a SolrResponseBase object.
escA Velocity EscapeTool instance
dateA Velocity ComparisonDateTool instance
mathA Velocity MathTool instance
numberA Velocity NumberTool instance
sortA Velocity SortTool instance
displayA Velocity DisplayTool instance
resourceA Velocity ResourceTool instance
engineThe current VelocityEngine instance
pageAn instance of Solr’s PageTool (only included if the response is a QueryResponse where paging makes sense)
debugA 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
contentThe 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.

VelocityResponseWriter Usage

To see results in an HTML user interface on your own collection, try http://localhost:8983/solr/<my collection>/select?q=:&wt=velocity&v.template=browse&v.layout=layout

Or try /browse in the examples techproducts or example/files.