Professional Documents
Culture Documents
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
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
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/)
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
Boolean
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
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.
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
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>
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
What this request does is create a raster composition based on a single document with a license
slot for client ID 945682.
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>
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.
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 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
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
Boolean
Boolean
Boolean
Boolean
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
Boolean
25
BravaHTML_IntegrationGuide
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) { });
Methods
Method Name
Description
Properties
getPageCount()
getCurrentPage()
changePage(pageNumber)
hasNext,
hasPrevious, or
pageNumber
close(options)
allowCancel,
on(eventName,
eventHandler), or
on()
allowCancel
BravaHTML_IntegrationGuide
on(eventName,
eventHandler)
on()
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
32
<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
<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
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
OpenForEdit
Message
x sd:any
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
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:
Acknowledgements:
36