solr/solr-ref-guide/src/velocity-response-writer.adoc - lucene-solr - Git at Google

 = Velocity Response Writer
 // 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
 //
 //   http://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.

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

 [WARNING]
 ====
 The VelocityResponseWriter and associated /browse UI is deprecated and will be removed in 9.0.

 The functionality has been replaced by a 3rd party plugin available at https://github.com/erikhatcher/solritas.
 ====

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

 [source,xml]
 ----
 <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>
   <lst name="tools">
     <str name="mytool">com.example.MyCustomTool</str>
   </lst>
 -->
 </queryResponseWriter>
 ----

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

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

 `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

 `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. The default is `true`, but requires `v.layout` to specified as well.

 `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.
 +
 The default without `v.json=wrf`: `text/html;charset=UTF-8`.
 +
 The default with `v.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.


 === VelocityResponseWriter Context Objects

 // TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed

 [cols="30,70",options="header"]
 |===
 |Context Reference |Description
 |`request` |{solr-javadocs}solr-core/org/apache/solr/request/SolrQueryRequest.html[SolrQueryRequest] javadocs
 |`response` |{solr-javadocs}solr-core/org/apache/solr/response/SolrQueryResponse.html[QueryResponse] most of the time, but in some cases where QueryResponse doesn't like the request handler's output (https://cwiki.apache.org/confluence/display/solr/AnalysisRequestHandler[AnalysisRequestHandler], for example, causes a ClassCastException parsing "response"), the response will be a SolrResponseBase object.
 |`esc` |A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#EscapeTool[EscapeTool] instance
 |`date` |A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#ComparisonDateTool[ComparisonDateTool] instance
 |`math` |A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#MathTool[MathTool] instance
 |`number` |A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#NumberTool[NumberTool] instance
 |`sort` |A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#SortTool[SortTool] instance
 |`display` |A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#DisplayTool[DisplayTool] instance
 |`resource` |A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#ResourceTool[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.
 |===

 === 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.
	= Velocity Response Writer
	// 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
	//
	// http://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.

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

	[WARNING]
	====
	The VelocityResponseWriter and associated /browse UI is deprecated and will be removed in 9.0.

	The functionality has been replaced by a 3rd party plugin available at https://github.com/erikhatcher/solritas.
	====

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

	[source,xml]
	----
	<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>
	<lst name="tools">
	<str name="mytool">com.example.MyCustomTool</str>
	</lst>
	-->
	</queryResponseWriter>
	----

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

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

	`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

	`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. The default is `true`, but requires `v.layout` to specified as well.

	`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.
	+
	The default without `v.json=wrf`: `text/html;charset=UTF-8`.
	+
	The default with `v.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.


	=== VelocityResponseWriter Context Objects

	// TODO: Change column width to %autowidth.spread when https://github.com/asciidoctor/asciidoctor-pdf/issues/599 is fixed

	[cols="30,70",options="header"]
	\|===
	\|Context Reference \|Description
	\|`request` \|{solr-javadocs}solr-core/org/apache/solr/request/SolrQueryRequest.html[SolrQueryRequest] javadocs
	\|`response` \|{solr-javadocs}solr-core/org/apache/solr/response/SolrQueryResponse.html[QueryResponse] most of the time, but in some cases where QueryResponse doesn't like the request handler's output (https://cwiki.apache.org/confluence/display/solr/AnalysisRequestHandler[AnalysisRequestHandler], for example, causes a ClassCastException parsing "response"), the response will be a SolrResponseBase object.
	\|`esc` \|A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#EscapeTool[EscapeTool] instance
	\|`date` \|A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#ComparisonDateTool[ComparisonDateTool] instance
	\|`math` \|A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#MathTool[MathTool] instance
	\|`number` \|A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#NumberTool[NumberTool] instance
	\|`sort` \|A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#SortTool[SortTool] instance
	\|`display` \|A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#DisplayTool[DisplayTool] instance
	\|`resource` \|A Velocity http://velocity.apache.org/tools/{ivy-velocity-tools-version}/tools-summary.html#ResourceTool[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.
	\|===

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