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