Brava HTML Viewer

Version 2.0

INTEGRATION GUIDE

Table of Contents
Introduction ............................................................................................................................................ 5
Overview ........................................................................................................................................................ 5
Intended Audience ........................................................................................................................................ 5
Organization .................................................................................................................................................. 5
Deployment............................................................................................................................................. 6
Cross-Origin Resource Sharing....................................................................................................................... 7
Working with Documents ........................................................................................................................ 9
Opening a Document ..................................................................................................................................... 9
Upload Document.......................................................................................................................................... 9
Creating a Composition ............................................................................................................................... 12
Single Document View ............................................................................................................................ 15
Single Document View with Banners ...................................................................................................... 15
Document Compare ................................................................................................................................ 16
Creating the Signed Config .......................................................................................................................... 16
Configuration Options ........................................................................................................................... 19
Viewer Configuration and Features ............................................................................................................. 19
Viewer Global Settings................................................................................................................................. 19
Document Attributes ................................................................................................................................... 20
Search .......................................................................................................................................................... 21
Markups .................................................................................................................................................. 22
Redactions ................................................................................................................................................... 23
Text Selection .............................................................................................................................................. 24
Printing ........................................................................................................................................................ 24
PDF/TIFF Export ........................................................................................................................................... 25
Saving Markup Files ............................................................................................................................... 26
Localization ........................................................................................................................................... 28
Integration API ...................................................................................................................................... 29
handleMarkupSaveAs(options) ............................................................................................................... 29
onExportComplete(url, type) .................................................................................................................. 29
getMarkupSaveParams() ......................................................................................................................... 29
Viewer API............................................................................................................................................. 31
Methods .................................................................................................................................................. 31
Events ...................................................................................................................................................... 32
Appendix 1: Page Sizes Schema .............................................................................................................. 33
Appendix 2: Markup List Schema ........................................................................................................... 34
Appendix 3: Redaction Reasons Schema ................................................................................................ 35
Copyright Notices and Acknowledgements ............................................................................................ 36
iii

INTRODUCTION
OVERVIEW

This guide describes how to customize and integrate the Brava HTML Viewer into your enterprise
content management application and your corporate environment, tailored to your users specific
needs.

INTENDED AUDIENCE
This guide is intended for software developers integrating the Brava HTML Viewer into a third party
Enterprise Content Management system and IT developers looking to customize the Brava
HTMLViewer to better fit a particular corporate look and feel. Developers are expected to have
some basic familiarity with HTML, Javascript, JSP, ASPX (Brava .NET installs), XML, and CSS
technologies.

ORGANIZATION
This document has the following major sections:
o
o
o
o
o
o
o

Introduction provides an overview of the information covered in this guide

Deployment describes how to include the viewer on an HTML page
Opening a Document describes how to view a document with the viewer
Document Features describes specific features of the viewer
Saving Markup Files describes the process for saving markup files
Localization describes how to localize strings into different languages
Integration API describes the various integration points to the viewer

BravaHTML_IntegrationGuide

DEPLOYMENT

The Brava HTML Viewer is composed of HTML, Javascript, and CSS files and is injected into HTML
documents by the igc.be.htmlClient() API. This API is defined in the IGC/HtmlClient/be.js
file on your web server (with Brava! Enterprise), or C:\Program Files\IGC\Brava! Enterprise
.NET\BravaServerRest\HtmlClient\be.js (with Brava Enterprise .NET) after installing the
Brava HTML Viewer, and is to be used like this:
<!DOCTYPE html>
<html>
<head>
<!-- To run Brava HTML Viewer in IE, web pages that include Brava HTML Viewer
must be in IE9 standards mode or later. -->
<!-- This meta tag declares what IE compatibility modes may be used for this page. -->
<meta http-equiv="X-UA-Compatible" content="IE=9, IE=10">
...
<!-- The IGC directory may be anywhere on your web server,
but this example assumes it is at the root.
The data-igc="brava" attribute is necessary for
Brava to determine where its client files are located. -->
<script data-igc="brava" src="/IGC/HtmlClient/be.js"></script>
...
<script>
var bravaApi = null;
window.onload = function() {
igc.be.htmlClient({
container: "viewer",
width: "920px",
height: "800px",
// Brava HTML Viewer will select a locale based on the browsers language settings.
// To force selection of a locale, provide the desired locale code like so:
locale: "en-us",
options: {
signedConfigUrl: [some url to the signed config],
[some integration property]: [some integration value]
}
}).then(
function(api) {
bravaApi = api;
console.log('Brava HTML Viewer Loaded');
},
function(errorMessage) {
console.error('Error: ' + errorMessage);
}
);
};
</script>
...
</head>
<body>
<div id="viewer"></div>
</body>
</html>

The igc.be.htmlClient() function requires you to provide an object specifying the container to
place the viewer (it can be either an HTML element id or a reference to a DOM node), the width
and height of the viewer, as well as the URL the viewer should use to retrieve its configuration
data.
The options object specified in the igc.be.htmlClient() call is copied into your IntegrationImpl
object at startup time so you may use anything in there to facilitate your integration
implementations. For example, if for some reason you cannot inject markup save properties into
6

Cross Origin Resource Sharing

the SignedConfig (where they benefit from the integrity protection afforded by the digital
signature there), you can pass them via this options object and have both sets of properties
available to handle the getMarkupSaveParams() integration hook

CROSS-ORIGIN RESOURCE SHARING

Web browsers enforce a same-origin* policy that allows JavaScript from the same origin to share
data, properties, and methods but denies that sharing between scripts and data of different
origins. Under the same-origin policy, Brava HTML Viewer is (by default) not able to use data
received from Brava Server when the two are hosted on different servers. This is where Crossorigin Resource Sharing (CORS) comes in. CORS defines ways for resources to be shared between
different origins in the browser and allows Brava HTML Client to use Brava Server data from a
different origin.
To take advantage of CORS in Brava HTML Viewer, there are two options:
1.

Provide an array of additional origins accessed by Brava HTML Viewer. Normally, the only
origin in the array will be the Brava Server origin:
igc.be.htmlClient({
...
options: {
...
corsServers: [ http://brava-server-hostname:8080/ ]
},
...
}

2. Utilize a proxy page hosted on the same server as Brava HTML Viewer. A proxy page
forwards HTTP requests to the resource designated by the url query string parameter
and returns the response back to the original requester. Here is how to configure Brava
HTML Viewer to use a proxy page:
igc.be.htmlClient({
...
options: {
...
proxyUrl: http://web-server-hostname:8080/proxy/proxy.jsp?url=
},
...
}

* The term origin refers to a combination of protocol, domain name, and port (e.g., http://somedomain:8080/)

WORKING WITH DOCUMENTS

OPENING A DOCUMENT
There are three steps required to view a document:
1. Upload the document to Brava Server
2. Request Brava Server to create a composition
3. Creating the cryptographically signed XML configuration

The Brava HTML Viewer ships with two JSP files (GetSignedConfig.jsp and its helper
LaunchUtils.jsp) for Brava! Enterprise, and one ASPX file (GetSignedConfig.aspx) for Brava!
Enterprise .NET that perform all of these steps. The JSP files for Brava Enterprise can be found in
the BravaServer web application directory and the ASPX file for Brava Enterprise .NET can be
found in the Brava! Enterprise .NET\BravaServerRest directory. The
/IGC/HtmlClient/HTMLDemo.html sample page makes use of these JSP and ASPX files. Reusing
these files is strongly recommended. However, in case you want to handle each step individually,
the following sections describe these three steps.

UPLOAD DOCUMENT
The original source document must be uploaded to Brava Server so it can be converted to a special
intermediate IGC file format. This file format (.XDL) is then further processed by Brava for specific
formats and outputs, including page viewing, thumbnail viewing, PDF and TIFF exports, etc. The
following diagram shows the upload document use case where the integration wants Brava Server
to automatically retrieve the desired document (see the Source element description below):

BravaHTML_IntegrationGuide

To upload a document, XML complying with the following XML Schema should be POSTed to the
Brava Servers upload resource (for example, http://acme.com/BravaServer/upload).
<xsd:element name="UploadRequest" type="UploadRequestType">
<xsd:element name="UploadRequestType">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="ID" type="xsd:string" />
<xsd:element name="DocVersion" type="xsd:string" minOccurs="0"/>
<xsd:element name="Source" type="xsd:anyURI" minOccurs="0"/>
<xsd:element name="Filename" type="xsd:string" minOccurs="0"/>
<xsd:element name="Xref" type="xsd:boolean" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

Element
ID

Legal Values
String

The repository-unique identifier for this document. Future requests to view or operate
against this document must reference this same ID value.
DocVersion

String

Optional. An additional string thats combined with the ID for referencing the document.
Useful for specifying some additional revision information related to the document to allow
multiple copies of the same document to be cached.
Source

URL

Optional. The location from where Brava Server will copy the document to the Brava Server
cache. If not provided, then Brava Server will assume that the document will be sent
separately via the URL found in the response to this POST.
Filename

String

Optional. A filename to use when Brava Server publishes the file. It is useful for certain file
10

Working with Documents

types where a document references its name in headers, footers, etc.
Xref

Boolean

Optional. Indicates whether the document is an xref to the main file.

The response from Brava Server to the above POST will comply with the following XML Schema:
<xsd:element name="UploadResponse" type="UploadResponseType">
<xsd:element name="UploadResponseType">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Cached" type="xsd:boolean" />
<xsd:element name="Upload" type="xsd:anyURI" />
<xsd:element name="UploadStatusURI" type="xsd:anyURI" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>

Element
Cached

Legal Values
Boolean

Whether the document has already been cached by Brava Server.

Upload

URL

The URL that can be used to POST the document to Brava Server in those situations when
the document isnt referenced in the optional Source element above.
UploadStatusURI

URL

The URL that can be used to GET the status of the conversion of the document to XDL. The
response from this resource will contain a single Status element containing a string. As long
as the string isnt either Done or Error the status may change while those two values
represent the final success or failure status of the conversion.

An example UploadRequest might look like:

<UploadRequest>
<ID>4324-24-4324234-34155</ID>
<DocVersion>rev-23</DocVersion>
<Source>http://somefileserver/com/admin-guide.pdf</Source>
<Filename>admin-guide.pdf</Filename>
<Xref>false</Xref>
</UploadRequest>

And the response might look like this:

<UploadResponse>
<Cached>false</Cached>
<Upload>http://acme.com/1434-43-234245/upload</DocVersion>
<UploadStatusURI>http://acme.com/1434-43-234245</UploadStatusURI>
</UploadResponse>

11

BravaHTML_IntegrationGuide
If your integration does not want Brava Server to automatically copy the file and convert it, you
can POST to the UploadResponse.Upload URI like this. Notice how polling against the
UploadResponse.UploadStatusURI URI wont return Done until Brava Server has cached the
document.

CREATING A COMPOSITION
The second step to viewing a document is creating a composition which specifies precisely what is
to be viewed. This is done with a view request. The view request describes how the cached
document should be rendered for a specific user, including things like the desired rendition format,
banners, watermarks, etc all combining together into a single unified composition. A given
document in the cache might be composed in many different compositions so the view request
capabilities are extensive.

12

Working with Documents

The following XML must be POSTed to the BravaServer/request endpoint. All requests must
comply with the following XML Schema. The following sections describe various commonly used
compositions using examples that comply with the XML Schema, and explain incrementally what
each part is used for.
<xsd:element name="Request" type="RequestType">
<xsd:element name="RequestType">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="ClientID" type="xsd:string" />
<xsd:element name="Type" type="xsd:string" />
<xsd:element name="Banners" minOccurs="0" type="BannersType" />
<xsd:element name="DocumentConfig" maxOccurs="unbounded" type="DocumentConfigType" />
<xsd:element name="Composition" type="CompositionType" />
<xsd:element name="CompositionCompare" minOccurs="0" type="CompositionType" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="DocumentConfigType">
<xsd:complexType>
<xsd:attribute name="uid" type="xsd:string"/>
<xsd:sequence>
<xsd:element name="ID" type="xsd:string" />
<xsd:element name="DocVersion" type="xsd:string" />
<xsd:element name="Banners" minOccors="0">
<xsd:complexType>
<xsd:attribute name="uid" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CompositionType">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="DocumentConfig" maxOccurs="unbounded" >
<xsd:complexType>
<xsd:attribute name="uid" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

13

BravaHTML_IntegrationGuide
<xsd:element name="BannersType">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Watermark" type="WatermarkType"/>
<xsd:element name="TopLeft" type="BannerType"/>
<xsd:element name="TopCenter" type="BannerType"/>
<xsd:element name="TopRight" type="BannerType"/>
<xsd:element name="BottomLeft" type="BannerType"/>
<xsd:element name="BottomCenter" type="BannerType"/>
<xsd:element name="BottomRight" type="BannerType"/>
<xsd:element name="LeftTop" type="BannerType"/>
<xsd:element name="LeftCenter" type="BannerType"/>
<xsd:element name="LeftBottom" type="BannerType"/>
<xsd:element name="RightTop" type="BannerType"/>
<xsd:element name="RightCenter" type="BannerType"/>
<xsd:element name="RightBottom" type="BannerType"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="WatermarkType">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Text" type="xsd:string"/>
<xsd:element name="Color" type="xsd:string"/>
<xsd:element name="Opacity" type="xsd:string"/>
<xsd:element name="Editable" type="xsd:boolean"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="BannerType">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Text" type="xsd:string"/>
<xsd:element name="Color" type="xsd:string"/>
<xsd:element name="Editable" type="xsd:boolean"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

The response to a POST of a Request is a RequestResponse adhering to the following XML

Schema:
<xsd:element name="RequestResponse" type="RequestResponseType">
<xsd:element name="RequestResponseType">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="RequestID" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>

This response contains the unique identifier for the requested composition. This RequestID string
must be included in the Config element that is ultimately cryptographically signed by Brava Server
to create the SignedConfig XML that tells the viewer what document to view, what features are
available to the user, and provides many integration configurable options and hooks.
However, before discussing the viewer configuration, provided below are a few example rendering
requests.

14

Working with Documents

Single Document View

This is the simplest of all compositions where only a single document is rendered with no banners
or watermarks. An example request to view the document that was uploaded in the previous
sections example might look like this. Notice that the DocumentConfig.ID and the
DocumentConfig.DocVersion elements match what was referenced in the UploadRequest.ID
and UploadRequest.DocVersion elements.
<Request>
<ClientID>945682</ClientID>
<Type>Raster</Type>
<DocumentConfig uid="0">
<ID>4324-24-4324234-34155</ID>
<DocVersion> rev-23</DocVersion>
</DocumentConfig>
<Composition>
<DocumentConfig uid="0"/>
</Composition>
</Request>

What this request does is create a raster composition based on a single document with a license
slot for client ID 945682.

Single Document View with Banners

The next simplest of composition just adds banners and a watermark, like this:
<Request>
<ClientID>945682</ClientID>
<Type>Raster</Type>
<Banners uid="0">
<Watermark>
<Text>Confidential</Text>
<Color>ff0000</Color>
<Opacity>0.5</Opacity>
<Editable>false</Editable>
</Watermark>
<TopLeft>
<Text>Internal Use Only</Text>
<Color>ff0000</Color>
<Editable>false</Editable>
</TopLeft>
...
</Banners >
<DocumentConfig uid="0">
<ID>4324-24-4324234-34155</ID>
<DocVersion> rev-23</DocVersion>
<Banners uid="0"/>
</DocumentConfig>
<Composition>
<DocumentConfig uid="0"/>
</Composition>
</Request>

15

BravaHTML_IntegrationGuide
This is similar to the first request example, but adds a watermark and a banner in the top left
corner. The rest of the banners are elided for brevity.

Document Compare
In addition to viewing documents, Brava Server is capable of creating a composition based on a
comparison (or diff) of two documents. The request would look similar to this:
<Request>
<ClientID>945682</ClientID>
<Type>Raster</Type>
<DocumentConfig uid="0">
<ID>4324-24-4324234-34155</ID>
<DocVersion> rev-23</DocVersion>
</DocumentConfig>
<DocumentConfig uid="compare">
<ID>7626-77-5437888-52623</ID>
</DocumentConfig>
<Composition>
<DocumentConfig uid="0"/>
</Composition>
<CompositionCompare>
<DocumentConfig uid="compare"/>
</CompositionCompare>
</Request>

CREATING THE SIGNED CONFIG

The Brava HTML Viewer must download at startup an XML file (called the SignedConfig XML)
telling it what document to load, what features should be enabled or disabled, and numerous
configuration values. While you may use a different mechanism other than the supplied
GetSignedConfig.jsp or GetSignedConfig.aspx (Brava .NET) for generating this viewer
configuration XML, the viewer requires that it have a cryptographic digital signature applied to it by
Brava Server to provide robust tamper-protection to prevent man-in-the-middle attacks that might
subversively activate a feature not intended for a particular user, or changing the viewed
document that isnt supposed to be viewed, or changing some banner or watermark setting for
example.
The full XML Schema for the two different configurations is too large to show in its entirety here in
this document. You can find the XML Schema in two files included in the Brava Enterprise SDK,
named DocumentSignedConfig.xml and VideoSignedConfig.xsd. Your integration will need to
create an XML configuration document that complies with this XML Schema. Most of the elements
in the configuration XML are required, and if absent the viewer will not show anything other than a
message stating which parameter was missing.
By far the easiest way to create SignedConfig XML documents is with the GetSignedConfig.jsp
or GetSignedConfig.aspx sample files. To see what the configuration XML for documents and
video contains, apart from examining the corresponding sample files, listen to the HTTP traffic
coming from the browser when using the FlashDemo.html sample page. There are a number of
16

Working with Documents

good, free, HTTP traffic listeners, including Fiddler (http://www.fiddler2.com/fiddler2/), HTTPFox
(https://addons.mozilla.org/en-US/firefox/addon/httpfox/), and Firebug (http://getfirebug.com/).
The following sequence diagram shows this flow (the previous two sections expand out the upload
and composition steps).

To facilitate script reuse, GetSignedConfig.jsp or GetSignedConfig.aspx accepts URL

parameters specifying which document to open, what that documents title is, the documents
author, the current user name, and several other options. An example of launching the viewer to
show a PDF document titled Example for a user named Bob might look like this for Brava!
Enterprise:
http://acme.com/BravaServer/GetSignedConfig.jsp?Document=http://acme.com/doc.pdf&Title=Exam
ple&UserName=Bob

The sample for Brava! Enterprise .NET might look like:

http://acme.com/BravaServer/GetSignedConfig.aspx?Document=http://acme.com/doc.pdf&Title=Exa
mple&UserName=Bob

The next chapter discuses specific features and how integrators can work with them.

17

CONFIGURATION OPTIONS
VIEWER CONFIGURATION AND FEATURES
There are a number of general viewer configuration options discussed below. All elements are
required in the SignedConfig. Important notes are highlighted in red.

VIEWER GLOBAL SETTINGS

Element
Config.RequestID

Legal Values
String

The value returned by the rendition request POST discussed in the previous section
Config.ClientID

String

A pseudo-random number generated by the viewer itself for purposes of reserving license
slots. The viewer will provide the value as a URL parameter to the GET request for the
SignedConfig. NOTE: If the viewer receives a SignedConfig with a different ClientID than its
own ClientID value, it will reject the request to open the document!
Config.ClientIP

String

The IP address of the client. This value is only as accurate as the browsers ability to
determine the users local IP address.
Config.HelpURI

URI

This element must contain a URI pointing to the main help page for the Brava HTML Viewer
for a given installation. A new browser window will be launched pointing to this URI when a
user opens the help from the viewer.
Config.BravaServerURL

URI

This element must contain the URI that contains the network endpoint for Brava Server.
Because of the large number of various network configurations, including intranet and
internet topologies, with and without firewalls, etc., you may need to specify a different
BravaServerURL (say, an internal URL) for some clients that might be using your Brava
Flash Viewer installation from a network without access to that internal network.
Config.UserName

String

This element should contain the users name for purposes of audit event reporting and
markup creation/editing. The actual content of this string is not significant to the viewer, but
may be significant to your integration.
Config.ShowBranding

Boolean

This element must contain a Boolean determining whether the viewer should show any
branding content in the viewer. Brava Server MAY override this setting depending on the
19

BravaHTML_IntegrationGuide
license.
Config.ViewSize

Number

This element must contain a number representing the height of the full-size page bitmaps.
This value can be arbitrarily set, as long as the following conditions are satisfied:

The longest page dimension must be less than 8191

The total number of pixels (width X height) must be less than 16,777,215

Therefore, if the ViewSize (height) of the image is set to 8191, the width of the page will
have to fit within 2048. In other words, a W/H aspect ratio of > 0.25. An aspect ratio larger
than 0.25 will require a smaller ViewSize value to ensure that page bitmaps are not too
large.
Config.ThumbnailSize

100

RESERVED: This element must contain a number representing the height of the thumbnailsize page bitmaps. Note: This value must be 100 as the viewer assumes this value.
Config.PageSizesURI

URI

This element must contain the URI that names an XML document containing a list of valid
page sizes. This list is used in the PDF and TIFF export dialog boxes to populate the pulldown list of page types. See Appendix 1 for the XML Schema of the page sizes document.

DOCUMENT ATTRIBUTES
In order for the viewer to show the human-meaningful document title, it must be provided to the
viewer via Config.Attributes. Each Attribute is a named value pair. While the SignedConfig
can contain an arbitrary number of Attribute elements, the only one the HTML viewer makes use
of is an Attribute with a Label of Title. Future versions of the viewer may make use of
additional attributes.
Element
Config.Attribute.Label

Legal Values
String

This element should contain the human-readable name for the document attribute. For
example, a label of Title or a label of Author.
Config.Attribute.Text

String

This element should contain the human-readable value for the document attribute. For
example, Japan Conference Trip Report or John Doe might be the text for the title or
author attributes. While there is no enforced limit to the length of either the label or text
fields, they will all be displayed by the viewer so practical limitations are present given screen
dimensions and resolution.
20

Integration API

SEARCH
The viewer provides a robust set of search capabilities. The search feature is configured with the
following elements:
Element
Features.Search.MatchCase

Legal
Values
Boolean

Determines whether the default search will match case or not

Features.Search.WholeWord

Boolean

Determines whether the default search will match whole words only or not
Features.Search.Enabled

Boolean

Determines whether searching is allowed. NOTE: even if searching is disabled via this
element, the viewer will still respect the InitialSearch element below and execute that single
search at startup time. However, no other searches will be permitted if this Enabled element
is false.
Features.Search.InitialSearch

String

This element may contain a string literal that should be searched for upon opening the
document. This is useful if your integration provides the ability to find a document based on
some search string, and want to open the viewer showing those strings.
Features.Search.EnableTermHits

Boolean

Determines whether the viewer will provide the user with the option to show/hide search
terms via a checkbox menu item in the search menu.
Features.Search.DefaultTermHits
Determines whether the viewer will initially activate the Enable Term Hit checkbox menu
item in the search menu referenced in the Features.Search.EnableTermHits element above.
NOTE: by disabling the EnableTermHits option integrations can force the users to always or
never see term hits via the DefaultTermHits option!
Features.Search.SearchCap

Integer

The number of search terms to look for at a time. The viewer will pause searching when it
reaches this cap and provide the user with the ability to find the next SearchCap-sized batch
of search hits.

21

BravaHTML_IntegrationGuide

Markups
One of the key features of IGC viewers is allowing users to markup/annotate documents and share
those markups with other users. These markups are stored separately either in Brava Servers
default markup directory or from your Enterprise Content Management system that you are
integrating. These markup files can then be downloaded by other users depending on your
integrations authorization requirements and rendered against the document for collaboration
(editing) or review.
The following elements configure the markups feature of the viewer:
Element
Features.Markups.ChangemarkConfigURI

Legal Values
URI

URI pointing to a Brava Changemark Configuration file. This file describes the available
Changemark types and each types available states and colors.
Features.Markups.EnableEdit

Boolean

Whether the viewer will allow the user to edit markup files. This will show or hide the
Annotation menu item at the top panel of the viewer.
Features.Markups.EnableReview

Boolean

Whether the viewer will allow the user to review markup files. This will show or hide the
Review menu item at the top panel of the viewer.
Features.Markups.EnableMarkupOverwrite

Boolean

Whether the viewer will give the user the opportunity to overwrite an existing markup file
Features.Markups.AlwaysOverrideSave

Boolean

Whether the viewer should suggest to Brava Server (or the integration) that the markup file
being saved should always overwrite any existing files. If false, Brava Server may return
File Exists to a markup save request allowing the viewer to prompt the user to decide
what to do.
Features.Markups.MarkupListURI

URI

This optional element may contain an integration-specific URI that the viewer will use to
GET the catalog of available markup files. If you dont specify this element, Brava Server will
automatically inject a default URL for you that returns all markup files for the viewed
document. Your integration must respond with an XML document complying with the
schema found in Appendix 2.
Features.Markups.MarkupSaveURI

URI

This optional element may contain an integration-specific URI that the viewer will use to
POST markup files to have them saved. If you dont specify this element, Brava Server will
automatically inject a default URL for you that will save the POSTed markup file to its
markup file cache. Your integration must handle and reply to a POST of XML complying with
22

Integration API
the XML Schema found in Appendix 2.
Features.Markups.EnableMultiPartSave

Boolean

Determines whether the viewer will issue a multipart POST when saving markup files. Used
only for integrations that require multi-part markup saves.
Features.Markups.Markup

MarkupType

Zero or more MarkupType elements (see Appendix 2 for the applicable XML Schema). The
viewer will preload all markups specified here, allowing 0..n markups for review, and only
0..1 markups for edit.

In addition, the viewer allows integrators to individually show/hide specific markup menu items:
Element

Legal Values

Features.Markups.Menu.EnableNew

Boolean

Whether the New menu item is visible.

Features.Markups.Menu.EnableOpen

Boolean

Whether the Open menu item is visible.

Features.Markups.Menu.EnableSave

Boolean

Whether the Save menu item is visible.

Features.Markups.Menu.EnableSaveAs

Boolean

Whether the Save As menu item is visible.

Features.Markups.Menu.EnableClose

Boolean

Whether the Close menu item is visible.

REDACTIONS
In addition to support markup annotations against a document, the Brava HTML Viewer also allows
users to create redactups that when burned-in against a document by Brava Server (exported to
a PDF or TIFF) removes all traces of the underlying characters from the redacted document. The
available configuration elements are:
Element

Legal Values

Features.Redactions.Enabled

Boolean

Whether the viewer will allow the user to create redactups against the current document.
This will show or hide the Redaction menu item at the top panel of the viewer.
23

BravaHTML_IntegrationGuide
Features.Redactions.RedactionReasonsURI

URI

URI pointing to a Brava Redaction Reasons file. This file describes the available reasons that
the user may choose to associate with each redaction. If this is an empty URL () then the
user will be able to type any arbitrary reason for the redaction. Otherwise, the viewer will
limit the user to only those redaction reasons found in the file at this endpoint. See
Appendix 3 for the redaction reasons XML Schema.

TEXT SELECTION
The Brava HTML Viewer allows the user to select document text to place it in the users clipboard
for pasting into other applications (email, other document editors, etc.) Due to security restrictions
though, the Brava HTML Viewer is NOT permitted to directly modify the users OS clipboard.
Therefore, this tool will present the user with a dialog with the selected text, allowing the user to
manually copy the text into their clipboard themselves. The available configuration elements for
the text selection feature are:
Element

Legal Values

Features.TextSelect.Enabled

Boolean

Whether the viewer will allow the user to select document text. This will show or hide the
text selection tool icon on the top panel of the viewer.

PRINTING
The Brava HTML Viewer allows the user to print the currently viewed document along with any
markups or redactups applied. After the user is permitted to select what to include in the print job
(including redaction reasons and Changemark summaries), Brava Server will create a PDF of the
document then the viewer will download the PDF and use the native system to attempt to print the
newly created PDF. Depending on the users specific browser and available plugins, the actual print
behavior may be different. The following print configuration elements are available:
Element
Features.Print.Enabled

Legal Values
Boolean

Whether the viewer will allow the user to print the current document. This will show or hide
the print icon on the top panel of the viewer.

24

Integration API

PDF/TIFF EXPORT
The viewer allows the user to export the current document to a new PDF or TIFF document. This is
commonly done to share the document with someone who doesnt have access to the Brava
viewers. The available PDF/TIFF export configuration elements are:
Element
Features.Publish.Enabled

Legal Values
Boolean

Whether the viewer will allow the user to print the current document. This will show or hide
the Publish menu item on the top panel of the viewer.
Features.Publish.EnablePDF

Boolean

Whether the viewer permits publishing to PDF

Features.Publish.EnableTIFF

Boolean

Whether the viewer permits publishing to TIFF

25

BravaHTML_IntegrationGuide

SAVING MARKUP FILES

A common integration point for Brava viewers is changing how markup files are stored in the
server. To effectively integrate in this functional area you must understand the flow of the viewers
save feature and the various decision points and influencing properties. See the following flow
chart for the markup save flow:

In the flow chart above, the colored boxes represent a dialog box that is shown to the user. The
main content of those dialog boxes is returned by the integration in the Message element of the
MarkupType element.
The type of POST the viewer uses can be configured via the Features.Markups.EnableMultiPartSave
configuration property. If this property is set to true, then the viewer will use a multi-part POST,
with all of the information as POST variables (including the markup file metadata like title, date,
etc., the markup file, as well as the signed config XML itself). Otherwise, the viewer will use
ordinary HTTP POST messages.
26

Integration API
In the first POST to save a markup file, the viewer will set the Overwrite element to whatever is in
the SignedConfigs AlwaysOverrideSave element and the SaveAs element to true if the user is
executing a save-as type operation versus an ordinary save operation. It is entirely up to the
integration to honor the intent of these properties (specifically, if you have set the
AlwaysOverrideSave property to true, then you probably dont want to send back a FileExists
since the viewer will then prompt the user whether or not to overwrite!)
Prior to sending the markup file to the server, the viewer will call
IntegrationImpl.getMarkupSaveParams() to gather any integration-specific properties that cant be
adequately provided in the SignedConfig. The getMarkupSaveParams() function must return an
array of objects, where each object has a name property and a content property.

27

BravaHTML_IntegrationGuide

LOCALIZATION

Brava HTML Viewer 2.0 has built-in support for the following locales:
Locale

Locale Code

English (US)

en-us

Chinese

zh

Spanish

es

German

de

French

fr

Japanese

ja

Korean

ko

By default, Brava HTML Viewer selects a locale based on the browsers language settings. To force
a given locale, provide a locale setting when you call the igc.be.htmlClient() method. An
example can be found in the Deployment section of this guide.
Integrations that need their own localized strings can start by uncommenting the localizationrelated lines in HtmlClient/integration/IntegrationImpl.js and checking out the example localization
modules in the HtmlClient/integration/nls directory.

28

Integration API

INTEGRATION API

The Brava HTML Viewer currently exposes only a small number of integration extension points.
Inside HTMLClient/integration there are two files: IntegrationAPI.js and
IntegrationImpl.js. The first file defines all of the integration extension hooks while the second
file is where you need to override the implementation in IntegrationAPI.js to provide your own
implementation. By not providing an alternative implementation, the viewer will use the default
found in the IntegrationAPI.js. However, the viewer will ALWAYS load IntegrationImpl.js
and rely on the Dojo frameworks inheritance mechanism to resolve the various functions.
The following sections describe each of the available integration API functions.

handleMarkupSaveAs(options)
This function is called by the viewer when it needs to prompt the user for a new markup filename.
By default it will just show the user the MarkupSaveAsDialog() that is built into the core viewer,
but integrations can override this behavior to show their own markup save dialog. The options
argument will contain some number of properties subject to change with each release of the
viewer.

onExportComplete(url, type)
This function is called when the users request to export the current document to either PDF or
TIFF has completed and the document is available on the server. The first argument passed
contains the URL on the server of the export document, and the second argument contains a string
describing the format of the exported document (it will either be PDF or TIFF). By default it will
just show the user a PromptDialog that when the user clicks OK it opens the URL in a new
browser window, but integrations can override this behavior to do something else with the URL,
including calling a server function to save the document back into the enterprise content
management system or email the URL to a distribution list, for example.

getMarkupSaveParams()
This function is called just before a markup file is save to the server. In situations where additional
save properties cant be provided in the signed config, this function allows integrations to specify
additional properties provided to the server as part of the save POST message. It needs to return
an array of Objects, where each Object contains a name property and a content property.

29

VIEWER API

The Brava HTML Viewer exposes a Viewer API which is completely asynchronous. Every method in
the API returns a promise representing a deferred result, and each promise returned by the API
has a then() method:
then(resultHandler, errorHandler)
The resultHandler signature is: function(result) { }
The errorHandler signature is: function(errorMessage) { }
The igc.be.htmlClient() method returns a promise of viewer initialization, and the result is a
reference to the viewer API:
igc.be.htmlClient(initializationOptions).then(function(bravaApi) { },
function(errorMessage) { });

The following are methods and events supported by the API:

Methods

Method Name

Description

Properties

getPageCount()

resolves with the total number of

pages in the document

getCurrentPage()

resolves with the current page

number

changePage(pageNumber)

tells the viewer to go to the

specified page number and
resolves with an object containing
the available properties:

hasNext,
hasPrevious, or
pageNumber

close(options)

tells the viewer to close and

resolves when operation is
completed. The options parameter
is optional and may contain the
following properties:

allowCancel,
on(eventName,
eventHandler), or
on()

allowCancel

a boolean value specifying

whether the user may cancel the
close operation in the case where
there is a modified, unsaved
markup open for edit. If the user
cancels the operation, the
errorHandler of the close()
promise will be called and passed
an instance of igc.be.CancelError
31

BravaHTML_IntegrationGuide
on(eventName,
eventHandler)

attaches an event handler for the

specified event

on()

a special method that does not

return a promise but rather a
handle for the attached event
handler. To remove an event
handler, simply call the remove()
method of the handle object

Events

Event Name

Description

PageChanged

Fired when the viewer changes pages. The event value is an object
containing the following properties: hasNext, hasPrevious, and
pageNumber.

PrintRequested

Fired when a print is attempted.

32

Copyright Notices and Acknowledgements

APPENDIX 1: PAGE SIZES SCHEMA

<xsd:element name="PageSizes" type="PageSizesType" />

<xsd:complexType name="PageSizesType">
<xsd:sequence>
<xsd:element name="Page" type="PageType" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="PageType">
<xsd:sequence>
<xsd:element name="Label" type="xsd:string" />
<xsd:element name="Unit" type="xsd:string" />
<xsd:element name="Width" type="xsd:decimal" />
<xsd:element name="Height" type="xsd:decimal" />
</xsd:sequence>
</xsd:complexType>

A PageType describes a single page format, including its name (the Label), the unit of measure,
and the width and height in those units of the page size. For example, for a standard 8 x 11
page, the PageType element might look like:
<PageSizes>
<Page>
<Label>Letter</Label>
<Unit>inches</Unit>
<Width>8.5</Width>
<Height>11</Height>
</Page>
</PageSizes>

33

BravaHTML_IntegrationGuide

APPENDIX 2: MARKUP LIST SCHEMA

<xsd:element name="Markups" type="MarkupsType" />

<xsd:complexType name="MarkupsType">
<xsd:sequence>
<xsd:element name="Markup" type="MarkupType" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="MarkupType">
<xsd:sequence>
<xsd:element name="URI" type="xsd:string" />
<xsd:element name="Title" type="xsd:string" />
<xsd:element name="Author" type="xsd:string" />
<xsd:element name="Date" type="xsd:int" />
<xsd:element name="OpenForEdit" type="xsd:boolean" minOccurs="0" />
<xsd:element name="Message" type="xsd:string" minOccurs="0" />
<xsd:any minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>

A MarkupType describes a collection of markup entities that are applied to a particular document
by an author. At a minimum every MarkupType MUST specify a URI, a Title, an Author, and a
Date. However, some integrations may add arbitrary other elements for extensibility purposes on
account of the xsd:any.

34

Element

Description

URI

The URI for the IGC markup file itself

Title

The title label for the markup file. With the default server file
system integration the title is the path-less filename on the
server.

Author

The author of the markup file. The default server file system
integration does not support authors so this field could be
none.

Date

The last modified date of the markup file.

OpenForEdit

When a MarkupType element is provided in the SignedConfig

for purposes of preloading markups, this element determines
whether the markup is opened for edit or only for review. The
viewer will open for edit ONLY the first such MarkupType,
ignoring any subsequent open-for-edit entities.

Message

An optional message for the user when a MarkupType XML is

returned from an integration when saving a markup file.

x sd:any

A place where integrations are formally permitted to add

additional information relating to the markup. It could contain
user credentials, database IDs, etc. and the viewer is not
allowed to make any assumptions about its contents, and must
include this information when saving a markup file.

Copyright Notices and Acknowledgements

APPENDIX 3: REDACTION REASONS SCHEMA

The redaction reasons are stored in JSON files. The file contains an array of redaction reason
objects, with each redaction reason object containing the redaction code, the redaction short
description, and the redaction long description. The viewer ships with a number of example
redaction reason JSON files. Here is an example:
[

},
{

"code" : "Attorney-Client",
"short" : "Attorney-client Privilege",
"long" : "Attorney-Client Privilege - Information reflects legal advice"
"code" : "First Amendment",
"short" : "First Amendment Rights Privilege",
"long" : "First Amendment Privilege. Protected by First Amendment Rights."

35

BravaHTML_IntegrationGuide

COPYRIGHT NOTICES AND ACKNOWLEDGEMENTS

This software includes third party component software distributed by IGC to you pursuant to
specific third party license agreements, whose terms and conditions are as set forth in your license
agreement with IGC and/or the Terms and Conditions of Embedded Products.
Below please find the applicable copyright notices required by such third party licenses:

Copyright 2005-2006, The Dojo Foundation.

Acknowledgements:

36

This software includes Dojo Toolkit (https://dojotoolkit.org/license