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:

Highlighting PDF Viewer will be used if user consumes the service using a modern web browser or a mobile device.
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}"