Display Template

From DBSight Full-Text Search Engine/Platform Wiki

Table of contents

Rendering results

After a search, all the results, including pagination, facet search, etc, are stored in an object called "searchResult", which are retrievable from JSP, FreeMarker, and Velocity templates. The javadoc for class "SearchResult" is provided. So theoretically you can use it to do everything.

You can choose JSP, FreeMarker, Velocity as your view technology in this MVC model. By default, DBSight 2.x uses FreeMarker. DBSight 1.x uses Velocity.

Structure of SearchResult

Documents

There will be a list of documents, available method searchResult.getDocs(), in the searchResult object. You can render each value in the documents in several ways

  • Text values
    • Direct Rendering: doc.get("field_name")
    • Highlighted: searchResult.highlight(doc, "field_name")
    • Summarized: searchResult.summarize(doc, "field_name")
  • Date values
    • Get a Date object: doc.getDate("date_field_name")
    • Format the date object: ${date.format('M/d/yyyy hh:mm:ss a', doc.getDate("created_at"))}
  • Number values
    • Get a Float object: doc.getFloat("number_field_name")
    • Format the number object: ${number.format('$#,##0.##', doc.get("number_field_name"))}

Pagination Information

There are 3 values needed to render pagination of the search result:

  • Total number of matched documents: searchResult.total
  • The first document number in current page: searchResult.start, it starts with 0
  • Length of the documents in current page: searchResult.length

Sort By Information

Use searchResult.searchSort or searchResult.getSearchSort(), you can get a list of SearchSort objects, which you can use to render sorting options.

Narrow By Information

Use searchResult.filterResult or searchResult.getFilterResult(), you can get the object FilterResult, which includes informations to render narrowBy links. It has two lists of objects:

  1. FilteredColumn: already filtered columns
  2. FilterColumn: columns for the users to filter on


Freemarker Template

DBSight 2.0 starts to use Freemarker.

Freemarker Introduction

Freemarker is more powerful, although a bit higher learning curve. But you will feel its power if you really need to render some thing in Velocity. Here are some things you should know.

Create a java instance

<#assign keyWords = new("java.util.ArrayList",10)>  //create an ArrayList of initial size 10
<#assign keyWords = new("java.util.ArrayList")>

DBSight added this new keyword into the context.

Loop through a list

 <ul>
   <#foreach kw in keyWords>
     <li><a href="${kw.link}">${kw.word}</a>
   </#foreach>
 </ul>

Define a macro

 <#macro section(title width="90%")>
  <fieldset style="width:${width};">
   <legend><b>${title}</b></legend>
   <#nested>                                          //notice this <#nested>, any content wrapped by the <@section> tag is put here
  </fieldset>
 </#macro>
 ...
 <@section title="a new section", width="45%" />      //call the macro with 2 named parameters
 <@section title="a new section"/>                    //call the macro with 1 named parameter, one using default value
 <@section "a new section", "50%" />                  //call the macro with 2 parameters
 <@section "a new section" />                         //call the macro with 1 parameter, the other one is using default
 <@section "a new section">                           //call the macro with 1 parameter, and the content in the section
   Put any html and freemarker expressions here       //these will be wrapped with the filedset tag, defined in the macro
 </@section>

As you can tell, FreeMarker's macro is more powerful than Velocity's, with default values, nested content, named parameters.

Biggest difference with Velocity

If you come from Velocity like us, you may not enjoy this: In Velocity, if some value is not defined or empty, Velocity will simply print it out. But in Freemarker, an exception will be thrown!

This will affect many places. But let's just get used to it. Not that difficult.

To determine whether a value is set

<#if x?has_content>
  ${x} is not empty
</#if>

Or

${x?if_exists}

Remember it. It'll be used everywhere!


More Detailed Documentation

Reference         http://freemarker.org/docs/ref.html
Full Manual       http://freemarker.org/docs/index.html

Freemarker Formatting Examples

Freemarker has a rich-set of features. Maybe you should bookmark this page:

http://freemarker.sourceforge.net/docs/ref_builtins.html

Before you go there, here are some examples most relevant to DBSight users.

Format a String

${'abc'?substring(1)}             //output bc
${"GreEN mouse"?capitalize}       //output Green Mouse
${doc.get("title")?html}          //escape characters for HTML tags
<#assign test3 = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")>
              //convert a string to DateTime object

More is here, http://freemarker.sourceforge.net/docs/ref_builtins_string.html

Format a number

<#assign x = 1.234>
${x?string("0")}                   //output 1
${x?string("0.####")}              //output 1.234
${12.1?string("000.00")}           //outptu 012.10

More is here, http://freemarker.sourceforge.net/docs/ref_builtins_number.html

Format a date

${lastUpdated?string("yyyy-MM-dd HH:mm:ss zzzz")}

More is here, http://freemarker.sourceforge.net/docs/ref_builtins_date.html

More Freemarker Syntax

Bookmark this page for quick reference, http://freemarker.sourceforge.net/docs/ref_directives.html

If else elseif

<#if x == 1>
 x is 1
<#elseif x == 2>
 x is 2
<#elseif x == 3>
 x is 3
</#if> 

list

<#list seq as x>
 ${x}
 <#if x = "spring"><#break></#if>
</#list>

include

<#include path>

assign

<#assign name=value>

JSP Template

In any template, you can create a file called main.jsp. Actually any file name will be good, as long as the file name extension is jsp.

Then when searching, you can specify jsp rendering by this way:

http://localhost:8080/dbsight/search.do?indexName=<the_index_name>&templateName=<template_name>&fileName=main.jsp

Usually you can put FreeMarker, JSP or Velocity in the same template. This way, JSP can be used to render when there is some special requirement. For example, you can create a pdf.jsp to download results as pdf file.