Document Serving Methods

Default Behavior#

Depending on user browser, Highlighter Server will automatically select the most appropriate method for showing the PDF with search terms highlighted. By default:

  1. Highlighting PDF Viewer will be used if user consumes the service using a modern web browser or a mobile device.
  2. Otherwise, the server will burn highlights into the PDF and return it for showing in browser's default PDF viewer.

Modifying Document Serving Rules#

If you need to modify the above behavior, copy and modify the documentServingPathRules section from defaults.conf to your application.conf. It is a set of rules where matchUserAgent is a regex expression that will be used to find a match in the User-Agent HTTP header sent by the user's web browser. Highlighter will use documentServingPath from the first rule matching, otherwise the default will be used.

Example:

highlighter {
documentServingPathRules = [
{
matchUserAgent = "MSIE [1-9][^0-9]"
documentServingPath = serveBurnedPdf
}
{
matchUserAgent = "Mobile|iP(hone|od|ad)|Android|BlackBerry|IEMobile|Kindle|NetFront|Silk-Accelerated|(hpw|web)OS|Fennec|Minimo|Opera|M(obi|ini)|Blazer|Dolfin|Dolphin|Skyfire|Zune"
documentServingPath = serveViewerHighlightedPdf
}
...
]
documentServingPath = serveBurnedPdf
}

The documentServingPath parameter can specify document serving path directly or reference another configuration parameter (e.g. for reuse) โ€” which is what we do in the default settings defining:

  • serveBurnedPdf
  • serveBurnedPdfInViewer
  • serveViewerHighlightedPdf

The following placeholders can be used in the path โ€” specified within { and } parenthesis:

  • hitsRef - Caching ID for obtaining highlighting meta data, used by Highlighting PDF Viewer.
  • docuRef - Caching ID for obtaining document with highlights burned into it.
  • firstHitPage - First matching page in PDF document
  • originalRequestUrl - Highlighting request URL
  • serviceUrl - URL to Highlighter
  • viewerOptions - Viewer parameter list composed by Highlighter from config options in the "viewer" section.
  • cachedDocUrlIfAvailable - URL to cached original document. Available only if caching is enabled.
  • cachedDocUrlIfCorsIssueDetected - URL to cached original document to be included only if CORS issue is detected.
  • cachedDocUrlIfLocalFile - If the 'uri parameter of the highlighting request specifies a path on the local file system, this URL provides access to the original document through the Highlighter server.
  • request.* - Reference HTTP request parameter using request. prefix (e.g. {request.uri} or {request.query})

If parameter name is followed with the :urlencoded suffix, the value will be encoded for use in URL. For example {request.uri:urlencoded}

Example:

serveViewerHighlightedPdf = "{serviceUrl}/viewer/?file={cachedDocUrlIfLocalFile:urlencoded|cachedDocUrlIfCorsIssueDetected:urlencoded|request.viewUrl:urlencoded|request.uri:urlencoded}&highlightsFile={serviceUrl:urlencoded}{/hits/:urlencoded}{hitsRef:urlencoded}&{viewerOptions}#page={firstHitPage}"