11 Web View Export Javascript API

This chapter describes how the output produced by Web View Export (EXH5) includes references to Javascript files that provide functionality within the exported content. These files also present an API for users to implement customized integration and interaction with that output.

This chapter contains the following sections:

11.1 The Global OIT Object

Web View Export's API functions are implemented as methods of a global object named OIT. Similar to the $ object used by jQuery, all interaction by third party scripts with Web View Export content is through this object. This prevents name collisions between any OIT functions and those in scripts written by other parties.

11.2 Client-side Display Options

Some aspects of the Web View Export display are controlled through the OIT.document.setOptions() function. Note that these will not affect conversion-time behavior.

11.3 Client-side Control

It's very possible that a consumer of Web View Export output, having implemented a web application with their own user interface elements, might not want to rely on controls provided by us (e.g., navigation controls, scrollbars, statusbar, etc.).

Web View Export provides a basic API for control of the navigation of its content, through which a customer may implement their own interface to control the users' interaction with content rendered by Web View Export.

These methods are accessed from objects under the OIT object:

  • OIT.archive: This object allows the application to listen to events related to archive files.

  • OIT.attachments: This object allows the application to listen to events related to email attachments.

  • OIT.document: Methods of this object control zooming, searching, and selection of the content.

  • OIT.highlights: Management of highlighted text, cell ranges, or rect ranges.

  • OIT.hyperlinks: This object allows the customer to listen to events related to hyperlinks.

  • OIT.local: Localized user interface strings.

  • OIT.pages: Methods of this object control navigation through the pages of the document.

  • OIT.toolbars: This object allows the application to add custom toolbars to the view.

  • OIT.view: This object provides control over the view area.

11.4 Ranges

Specialized ranges are used throughout the Web View Export API.

11.4.1 TextRange

A TextRange is a specialized range that tracks a range of text by ACC (actual character count).

Field Type Description

type

String

The range type: "text".

acc

Number

The starting ACC for the range.

accend

Number

The ending ACC for the range.

11.4.2 CellRange

A CellRange is a specialized range that tracks a cell or range of cells in a spreadsheet or database table.

Field Type Description

type

String

The range type: "cell".

page

Number

The 0-based index of the page containing the range.

section

Number

The 0-based index of the section containing the range (includes hidden pages)

c1

Number

The 0-based index of the starting column for the range.

r1

Number

The 0-based index of the starting row for the range.

c2

Number

The 0-based index of the ending column for the range. For single column ranges, this will be equal to c1.

r2

Number

The 0-based index of the ending row for the range. For single row ranges, this will be equal to r1.

11.4.3 RectRange

A RectRange is a specialized range that tracks a point or rectangular range in a drawing or bitmap.

Field Type Description

type

String

The range type: "rect".

page

Number

The 0-based index of the page containing the range.

section

Number

The 0-based index of the section containing the range (includes hidden pages)

left

Number

The x coordinate of the left edge of the rectangle.

top

Number

The y coordinate of the top edge of the rectangle.

right

Number

The x coordinate of the right edge of the rectangle. For point ranges, this will be equal to left.

bottom

Number

The y coordinate of the bottom edge of the rectangle. For point ranges, this will be equal to top.

units

String

Units for the left, top, right, and bottom properties. Must be one of: "px" (pixels), "tw" (twips). If not specified, the default value of "px" is used.

11.5 OIT.view

The OIT.view functions manage the rectangular area inclusive of toolbars and the displayed document itself, for a document that has been loaded into a DOM element of a host web page.

11.5.1 OIT.view.attach

OIT.view.attach( containerElem )

This attaches the Web View to an element in a page.

  • containerElem: A DOM node, typically for a <div> element, that will contain the Web View of files loaded through subsequent calls to OIT.document.load().

HTML File Example

<body>
...
<div class="myViewContainer" id="container"></div>
...
</body>

Javascript Example

var viewContainer = document.getElementById("container");
OIT.view.attach(viewContainer);
...
OIT.view.load("primary_output_file.html");

11.5.2 OIT.view.detach

OIT.view.detach()
 

Detaches Web View and removes any Web View related content from the page. After calling this function, OIT.view.attach() must be called again before loading another document.

11.5.3 OIT.view.load

OIT.view.load( url )

This loads a WebView document into an element on the page previously specified by OIT.view.attach().

  • url: The url of a primary output file produced by Web View Export. This file must have been produced in Ajax mode.

Note:

This function uses Ajax methods to load the output of Web View Export into a container on the current page. This function will fail if OIT.view.attach was not called first, to specify the container into which the web view may be loaded.

If the file whose URL is provided was not produced by Web View Export, or produced without the document structure option set to one of the Ajax modes, this function will fail.

11.5.4 OIT.view.unload

OIT.view.unload()

Unloads a Web View Export document previously loaded via OIT.view.load. It is not necessary to call this function when viewing successive documents in a single view; loading a new document into a view will automatically cause the previous document to be unloaded.

11.5.5 OIT.view.fitToContainer

OIT.view.fitToContainer()

This function resizes the web view to fill the dimensions of the container to which it has been attached. It is only necessary to call this function when the container has been resized independently of the browser window.

11.5.6 OIT.view.width

OIT.view.width( [x] )
  • x - An optional CSS size value for the new width of the web view. A numeric value will be interpreted as a pixel value.

Return Value

A number representing the width of the current web view in pixels, including any toolbars.

11.5.7 OIT.view.height

OIT.view.height( [y] )
  • y - An optional CSS size value for the new height of the web view. A numeric value will be interpreted as a pixel value.

Return Value

A number representing the height of the current web view in pixels, including any toolbars.

11.5.8 OIT.view.info

OIT.view.info()

Returns an object containing information about the Web View export process and the converted document. This object contains the following fields:

  • filename: The filename of the original input file, if available

  • fi: The integer FI id for the input document. See SCCFI.H in the WebView sdk/common directory for a list of possible FI values.

  • fistring: The name of the input document's format id.

  • product: The name of the OIT product that generated the output (typically "Outside In® Technology").

  • version: The version number of the OIT product that generated the output.

  • libversion: The version number of the API's Javascript library (oit.js)

Return Value

The info object for the currently loaded document.

11.6 OIT.document

This section describes the OIT.document class.

11.6.1 OIT.document.properties

OIT.document.properties()

Returns the document properties object, which contains the document properties from the input document. This object may contain any combination of the following fields:

  • general.title: The document title

  • general.author: The document author name

  • general.company: The document company

  • general.subject: The document subject

  • general.keywords: The document keywords

  • general.category: The document category

  • general.creationDate: The date the document was created

  • general.lastSaveDate: The date the document was last saved

  • statistics.backupDate: The date the document was last backed up

  • statistics.completedDate: The date the document was completed

  • statistics.charCount: The number of characters in the document

  • statistics.pageCount: The number of pages in the document

  • statistics.wordCount: The number of words in the document

  • statistics.byteCount: The number of bytes in the document

  • statistics.lineCount: The number of lines in the document

  • statistics.paraCount: The number of paragraphs in the document

  • statistics.slideCount: The number of slides in the document

  • statistics.hiddenSlideCount: The number of hidden slides in the document

  • statistics.noteCount: The number of notes in the document

  • statistics.charCountWithSpaces: The number of characters in the document, including spaces

  • statistics.editMinutes: The total number of minutes spent editing the document

  • statistics.lastPrintDate: The date the document was last printed

  • statistics.lastSavedBy: The person who last saved the document

  • statistics.revisionDate: The date of the current document revision

  • statistics.revisionNumber: The current revision number

  • statistics.versionDate: The date of the document version

  • statistics.versionNumber: The document version number

  • other: An array of name/value pairs for any document properties not included in the above fields. Each entry in this array is an object with "name" and "value" properties.

Return Value

The document properties object for the currently loaded document.

11.6.2 OIT.document.externalData

OIT.document.externalData()

Returns an object containing the external data added to the web view at the time it was generated. These values are set during the export process via the EXAddKeyValue API function.

For example, if the following call was made at the time a file was exported:

EXAddKeyValueInt( hExport, (VTLPCSTR)"UserId", 42 );

Then the following Javascript statements would be possible in the browser:

var data = OIT.document.externalData();
if( data )
  alert( data.UserId );  // displays "42"

Return Value

An object containing key/value data applied via the Export API, or undefined if no such data is available.

11.6.3 OIT.document.setOptions

OIT.document.setOptions( options )

Initializes the viewer with the specified options.

options: An object with zero or more of these fields set:

Field Description Default Value

disableAnimation

A boolean flag controlling whether animations are enabled for various transitions such as scrolling. If true, animations will be disabled. Animations are enabled by default, except in mobile browsers.

false for desktop browsers

true for mobile browsers

memoryModel

A string value that affects how much memory is used to store downloaded pages in the browser. When this memory limit is exceeded, page content may be discarded from memory but will be reloaded from the server on demand. Note that this is a soft limit, and may be exceeded under certain circumstances.

This option does not have any effect unless the SCCOPT_OUTPUT_STRUCTURE option is set to either SCCWV_STRUCTURE_AJAX_CHUNKED or SCCWV_STRUCTURE_AJAX_STREAMING.

May have any of the following values: "none", "large", "small", "micro". By default, set to "large" for desktop browsers and "small" for mobile browsers. "none" removes any limits on memory. "micro" places a very small limit on memory, and is mainly useful for testing purposes.

"large" for desktop

"small" for mobile

outputBaseUrl

Sets a base URL for secondary files when the primary output file is loaded via OIT.view.load.

none

detectBaseUrl

(boolean) This option controls whether or not the library will attempt to infer the base URL path for secondary files (JSON, PNG, HTML) when the primary HTML output file is loaded via OIT.view.load. Base URL detection occurs only if the following conditions are all true:
  • detectBaseUrl is not set to false

  • An absolute path was not specified as the output base URL when the HTML was generated

  • The URL path to the primary output file does not match the internal URLs to secondary files.

true

emailHeaderStyle

If specified, the value for this option must be an object that contains one or more CSS properties to apply to the header area that is displayed with email messages. These values override the default properties.

The supported properties are limited to color, font, and background properties.

Property names must be specified as they would in Javascript rather than in a CSS file; i.e., the size of a font is specified as "fontSize" instead of "font-size". Property values are specified as normal CSS strings.

Examples:

OIT.document.setOptions( {
  emailHeaderStyle: { 
     fontSize: "9pt", 
     fontFamily: "Times, serif", 
     background: "#ffff88" }
  });

OIT.document.setOptions( {
  emailHeaderStyle: {
    font: "bold 12px Arial, sans-serif",
    color: "red" }
  });
 

removeExtraEmailHeaders

A boolean value; used in the display of email headers. If this option is set to true, the full set of additional email headers (normally indicated by the presence of a clickable gear icon) is not available to the user. The gear icon is hidden.

false

doubleClickInterval

A numeric value specifying the maximum interval, in milliseconds, between subsequent mouse clicks that will trigger a double-click event.

500

centerPages

A boolean value indicating whether pages should be centered in the view. If this value is false, pages will be aligned to the left edge of the view.

true

showHighlightLabels

A boolean value indicating whether highlight labels should be visible

true

highlightLabelFontFamily

A string value containing a CSS font family to use for highlight labels.

"Geneva,Tahoma,Verdana,Helvetica,Arial,sans-serif"

highlightLabelFontSize

A string value containing a CSS font size to use for highlight labels. Note that the label font may be reduced from this size to allow the label to fit within the highlight.

"10pt"

highlightActivationBoxColor

A string value containing a CSS color string to use for the highlight activation box, or null to prevent the activation box from being drawn.

"rgba(51,153,238,0.5)

redactionColor

A CSS color string to use for redactions. The redaction rectangle will use this color and the label (if present) will use the inverse of this color. Setting this option will automatically change the color of all existing redactions.

black

redactionFillColor

A CSS color string to use to fill the rectangular area occupied by compound rectangular redactions. Specifying null for this option will remove the redaction fill color. The redacted content within the rectangular range will use the redactionColor option regardless of the value of this option.

null

contentTimeout

The maximum time in milliseconds to wait for additional content to become available when viewing a document in streaming mode. This timeout is used when a document is being viewed as it is exported. If the server fails to respond within this time, an error message is displayed and no further content will be downloaded. The default content timeout is 20 seconds (contentTimeout=20000).

null

showSlideNotes

Boolean value that determines whether slidenotes are to be shown (for presentation file types only).

false

presentationMode

A string value that affects whether presentation documents display hidden slides. May have any of the following values: "normal", "slideshow". In "slideshow" mode, if OIT.pages.moveto is called with a specified destination page that is hidden, the display will move to the next non-hidden page. If there are no non-hidden pages after the specified page, the display will move to the last non-hidden page. The return value from the method will indicate the page displayed, not the page requested.

“normal”

nochrome

A boolean value that may be set to true to disable browser chrome (background color, page shadow, page margin, and the tab bar). Setting nochrome to true automatically sets scrollMode to 'single'.

false

scrollMode

A string value that controls how the user navigates between pages. When set to the default value, 'vertical', multiple word processor, vector, or bitmap pages are displayed in a vertically scrollable list. This option may also be set to 'single', in which case a single page is displayed at a time and the keyboard, tab bar, navbar, or API functions must be used to navigate between pages.

'vertical'

11.6.4 OIT.document.zoom

OIT.document.zoom( [zoom] )

Sets or retrieves the zoom factor for the view. Calling this function will cause a 'zoom' event to be dispatched if the zoom factor changes. If zoom is called with no arguments, it simply returns the current zoom factor.

zoom: May be a numeric zoom factor (1.0 = 100%, 1.5 = 150%, etc.) or one of the following strings:

Value Description

"pagewidth"

Set the zoom factor so the widest page in the document will fill the view from left to right.

"pageheight"

Set the zoom factor so the tallest page in the document will fill the view from top to bottom.

"page"

Set the zoom factor so the largest page in the document will fit within the view.

“mobile”

The default zoom mode for mobile devices. Spreadsheet, database and archive files are displayed at 100%, and other file types are zoomed so the page will fit within the width of the view.

Return Value

Returns a number indicating the current zoom factor (1.0 = 100%, 1.5 = 150%, etc.)

11.6.5 OIT.document.zoomIn

OIT.document.zoomIn()

Zooms in one step. Calling this function will cause a 'zoom' event to be dispatched if the zoom factor is not already at the maximum.

Return Value

Returns a number indicating the current zoom factor (1.0 = 100%, 1.5 = 150%, etc.)

11.6.6 OIT.document.zoomOut

OIT.document.zoomOut()

Zooms out one step. Calling this function will cause a 'zoom' event to be dispatched if the zoom factor is not already at the minimum.

Return Value

Returns a number indicating the current zoom factor (1.0 = 100%, 1.5 = 150%, etc.)

11.6.7 OIT.document.rotate

OIT.document.rotate( angle )

Rotates all of the pages in the document by the specified angle. If rotate is called with no arguments, it simply returns the current rotation angle. Note that rotation is not supported for all file types. Calling rotate() for a display engine that does not support rotation will have no effect and the angle 0.0 will always be returned.

angle: The angle to rotate the pages, in degrees. Must be an integer multiple of 90 degrees.

Return Value

Returns a number indicating the current rotation angle.

11.6.8 OIT.document.showHidden

OIT.document.showHidden( [mode] )

For spreadsheet and database files, makes hidden rows and/or columns visible. This affects the current sheet only and is not saved when the current sheet changes. When a different spreadsheet page is displayed, it will behave as if OIT.document.showHidden( "none" ) was called.

mode: The new visibility mode. Must be one of the following:

  • all - Makes hidden and narrow rows and columns visible by increasing their width to a preset minimum.

  • none - Resets all rows and columns to their default height/width. Hidden rows and columns are set to 0 height/width.

  • rows - Makes hidden and narrow rows visible by setting them to a minimum height. Columns are not affected.

  • columns - Makes hidden and narrow columns visible by setting them to a minimum width. Rows are not affected.

11.6.9 OIT.document.find

OIT.document.find( searchTerm, callbackFn, [caseSensitive], [direction] [startacc] )

Performs an asynchronous search for the specified text string in the specified direction, starting at the current position.

searchTerm: A string containing the search term to look for.

callbackFn: This function will be called when the search term is found. A TextRange is passed as the only parameter to the callback function.

If the search term is not found anywhere in the specified direction, the callback function will be called with no arguments.

caseSensitive: A boolean value specifying whether searches are case sensitive. May be true (the default) or false.

direction: A string value specifying the search direction from the current text position. May be "down" (the default) or "up".

startacc: The starting ACC (actual character count) for the search operation. If not specified, defaults to the end of the document if direction is "up" or the beginning of the document otherwise. To continue searching from the location of the previous OIT.document.find result, pass in (range.acc+1) for startacc (or (range.acc-1) if direction is 'up').

11.6.10 OIT.document.findAll

OIT.document.findAll( searchTerm, callbackFn, [caseSensitive] )

Performs an asynchronous document-wide search for the specified text string.

searchTerm: A string containing the search term to look for.

callbackFn: This function will be called each time the search term is found. A TextRange is passed as the only parameter to the callback function. If the callback function returns false, the search operation will be aborted.

If the search term is not found anywhere in the specified direction, the callback function will be called a single time with no arguments.

caseSensitive: A boolean value specifying whether searches are case sensitive. May be true (the default) or false.

11.6.11 OIT.document.getRawText

OIT.document.getRawText( callbackFunction )

callbackFunction: A Javascript function provided by the caller that will be called asynchronously by the Web View Javascript library. The function must conform to the following prototype:

function rawTextCallback( buffer, acc )
  • buffer: Javascript string containing utf8-encoded Unicode text from the document

  • acc: The acc of the first Unicode character in the text buffer. The acc of the last character in the buffer is equal to (acc + buffer.length - 1).

This function will be called repeatedly until all of the text of the file has been provided, unless the rawTextCallback function returns a boolean value of false, in which case the text retrieval will stop and no further calls will be made to the callback function. When the end of the document text is reached, the callback function will be called a single time with no arguments.

11.6.12 OIT.document.highlight

OIT.document.highlight( searchTerm, style, [callbackFn], [caseSensitive], [properties] )

Performs an asynchronous document-wide search for the specified text string and adds a highlight anywhere it occurs.

searchTerm: A string containing the search term to look for.

style: The style to apply to each highlight. A CSS string that may include the color and/or background-color properties. Any other properties are ignored.

callbackFn: This (optional) function will be called each time the search term is found. The function will be called with two arguments: a TextRange and a highlight id. If the callback function returns false, the search operation will be aborted.

If the search term is not found anywhere in the specified direction, the callback function will be called a single time with no arguments.

caseSensitive: A boolean value specifying whether searches are case sensitive. May be true (the default) or false.

properties: A Javascript object that contains additional data for the highlight. This object will be available to event handlers when events occur on this object, and may contain private data for the application's use.

11.6.13 OIT.document.select

OIT.document.select( range, moveto )

Makes the specified text range, cell range, or rect range the active selection. If range is null, any selection is cleared. If moveto is true, the display will be moved so the selection is visible.

range: Specifies the range to select. Must be a valid OIT TextRange, CellRange or RectRange, or a DOM Range (from document.createRange() and other methods), or a DOM Selection (from window.getSelection() and other methods).

moveto: If false, the range is selected without any other effect. Otherwise, the range is made visible just as if OIT.document.moveto were called.

Return Value

True if the selection changed, false if it was not changed.

11.6.14 OIT.document.selectionType

OIT.document.selectionType()

Retrieves the current selection type.

Return Value

"text", "cell", "rect" or "none"

11.6.15 OIT.document.selectionMode

OIT.document.selectionMode( [mode] )

Queries and optionally sets the selection mode.

mode: An optional parameter specifying the selection mode. A string value of "text", "rect", "cell", or "none". Only modes supported by the current view will be accepted. Attempting to set the selection mode to an unsupported value (i.e., "text" when viewing a spreadsheet) will have no effect. Setting the selection mode to "none" will disable selection.

Return Value

The current selection mode ("text", "rect", "cell", or "none")

11.6.16 OIT.document.selectionStyle

OIT.document.selectionStyle( [style] )

Queries and optionally sets the selection style. This determines the appearance of the selection rectangle.

style: An optional CSS string parameter specifying the selection style. Passing in null for this value will reset the selection style to the default (which is determined by the oit-sel-rect CSS class).

Return Value

The current selection style, or null if the default is being used.

11.6.17 OIT.document.selection

OIT.document.selection()

Returns a range representing currently selected text, rect, or cell range.

Return Value

A TextRange, RectRange, or CellRange object, or undefined if nothing is selected.

11.6.18 OIT.document.textSelection

OIT.document.textSelection()

Returns a range or array of ranges representing currently selected text. If cells in a spreadsheet or database are currently selected, the return value will be an array of TextRange objects corresponding to the selected cells.

Return Value

A TextRange object or array of TextRange objects, or undefined if no text is selected.

11.6.19 OIT.document.cellSelection

OIT.document.cellSelection()

Returns an object representing the currently selected range of cells.

Return Value

A CellRange object, or undefined if no cells are selected.

11.6.20 OIT.document.rectSelection

OIT.document.rectSelection()

Returns an object representing the currently selected rectangle or point.

Return Value

A RectRange object, or undefined if no rectangular range is selected.

11.6.21 OIT.document.getSelectedText

OIT.document.getSelectedText()

Retrieves the currently selected text.

Return Value

A string containing the currently selected text, without formatting. For cell selections in spreadsheets or database tables, the contents of the selected cells is returned. If no text is currently selected, returns an empty string.

11.6.22 OIT.document.textRange

OIT.document.textRange( domRange )

Returns an object representing the range of text specified by a DOM Range object (from document.createRange() and other methods). If the passed in Range object does not begin and end in the document text, will return undefined.

Return Value

A TextRange object

11.6.23 OIT.document.textRange

OIT.document.textRange( domSelection )

Returns an object representing the range of text specified by a DOM Selection object (from window.getSelection() and other methods). If the passed in Selection object does not begin and end in the document text, will return undefined.

Return Value

A TextRange object

11.6.24 OIT.document.textRange

OIT.document.textRange( acc, accend )

Returns an object representing the range of text specified by the acc and accend values

acc: The starting ACC for the text range.

accend: The ending ACC for the text range.

Return Value

A TextRange object

11.6.25 OIT.document.textRange

OIT.document.textRange( cellRange )

Returns an array of text ranges corresponding to the cells in the specified cell range.

  • cellRange: A CellRange object

Return Value

An array of zero or more TextRange objects

11.6.26 OIT.document.cellRange

OIT.document.cellRange( [sheet], c1, r1, [c2], [r2] )

Returns an object representing the cell or range of cells at the specified spreadsheet or database table, row(s), and column(s).

sheet: The sheet name or 0-based index. If unspecified, the current sheet will be used.

c1: The 0-based index of the starting column for the selection.

r1: The 0-based index of the starting row for the selection.

c2: The 0-based index of the ending column for the selection. If unspecified, the ending column will be the same as the starting column.

r2: The 0-based index of the ending row for the selection. If unspecified, the ending row will be the same as the starting row.

Return Value

A CellRange object

Return Value

OIT.document.cellRange( textRange )

Returns an array of cell ranges corresponding to the specified text range.

cellRange: A CellRange object

An array of zero or more CellRange objects.

11.6.27 OIT.document.rectRange

OIT.document.rectRange( [page], x1, y1, [x2], [y2], [units] )

Returns an object representing an x,y position or rectangle on the specified page.

page: The page name or 0-based index. If unspecified, the current page will be used.

left: The x coordinate for the left edge of the rectangle.

top: The y coordinate for the top edge of the rectangle.

right: The x coordinate for the right edge of the rectangle. If unspecified, the right edge will be equal to the left edge.

bottom: The y coordinate for the bottom edge of the rectangle. If unspecified, the bottom edge will be equal to the top edge.

units: Units for the left, top, right, and bottom properties. Must be one of: "px" (pixels), "tw" (twips). If not specified, the default value of "px" is used.

Return Value

A RectRange object

11.6.28 OIT.document.updateViewSize

OIT.document.updateViewSize()

The Web View Export view periodically updates it's layout in response to changes in the size of the view div, but there may be a slight delay while this update is processed. To update the display immediately after a change in view size, OIT.document.updateViewSize() may be called.

11.6.29 OIT.document.removeExtraEmailHeaders

OIT.document.removeExtraEmailHeaders()

This method allows a script to remove the extra email headers that are not displayed by default with an email message, but are available if the user clicks the "Show Details" icon (the small image of a gear.) Once this method is called, the detailed headers will not be accessible through the user interface or through internal API calls such as those for searching and highlighting. It is recommended that if you plan on using this method, you call it immediately after the document is loaded.

11.6.30 OIT.document.addEventListener

OIT.document.addEventListener( name, fn )

Adds an event listener for OIT document events. The event listener function receives the event as it's argument. event.preventDefault() may be called to prevent the default behavior described below.

See Events from the Javascript API for information on how events are handled.

Name may be any of the following:

Event Name Description Event Detail Default Behavior

load

Similar to the DOM load event, this event is fired when the document has been loaded and the Web View Export viewer initialized.

url: The url of the document that has been loaded.

(none)

unload

This event is fired when a document is being unloaded.

(none)

(none)

done

This event is fired when the number of pages in a document is known.

(none)

(none)

zoom

This event is fired when the user changes the zoom level in the Web View Export display.

zoom: A number representing the current scaling level. 1.0 = no zoom, 1.5 = image is 1.5 times normal size, etc.

mode: An optional string stating the zoom mode. Will be "page", "pagewidth" or undefined.

(none)

rotate

This event is fired when the user changes the rotation angle in the Web View Export display.

angle: A number representing the current rotation angle in degrees: 0, 90, 180, or 270.

(none)

idle

This event is fired periodically when no user mouse or keyboard activity is detected.

(none)

(none)

error

This event is fired when an error occurs in the client side OIT Javascript code.

message: A human readable message describing the error.

Log the error to the Javascript console.

select

This event is fired when the document selection changes.

selection: The new selection (may be undefined if nothing is selected).

empty: A boolean value indicating whether this is an empty selection. An empty text or rect selection occurs when the user clicks on the document but does not drag to create a selection. Empty cell selections are not possible since at least one cell will always be selected.

highlightid: If the selection is changing due to a highlight being activated, this will contain the highlight id.

Set the current highlight to the one closest to the new selection.

scroll

This event is fired when the view is scrolled. It is also fired when the scroll range changes, in response to a page change, zoom, or rotate operation and when the document is first loaded.

viewUpperLeft.pageIndex: The 0-based index of the page closest to the upper left corner of the view

viewUpperLeft.x, viewUpperLeft.y: The coordinates of the upper left corner of the view relative to the page specified by viewUpperLeft.pageIndex

viewLowerRight.pageIndex: The 0-based index of the page closest to the bottom right corner of the view

viewLowerRight.x, viewLowerRight.y: The coordinates of the lower right corner of the view relative to the page specified by viewLowerRight.pageIndex

Note that the x and y coordinates may fall outside the page. The OIT.pages.dimensions() function may be called to retrieve the dimensions of each page.

(none)

keydown

This event is fired when a keydown event is received by the view.

srcEvent: The original KeyboardEvent that triggered this event

Various actions, depending on the pressed key

showmessage

Dispatched when a dialog would be shown by oit.js. Calling preventDefault() on this event will suppress the dialog (but progress and hidemessage events will still be dispatched).

A showmessage event will be followed by a hidemessage event when the dialog would be hidden.

If the 'progress' property is true, one or more progress events will be dispatched before the hidemessage event is dispatched.

message: The original KeyboardEvent that triggered this event

modal: A boolean value indicating whether the dialog should be modal (i.e. should disable other interaction with the application)

progress: A boolean value indicating whether a progress bar should be displayed

Show the message dialog

change

Called whenever the currently displayed page (that is, the value returned by OIT.pages.current()) changes.

page: The index of the page being displayed

features: The features supported for this page type. An object with the following boolean properties: "zoom", "fitpage", "rotate", "pages", "highlights", "textselection", "rectselection", "cellselection"

width: The width of the page, in pixels, at 100% zoom and 0 degrees rotation. Changing the zoom level or page rotation angle will not affect this value

height: The height of the page, in pixels, at 100% zoom and 0 degrees rotation. Changing the zoom level or page rotation angle will not affect this value

type: The page type. See OIT.pages.info for a list of page types

notes: When type is "slide", this will indicate whether there are slide notes for this page

(none)

progress

This event is fired to update the progress bar in the message dialog.

percentDone: A numeric value in the range 0..100

Update the message dialog progress bar

hidemessage

This event is fired to hide the message dialog.

(none)

Update the message dialog progress bar

optionschanged

This event is dispatched when option values have been updated by OIT.document.setOptions

Any of the fields specified in OIT.document.setOptions may appear as a field in the event.detail object

(none)

11.6.31 OIT.document.removeEventListener

OIT.document.removeEventListener( name, fn )

Removes an OIT document event listener that was previously added by a call to OIT.document.addEventListener.

See Events from the Javascript API for information on how events are handled.

11.7 OIT.pages

This section describes OIT.pages.

11.7.1 OIT.pages.current

OIT.pages.current()

Returns the index of the page currently nearest the top of the display.

Return Value

A number representing the 0-based index of the current page.

11.7.2 OIT.pages.pageName

OIT.pages.pageName( [index] )

Returns the name of the specified page.

index: The 0-based index of a page in the range [0..(OIT.pages.count()-1)]. If not specified, returns the name of the current page.

Return Value

A string containing the name of the specified page.

11.7.3 OIT.pages.count

OIT.pages.count()

Returns the number of pages in the document.

Return Value

The number of pages in the document.

11.7.4 OIT.pages.moveto

OIT.pages.moveto( dest )

Moves the view to the specified destination. Calling this function will cause a 'change' event to be dispatched if the current page changes.

dest: The destination to move to. May be a 0-based page index, an element or text node in the body of the document, or a text range, cell range, or rect range object.

Return Value

A number representing the 0-based index of the current page.

11.7.5 OIT.pages.movetoNext

OIT.pages.movetoNext()

Moves the view to the next page in the document. Calling this function will cause a 'change' event to be dispatched if the view is not already at the end of the document.

Return Value

A number representing the 0-based index of the current page.

11.7.6 OIT.pages.movetoPrev

OIT.pages.movetoPrev()

Moves the view to the previous page in the document. Calling this function will cause a 'change' event to be dispatched if the view is not already at the beginning of the document.

Return Value

A number representing the 0-based index of the current page.

11.7.7 OIT.pages.info

OIT.pages.info( [pageIndex] )
 

Retrieves information about the specified page.

pageIndex: The 0-based index of the page to retrieve dimensions for. If not specified, the dimensions of the current page will be returned.

Return Value

An object with the following properties:

  • width: The width of the page, in pixels, at 100% zoom and 0 degrees rotation. Changing the zoom level or page rotation angle will not affect this value.

  • height: The height of the page, in pixels, at 100% zoom and 0 degrees rotation. Changing the zoom level or page rotation angle will not affect this value.

  • type: The type of this page, as defined in its original document (see below).

  • acc: The starting ACC for the text on the page.

  • accend: The ending ACC for the text on the page.

  • notes: When the type of this page is "slide", indicates whether slide notes are present for this page.

The page type will be one of the following:

  • "page" - Word processor page

  • "worksheet" - Spreadsheet worksheet

  • "database" - Database table

  • "bitmap" - Bitmap image

  • "archive" - File archive

  • "drawing" - Vector drawing

  • "slide" - Presentation slide

  • "html" - HTML page

  • "chart" - Spreadsheet chart

  • "emailarchive" - Email archive

  • "email" - Email document

11.7.8 OIT.pages.addEventListener

OIT.pages.addEventListener( name, fn )

Adds an event listener for OIT page events. The event listener function receives the event as its argument. event.preventDefault() may be called to prevent the default behavior described below.

See Events from the Javascript API for information on how events are handled.

Name may be any of the following:

Event Name Description Event Detail Default Behavior

change

Called whenever the currently displayed page (that is, the value returned by OIT.pages.current()) changes

page: The index of the page being displayed.

features: The features supported for this page type. An object with the following fields: "zoom", "pages", "highlights".

width: The width of the page, in pixels, at 100% zoom and 0 degrees rotation. Changing the zoom level or page rotation angle will not affect this value.

height: The height of the page, in pixels, at 100% zoom and 0 degrees rotation. Changing the zoom level or page rotation angle will not affect this value.

type: The page type. See OIT.pages.info for a list of page types.

(none)

add

Called when information on additional pages has been downloaded from the server. This message will only be dispatched when the file was exported using streaming mode.

startPage: The index of the first added page

(none)

Example:

OIT.pages.addEventListener( "change", function(event) 
        {
        document.getElementById("pagenum").innerHTML = event.detail.page;
        });

11.7.9 OIT.pages.removeEventListener

OIT.pages.removeEventListener( name, fn )

Removes an OIT page event listener that was previously added by a call to OIT.pages.addEventListener.

See Events from the Javascript API for information on how events are handled.

11.8 OIT.highlights

This section describes management of highlights.

11.8.1 Adding and Removing Highlights

This section describes adding and removing highlights.

11.8.1.1 OIT.highlights.add

OIT.highlights.add( style, [range], [properties], [comment] )

This method adds a highlight to a range of the document, using the specified style.

  • style: A CSS string that may include the color and/or background-color properties. Any other properties are ignored.

  • range: May be a text range (from OIT.document.textRange() or OIT.document.textSelection()), a cell range (from OIT.document.cellRange() or OIT.document.cellSelection()), a rect range (from OIT.document.rectRange() or OIT.document.rectSelection()), a DOM Selection or a DOM Range.

    When no range parameter is specified, the current selection is used. If there is no current selection, the function has no effect.

  • properties: A Javascript object that contains additional data for the highlight. This object will be available to event handlers when events occur on this object, and may contain private data for the application's use.

  • comment: An optional comment string for the highlight.

Return Value

This method returns a numeric highlight id or an array of numeric highlight ids, which can be used to later identify this particular highlight or highlights for other actions in the API, such as adding a comment.

Examples:

var hlProps= {user:"bobT",  
                date:"05-29-2013 12:14 PST",
                userGroup: "administrators" };

OIT.highlights.add( "background-color:#FFFF00",  hlProps, "This is a comment " );

11.8.1.2 OIT.highlights.addNote

OIT.highlights.addNote( style, [range], [properties], [comment] )

This method adds an anchored note to the document using the specified style.

  • style: A CSS string that may include the color and/or background-color properties. Any other properties are ignored.

  • range: This may be a cell range (from OIT.document.cellRange() or OIT.document.cellSelection()) or a rect range (from OIT.document.rectRange() or OIT.document.rectSelection()).

    When no range parameter is specified, the current selection is used. If there is no current cell or rect selection, the function has no effect.

  • properties: A Javascript object that contains additional data for the note. This object will be available to event handlers when events occur on the note, and may contain private data for the application's use.

  • comment: An optional string to use as the note text. If this value isn't specified, the note will be blank.

Return Value

This method returns an numeric id, which can be used to later identify this particular note for other actions in the API, such as changing the note comment.

Example 11-1 Example

This shows adding a note to the current selection:

var hlProps= {user:"bobT",  
              date:"05-29-2013 12:14 PST",
              userGroup: "administrators" };

OIT.highlights.addNote( "background-color:#FFFF00",  hlProps, "This is an anchored note" );

11.8.1.3 OIT.highlights.redact

OIT.highlights.redact( [range], [properties], [label] )

Adds a redaction to a range of the document. The redaction fill color will be black by default, but may be changed setting the redactionColor option through the OIT.document.setOptions function.

  • range: May be a text range (from OIT.document.textRange() or OIT.document.textSelection()), a cell range (from OIT.document.cellRange() or OIT.document.cellSelection()), a rect range (from OIT.document.rectRange() or OIT.document.rectSelection()), a DOM Selection or a DOM Range.

    When no range parameter is specified, the current selection is used. If there is no current selection, the function has no effect.

  • properties: A Javascript object that contains additional data for the redaction. This object is available to event handlers when events occur on this object, and may contain private data for the application's use.

  • label: A text label to display on top of the redaction. This text will be automatically sized and rotated for optimum display within the redaction rectangle.

Return Value

This method returns a numeric highlight id or an array of highlight ids, which can be used to later identify this particular redaction or redactions for other actions in the API, such as adding a comment.

Example 11-2 Examples

This shows adding a redaction to the current selection:

var hlProps= {user:"bobT",  
              date:"05-29-2013 12:14 PST",
              userGroup: "administrators" };

OIT.highlights.redact( hlProps, "SSN" );

This shows searching for text and applying a redaction:

var textRange = OIT.document.find("searchtext");
if( textRange )
  OIT.highlights.redact( textRange );

11.8.1.4 OIT.highlights.defineStamp

OIT.highlights.defineStamp( name, imageUrl, [options] )
 

This method specifies an image that may be used for image-stamp highlighting. Only images that have been named through this method may be used as for highlighting.

  • name: This is a name that will be used to reference the image stamp.

  • imageUrl: This is the URL to a PNG, JPG, or GIF file to be used as an image stamp

  • options: An optional object, which if present may contain properties that affect the formatting of the image stamp. Allowable properties are listed below.

Stamp Formatting Options

Besides the image itself, there are additional options that can affect the display of an image-stamp highlight. These may be specified as properties in an options object supplied to OIT.highlights.defineStamp, or as properties of a stamp object supplied to OIT.highlights.addStamp. Supported options include the following:

  • sizing: Indicates how stamp images should be sized. Possible values are:

    "scale" - The stamp will be fit into the destination rectangle at the largest size that preserves its aspect ratio.

    "stretch" - The stamp will be stretched to entirely fill the destination rectangle, with no preservation of aspect ratio.

    "image" - The stamp will be applied at the native size of the image, regardless of the boundaries of the rectangle.

    Default: "scale"

    The top left corner of the stamp will always align with the top left corner of the destination rectangle.

  • opacity: A value from 0 to 1.0 indicating the opacity of the image. A value of 0 indicates complete transparency; a value of 1 indicates complete opacity.

    Default: 1

  • defaultSize: An object that contains two properties, x and y; these numbers specify, respectively, a default width and height in pixels for stamps applied at a point (this includes stamps applied via OIT.highlights.autoHighlight).

    Default: none (When not specified, the size of the stamp image is used as the default size.)

    Example:

            options.defaultSize = {x:160,y:200}; 
    

Note:

None of these values are required to be specified; default values will be used if they are not. If these options are supplied both in OIT.highlights.defineStamp and OIT.highlights.addStamp, the values supplied in addStamp will take precedence.

11.8.1.5 OIT.highlights.addStamp

OIT.highlights.addStamp( stamp, [range], [properties], [comment] )

This method adds a highlight to a range of the document, using the specified style.

  • stamp: Specifies the stamp to be applied. This parameter may be either:

    • A string, in which case it specifies the name of a stamp previously specified in OIT.highlights.defineStamp. or

    • An object, in which case it must contain at least a property named "name" which specifies the name of a previously defined stamp. This object may also include one or more of the properties described above as stamp formatting options.

  • range: may be a rectangular range (from OIT.document.rectRange() or OIT.document.rectSelection()), or a cell range (from OIT.document.cellRange() or OIT.document.cellSelection()).

    In the special case of a rectangular range whose top-left and bottom-right corners are the same, indicating a single point, the image stamp will be applied at its native width and height, centered around the specified point.

    When no range parameter is specified, the current selection is used. If there is no current selection, the function has no effect.

  • properties: A Javascript object that contains additional data for the highlight. This object will be available to event handlers when events occur on this object, and may contain private data for the application's use.

Return Value

This method returns a numeric id, which can be used to later identify this particular highlight for other actions in the API, such as adding a comment.

Examples

  OIT.highlights.defineStamp( "approved", "/images/greencheck.png" );
  OIT.highlights.defineStamp( "rejected", "/images/redx.png", {sizing:image} );
 
  OIT.highlights.addStamp( "approved", OIT.document.rectRange( 0,0,100,100) );
  OIT.highlights.addStamp( { name:"rejected", opacity: .5 } );

11.8.1.6 OIT.highlights.apply

OIT.highlights.apply( highlights, filterFunction )

This method allows an application to specify an entire set of pre-defined highlights.

highlights: This is a JSON-encoded list of highlights previously obtained via a call to the OIT API.

filterFunction: [Optional] A function that can be used to indicate whether or not a particular highlight should be applied.

Notes

If present, the filter function will be called for every highlight, and should return a boolean value. If the function returns true, the highlight in question will be applied to the current document; if the function returns false, the highlight in question will not be applied.

The filter function has the following prototype:

function filterFunction( id, properties )

The first parameter is the id value that will be assigned to the highlight if the filter function returns true. This is equivalent to an id value returned by OIT.highlights.add(), with the exception that this id value is not yet valid, and may not be used in API calls within the scope of the filter function. The second parameter will be the properties object, if any, that has been defined for the highlight.

Example:

OIT.highlights.apply( function(id, props) {
   if( props && props.userId == myData.currentUserId )
     return true;
   else
     return false;
  });

11.8.1.7 OIT.highlights.remove

OIT.highlights.remove( [id] )

Removes the highlight with the specified id. If id isn't specified, removes the current highlight.

11.8.1.8 OIT.highlights.clear

OIT.highlights.clear( [filterFunction] )

Removes all highlights from the document.

filterFunction [Optional]: A function that can be used to indicate whether or not a particular highlight should be applied.

Notes

If present, the filter function will be called for every highlight, and should return a boolean value. If the function returns true, the highlight in question will be removed from current document; if the function returns false, the highlight in question will not be removed.

The filter function has the following prototype:

function filterFunction( id, properties )

The first parameter is the id of the highlight, as returned by OIT.highlights.add(). The second parameter is the properties object, if any, that has been defined for the highlight.

Example:

OIT.highlights.clear( function(id, props) {
   if( props && props.name == "remove me" )
     return true;
   else
     return false;
  });

11.8.1.9 OIT.highlights.autoHighlight

OIT.highlights.autoHighlight( type, options )

This method enables and disables automatic addition of highlights to a web view in response to user selections.

  • type: One of the following values:

    • "selection" (string value) - Selections are automatically highlighted.

    • “note” (string value) - Text and cell selections automatically result in an anchored note. Clicking on the document when in rectangular selection mode also results in an anchored note.

    • “redaction” (string value) - Selections are automatically redacted.

    • "stamp" (string value) - Image stamp highlights are automatically applied where the user clicks or taps on the document.

    • false (boolean value) - Auto highlighting is turned off. If this parameter is omitted, the method returns the current type of auto-highlighting.

  • options: An object that specifies parameters for auto-highlighting. Possible properties of this object include any of the values from OIT.highlights.setOptions, plus any of the following:

    • comment [optional] - This property may be a string or boolean value. If it is a string, its contents are applied as a comment to each highlight; if it is the boolean value true, the user is prompted to enter a comment for each new highlight.

      default value: false

    • label [optional] - A string value specifying a label to attach to each highlight.

      default value: (no label)

    • sticky [optional] - A boolean value. If present and equal to true, autoHighlight remains enabled until disabled through another call to this function

      default value: false

    • style [required if type is "selection"; ignored otherwise] - See description of the style parameter to OIT.highlights.add.

    • stamp [required if type is "stamp"; ignored otherwise] - See description of the stamp parameter to OIT.highlights.addStamp.

    • properties [optional] - See description of "properties" parameter to OIT.highlights.add; if specified, these properties are applied automatically to each highlight

      default value: none

Return Value

This method returns the current type of auto-highlighting.

Examples

OIT.highlights.autoHighlight( "selection", {style:"background-color:#FFFF00"});

11.8.1.10 OIT.highlights.autoHighlightOptions

OIT.highlights.autoHighlightOptions([options] )

This method sets or updates the current highlight options used by OIT.highlights.autoHighlight.

options: an object that specifies any of the properties associated with auto-highlighting. Any other properties are ignored. This parameter may be omitted if the caller simply wants to query the current value of the auto-highlight options.

Return Value

This method returns an object containing the active values of the auto-highlight options.

11.8.1.11 OIT.highlights.serialize

OIT.highlights.serialize( filterFunction )
OIT.highlights.serialize( highlightid )
OIT.highlights.serialize( highlightidArray )

Serializes the highlights in this document so that they may be saved and re-applied later. One of either a filter function, a highlight id, or an array of highlight id's may be passed in as arguments. If no parameter is specified as an argument, all of the highlights in the document are included in the serialized data.

  • filterFunction: [Optional] A function that can be used to indicate whether or not a particular highlight should be included in the serialized data.

  • highlightid: [Optional] A highlight id. Only the highlight matching the specified id will be included in the serialized data.

  • highlightidArray: [Optional] An array of highlight id's. Only the highlights matching the specified ids will be included in the serialized data.

Return Value

A Javascript String object that contains the highlights applied to the current document. This data may be saved and re-applied later via a call to OIT.highlights.apply. If changesOnly is set to true, this data will only include highlights created by the user since this document was loaded in the browser.

Notes

If present, the filter function will be called for every highlight, and should return a boolean value. If the function returns true, the highlight in question is serialized; if the function returns false, the highlight in question is not included in the serialized data.

The filter function has the following prototype:

function filterFunction( id, properties )

The first parameter is the id of the highlight in question. This is the same value returned by OIT.highlights.add(). The second parameter will be the properties object, if any, that has been defined for the highlight.

Example:

function checkProps(id, props) 
{
   if( props && props.userId == myData.currentUserId )
     return true;
   else
     return false;
}
 
OIT.highlights.serialize( checkProps );

11.8.1.12 OIT.highlights.getJSON

OIT.highlights.getJSON( highlightid )

This method behaves almost identically to the usage of specifying a single highlight id to OIT.highlights.serialize, but differs in its return type: the JSON string returned from this method represents a single highlight, not an array. (OIT.highlights.serialize always returns a JSON-encoded array, even when the results contain only a single item.)

  • highlightid: An id returned from OIT.highlights.add or OIT.highlights.redact

Return Values

A Javascript string that contains the JSON serialization of the specified highlight. If the supplied highlight id is invalid, the return value will be undefined. This data may be saved and re-applied later via a call to OIT.highlights.apply.

If the caller wishes to apply a collection of these highlights to a document all at once, they can do so by combining them in a single string that represents a JSON array. The string would just have to be built with the standard array delimiters; i.e., beginning the string with "[", appending highlight strings separated by "," characters, and appending "]" to the end of the buffer.

11.8.2 Interacting with Highlights

This section describes interacting with highlights.

11.8.2.1 OIT.highlights.setOptions

OIT.highlights.setOptions( id, options )
 

Sets options that control how a particular highlight behaves.

id: The highlight id.

options: An object with zero or more of these fields set:

  • enableUserDelete: A boolean value controlling whether the user is able to delete the highlight by pressing the DELETE key while the highlight is active. By default, highlights may be deleted by the user.

  • enableUserMove: A boolean value controlling whether the user is able to move the highlight using the mouse, touch, or keyboard. This applies to rectangular and cell highlights only - text highlights may not be made moveable. By default, rect and cell highlights may be moved by the user.

  • enableUserResize: A boolean value controlling whether the user is able to resize the highlight using the mouse, touch, or keyboard. By default, all highlights may be resized by the user.

  • enableUserComment: A boolean value controlling whether the user is able to add, edit, or remove the highlight comment. By default, comments are enabled.

11.8.2.2 OIT.highlights.style

OIT.highlights.style( id, [style] )

Optionally sets the style for the specified highlight, and returns the highlight style.

Calling this function for a redaction will not change the redaction style. The color of redactions may be changed by passing a value for the redactionColor property to OIT.highlights.setOptions.

  • id: The highlight id.

  • style: A CSS string that may include the color and/or background-color properties. Any other properties are ignored. The current highlight style is replaced by this new style. If a value is not passed in for this parameter, the current style will be returned unchanged.

Return Value

String containing the highlight style, or undefined if an invalid highlight id was specified.

11.8.2.3 OIT.highlights.comment

OIT.highlights.comment( id, [text] )
 

Optionally, sets the comment text for the specified highlight, and returns the highlight comment.

id: The highlight id.

text: The comment text string. If the highlight has an existing comment associated with it, the text is replaced by the new comment text. If a value is not passed in for this parameter, the current comment will be returned unchanged. Passing in null for this parameter will remove the comment from the highlight.

Return Value

String containing the comment text, or undefined if an invalid highlight id was specified or the highlight has no comment.

11.8.2.4 OIT.highlights.label

OIT.highlights.label( [id], [text] )

Retrieves the label for a highlight or redaction. If a value is passed in for the text parameter, the label is changed and the new value is returned.

  • id: The highlight id. If not specified, the current highlight or redaction will be used.

  • text: The label string. If the highlight has an existing label associated with it, the text is replaced by the new label text. If a value is not passed in for this parameter, the current label is returned unchanged. Passing in null for this parameter removes the label from the highlight.

Return Value

String containing the label text, or undefined if an invalid highlight id was specified or the highlight has no label.

11.8.2.5 OIT.highlights.properties

OIT.highlights.properties( id, [properties] )
 

Optionally, sets the custom properties for the specified highlight, and returns the highlight custom properties.

id: The highlight id.

properties: An optional javascript object that contains additional data for the highlight. This object replaces any existing properties on the highlight. This object will be available to event handlers when events occur on this object, and may contain private data for the application's use.

Return Value

The properties object attached to the highlight, or undefined if the highlight has no properties or if the specified id is not a valid highlight id.

11.8.2.6 OIT.highlights.property

OIT.highlights.property( id, valueName, [value] )
 

Optionally, sets a single custom property for the specified highlight, and returns the value of the property. If the specified highlight has a properties object, the named value will be added to it. If the named property already existed in the properties object, it will be replaced. If the specified highlight does not have a properties object associated with it, one will be created with the supplied property value.

id: The highlight id.

valueName: The name string for the property to be set.

value: The optional value of the property to be set. This parameter may be of any type. This value replaces any existing value for the specified property. If a value is not provided for this parameter, the value of the property is returned unchanged.

Return Value

The value of the specified property

11.8.2.7 OIT.highlights.current

OIT.highlights.current()

Returns the id of the current highlight. The current highlight is the one closest to the most recent selection or click. If there is no current highlight, returns undefined.

11.8.2.8 OIT.highlights.active

OIT.highlights.active()

Returns the id of the active highlight. The active highlight is the one that was most recently clicked or selected. If there is no active highlight, returns undefined.

11.8.2.9 OIT.highlights.moveto

OIT.highlights.moveto( [id] )

Moves the view to the highlight with the specified id. If id isn't specified, moves to the current highlight.

11.8.2.10 OIT.highlights.movetoNext

OIT.highlights.movetoNext( [filterFunction] )

Moves the view to the next highlight in document order.

filterFunction (optional): A function that is used to indicate whether or not a particular highlight should be navigated to.

Notes

The filter function is called for the next highlight in document order, and should return a boolean value. If the function returns true, the view moves to the highlight. Otherwise, moveToNext continues on to the next highlight and calls the filter function again. This process is repeated until either the last highlight is reached or the filter function returns true. If the filter function never returns true, the view is not moved.

The filter function has the following prototype:

function filterFunction( id, properties )

The first parameter is the id of the highlight in question. This is the same value returned by OIT.highlights.add(). The second parameter is the properties object, if any, that has been defined for the highlight.

Example:

function checkProps(id, props) 
{
   if( props && props.userId == myData.currentUserId )
     return true;
   else
     return false;
}
 
OIT.highlights.moveToNext( checkProps );

11.8.2.11 OIT.highlights.movetoPrev

OIT.highlights.movetoPrev( [filterFunction] )

Moves the view to the previous highlight in document order.

filterFunction: (optional) A function that is used to indicate whether or not a particular highlight should be navigated to.

Notes

The filter function is called for the previous highlight in document order, and should return a boolean value. If the function returns true, the view moves to the highlight. Otherwise, moveToPrev will continue on to the previous highlight and call the filter function again. This process is repeated until either the first highlight is reached or the filter function returns true. If the filter function never returns true, the view does not move.

The filter function has the following prototype:

function filterFunction( id, properties )
 

The first parameter is the id of the highlight in question. This is the same value returned by OIT.highlights.add(). The second parameter is the properties object, if any, that has been defined for the highlight.

Example:

function checkProps(id, props) 
{
   if( props && props.userId == myData.currentUserId )
     return true;
   else
     return false;
}
 
OIT.highlights.moveToPrev( checkProps );

11.8.2.12 OIT.highlights.type

OIT.highlights.type( [id] )

Returns the highlight type.

Return Value

One of the following strings:

  • highlight

  • note

  • redaction

  • stamp

11.8.2.13 OIT.highlights.range

OIT.highlights.range( [id] )

Returns the text range, cell range, or rect range associated with a highlight. If id isn't specified, returns the range of the current highlight.

11.8.2.14 OIT.highlights.show

OIT.highlights.show( [id] )

Makes a highlight visible. If the specified highlight is already visible, this function has no effect.

id: The id of the highlight to show. If id isn't specified, all of the highlights in the document are made visible.

11.8.2.15 OIT.highlights.show

OIT.highlights.show( filterFunction )
 

Makes selected highlights visible.

filterFunction: A function that is used to indicate whether or not a particular highlight should be shown.

Notes

The filter function is called for every highlight, and should return a boolean value. If the function returns true, the highlight in question is shown; otherwise the highlight in question is left in its current state.

The filter function has the following prototype:

function filterFunction( id, properties )

The first parameter is the id of the highlight in question. This is the same value returned by OIT.highlights.add(). The second parameter is the properties object, if any, that has been defined for the highlight.

Example:

function checkProps(id, props) 
{
   if( props && props.userId == myData.currentUserId )
     return true;
   else
     return false;
}
 
OIT.highlights.show( checkProps );

11.8.2.16 OIT.highlights.hide

OIT.highlights.hide( [id] )
 

Makes a highlight invisible. If the specified highlight is already invisible, this function has no effect.

Hidden highlights behave the same as visible highlights, except that the highlight style is only visible when the highlight is active.

id: The id of the highlight to hide. If id isn't specified, all of the highlights in the document are made invisible.

11.8.2.17 OIT.highlights.hide

OIT.highlights.hide( filterFunction )
 

Makes selected highlights invisible.

filterFunction; A function that is used to indicate whether or not a particular highlight should be hidden.

Notes

The filter function is called for every highlight, and should return a boolean value. If the function returns true, the highlight in question is hidden; otherwise the highlight in question is left in its current state.

The filter function has the following prototype:

function filterFunction( id, properties )
 

The first parameter is the id of the highlight in question. This is the same value returned by OIT.highlights.add(). The second parameter will be the properties object, if any, that has been defined for the highlight.

Example:

function checkProps(id, props) 
{
   if( props && props.userId == myData.currentUserId )
     return true;
   else
     return false;
}
 
OIT.highlights.hide( checkProps );

11.8.2.18 OIT.highlights.isHidden

OIT.highlights.isHidden( id )
 

Checks if a highlight has been hidden via a call to OIT.highlights.hide().

Return Value

True if the highlight has been hidden (even if it is currently visible due to being activated), otherwise false.

11.8.2.19 OIT.highlights.showComment

OIT.highlights.showComment( [id], [options] )

Makes the comment associated with a highlight visible. If id isn't specified, shows the comments for the current highlight. If the specified highlight has no comment, this function has no effect.

options: An object with fields controlling the display of the comment. The object may have any combination of the following fields:

Field Description

mode

A string value controlling whether the comment is editable. May be one of the following:

  • new: Used when adding a new comment. If the user cancels the dialog, the highlight is automatically removed.

  • edit: Entire comment is editable, including the existing value.

  • view: Comment is not editable (the default).

Note that the new and edit modes allow the comment to be added, edited or removed regardless of the value of the enableUserComment option.

11.8.2.20 OIT.highlights.hideComment

OIT.highlights.hideComment( [id] )

Makes the comment associated with a highlight invisible or, if the highlight is an anchored note, collapses it to an icon (see OIT.highlights.setOptions for a description of anchored notes). If id isn't specified, hides the comments for the current highlight. If the specified highlight has no comment, this function has no effect.

11.8.2.21 OIT.highlights.first

OIT.highlights.first()

Returns the id of the first highlight in the document.

11.8.2.22 OIT.highlights.last

OIT.highlights.last()

Returns the id of the last highlight in the document.

11.8.2.23 OIT.highlights.next

OIT.highlights.next( [id] )

Returns the id of the next highlight in the document after the specified id. If id isn't specified, returns the id of the next id after the current highlight.

11.8.2.24 OIT.highlights.prev

OIT.highlights.prev( [id] )

Returns the id of the previous highlight in the document from the current position. If id isn't specified, returns the id of the previous id before the current highlight.

11.8.2.25 OIT.highlights.activate

OIT.highlights.activate( [id] )

Activates the highlight with the specified id. If id isn't specified, activates the current highlight.

11.8.2.26 OIT.highlights.deactivate

OIT.highlights.deactivate()
 

Deactivates any currently active highlight. If no highlight is currently active, this function has no effect.

11.8.2.27 OIT.highlights.addEventListener

OIT.highlights.addEventListener( name, fn )

Adds an event listener for OIT highlight events. The event listener function receives the event as it's argument. event.preventDefault() may be called to prevent the default behavior described below.

See Events from the Javascript API for information on how events are handled.

Name may be any of the following:

Event Name Description Event Detail Default Behavior

add

Fired when a new highlight has been added.

highlightid: The id of the new highlight.

(none)

remove

Fired just before a highlight is removed.

highlightid: The id of the highlight that is being removed.

(none)

move

Fired after a highlight's range has changed.

highlightid: The id of the highlight that has moved.

(none)

comment

Fired after a highlight's comment has changed.

highlightid: The id of the highlight whose comment has changed..

(none)

mode

Fired when the current mode of highlighting changes

autohighlight: true if auto-highlighting mode is enabled, false if not.

autooptions: an object containing current values of auto-highlight options.

selectionmode: the current selection mode (text/rect/cell).

(none)

activate

Fired when the current highlight changes.

highlightid: The id of the current highlight.

before: A boolean value indicating if the selection falls before the highlight.

after: A boolean value indicating if the selection falls after the highlight.

(none)

mousedown

Fired when the user depresses a mouse button over a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original MouseEvent that triggered this event.

(none)

mouseup

Fired when the user releases a mouse button over a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original MouseEvent that triggered this event.

Activate the highlight

click

Fired when the user clicks on a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original MouseEvent that triggered this event.

(none)

dblclick

Fired when the user double clicks on a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original MouseEvent that triggered this event.

(none)

contextmenu

Fired when the user right clicks on a highlight, or takes another action that would normally bring up a context menu.

highlightid: The id of the affected highlight.

srcEvent: The original MouseEvent that triggered this event.

(none)

mousemove

Fired when the user moves the mouse cursor over a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original MouseEvent that triggered this event.

(none)

mouseover

Fired when the user moves the mouse cursor over a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original MouseEvent that triggered this event.

(none)

mouseout

Fired when the user moves the mouse cursor away from a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original MouseEvent that triggered this event.

(none)

touchstart

Fired when the user places a touch point over a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original TouchEvent that triggered this event.

(none)

touchend

Fired when the user removes a touch point over a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original TouchEvent that triggered this event.

Activate the highlight

touchmove

Fired when the user moves a touch point over a highlight.

highlightid: The id of the affected highlight.

srcEvent: The original TouchEvent that triggered this event.

(none)

touchcancel

Fired when the touch has been disrupted in some way.

highlightid: The id of the affected highlight.

srcEvent: The original TouchEvent that triggered this event.

(none)

11.8.2.28 OIT.highlights.removeEventListener

OIT.highlights.removeEventListener( name, fn )

Unregisters an event handler that was previously added by a call to OIT.highlights.addEventListener.

See Events from the Javascript API for information on how events are handled.

11.8.2.29 Examples

Searching for text and applying a highlight:

var textRange = OIT.document.find("searchtext");
if( textRange )
  OIT.highlights.add( "{background-color:yellow}", textRange );

11.9 OIT.hyperlinks

This section describes OIT.highlights.

11.9.1 Interacting with Hyperlinks

This section describes interacting with highlights.

11.9.1.1 OIT.hyperlinks.addEventListener

OIT.hyperlinks.addEventListener( name, fn )

Adds an event listener for OIT hyperlink events. The event listener function receives the event as its argument. event.preventDefault() may be called to prevent the default behavior described below.

See Events from the Javascript API for information on how events are handled.

Name may be any of the following:

Event Name Description Event Detail Default Behavior

mousedown

Fired when the user depresses a mouse button over a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original MouseEvent that triggered this event.

(none)

mouseup

Fired when the user releases a mouse button over a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original MouseEvent that triggered this event.

(none)

click

Fired when the user clicks on a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

target: For links to bookmarks in the current document, the target element.

srcEvent: The original MouseEvent that triggered this event.

Set window.location to the target url (for external hyperlinks) or call OIT.pages.moveto (for internal hyperlinks).

dblclick

Fired when the user double clicks on a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

target: For links to bookmarks in the current document, the target element.

srcEvent: The original MouseEvent that triggered this event.

(none)

contextmenu

Fired when the user right clicks on a highlight, or takes another action that would normally bring up a context menu.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original MouseEvent that triggered this event.

(none)

mousemove

Fired when the user moves the mouse cursor over a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original MouseEvent that triggered this event.

(none)

mouseover

Fired when the user moves the mouse cursor over a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original MouseEvent that triggered this event.

(none)

mouseout

Fired when the user moves the mouse cursor away from a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original MouseEvent that triggered this event.

(none)

touchstart

Fired when the user places a touch point over a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original TouchEvent that triggered this event.

(none)

touchend

Fired when the user removes a touch point over a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original TouchEvent that triggered this event.

(none)

touchmove

Fired when the user moves a touch point over a highlight.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original TouchEvent that triggered this event.

(none)

touchcancel

Fired when the touch has been disrupted in some way.

url: A string containing the url for the hyperlink that was clicked.

alt: The alt string for the hyperlink, if available.

external: A boolean value specifying whether this is a hyperlink to another document (true = external, false = link to a bookmark in the current document).

range: A TextRange or RectRange specifying the range affected by the hyperlink, if available.

srcEvent: The original TouchEvent that triggered this event.

(none)

11.9.1.2 OIT.hyperlinks.removeEventListener

OIT.hyperlinks.removeEventListener( name, fn )

Unregisters an event handler that was previously added by a call to OIT.hyperlinks.addEventListener.

See Events from the Javascript API for information on how events are handled.

11.10 OIT.archive

This section describes OIT.archive.

11.10.1 Interacting with archive nodes

This section describes archive node events and how to handle them.

11.10.1.1 OIT.archive.addEventListener

OIT.archive.addEventListener( name, fn )

Adds an event listener for OIT archive node events. The event listener function receives the event as its argument. event.preventDefault() may be called to prevent the default behavior described below.

Mouse Event Standard Properties include screenX, screenY, clientX, clientY, pageX, pageY, ctrlKey, altKey, shiftKey, metaKey, button, buttons, and relatedTarget, when those properties are set on the originating MouseEvent.

Touch Event Standard Properties include altKey, changedTouches, ctrlKey, metaKey, shiftKey, targetTouches, touches, and target, when those properties are set on the originating TouchEvent.

See Events from the Javascript API for information on how events are handled.

Name may be any of the following:

Event Name Description Event Detail Default Behavior

mousedown

Fired when the user depresses a mouse button over an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original MouseEvent that triggered this event.

(none)

mouseup

Fired when the user releases a mouse button over an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original MouseEvent that triggered this event.

(none)

click

Fired when the user clicks on an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original MouseEvent that triggered this event.

(none)

dblclick

Fired when the user double clicks on an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original MouseEvent that triggered this event.

(none)

contextmenu

Fired when the user right clicks on an archive node, or takes another action that would normally bring up a context menu.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original MouseEvent that triggered this event.

(none)

mousemove

Fired when the user moves the mouse cursor over an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original MouseEvent that triggered this event.

(none)

mouseover

Fired when the user moves the mouse cursor over an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original MouseEvent that triggered this event.

(none)

mouseout

Fired when the user moves the mouse cursor away from an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original MouseEvent that triggered this event.

(none)

touchstart

Fired when the user places a touch point over an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original TouchEvent that triggered this event.

(none)

touchend

Fired when the user removes a touch point over an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original TouchEvent that triggered this event.

(none)

touchmove

Fired when the user moves a touch point over an archive node.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original TouchEvent that triggered this event.

(none)

touchcancel

Fired when the touch has been disrupted in some way.

nodeid: The id of the affected node.

name: The name of the affected node.

srcEvent: The original TouchEvent that triggered this event.

(none)

11.10.1.2 OIT.archive.removeEventListener

OIT.archive.removeEventListener( name, fn )

Unregisters an event handler that was previously added by a call to OIT.archive.addEventListener.

See Events from the Javascript API for information on how events are handled.

11.11 OIT.attachments

This section describes handling email attachments.

11.11.1 Interacting with Email Attachments

The Web View display of email messages includes a listing of the names of any files that were attached to the message. The events described below apply to these displayed attachment names.

11.11.1.1 OIT.attachments.addEventListener

OIT.attachments.addEventListener( name, fn )

Adds a listener for events fired by attachments in email messages. The event listener function receives the event as its argument. event.preventDefault() may be called to prevent the default behavior described below.

Mouse Event Standard Properties include screenX, screenY, clientX, clientY, pageX, pageY, ctrlKey, altKey, shiftKey, metaKey, button, buttons, and relatedTarget, when those properties are set on the originating MouseEvent.

Touch Event Standard Properties include altKey, changedTouches, ctrlKey, metaKey, shiftKey, targetTouches, touches, and target, when those properties are set on the originating TouchEvent.

Event Name Description Default Behavior

mousedown

Fired when the user depresses a mouse button over an attachment.

(none)

mouseup

Fired when the user releases a mouse button over an attachment.

(none)

click

Fired when the user clicks on an attachment.

(none)

dblclick

Fired when the user double clicks on an attachment.

(none)

contextmenu

Fired when the user right clicks on an attachment, or takes another action that would normally bring up a context menu.

(none)

mousemove

Fired when the user moves the mouse cursor over an attachment.

(none)

mouseover

Fired when the user moves the mouse cursor over an attachment.

(none)

mouseout

Fired when the user moves the mouse cursor away from an attachment.

(none)

touchstart

Fired when the user places a touch point over an attachment.

(none)

touchend

Fired when the user removes a touch point over an attachment.

(none)

touchmove

Fired when the user moves a touch point over an attachment.

(none)

touchcancel

Fired when the touch has been disrupted in some way.

(none)

Event Detail

Each event object provided with the event will always include the following properties in event.detail

  • attachment: The index of the affected attachment

  • name: The name of the affected attachment

  • srcEvent: The original MouseEvent or TouchEvent that triggered this event

If the document was exported with the "attachment handling" option set to extract or export the attachments, the following properties will be present:

  • url: The url of the exported or extracted attachment

  • form: Either "html" or "extracted." If this value is "html," the url points to a generated web view of the attachment. If the value is "extracted," the url points to an extracted (binary) copy of the attachment.

11.11.1.2 OIT.attachments.removeEventListener

OIT.attachments.removeEventListener( name, fn )
 

Unregisters an event handler that was previously added by a call to OIT.attachments.addEventListener.

See Events from the Javascript API for information on how events are handled.

11.11.1.3 OIT.attachments.describe

OIT.attachments.describe( [index] )
 

Provides information attachments in email documents. The information returned is identical to the event detail provided in events generated from OIT.attachments.addEventListener.

index: Identifies the index of the attachment to be described. This is a zero-based index.

Return Value

A javascript object describing the specified attachment. If no index parameter is provided, this function returns an array of all of the document's attachments. If the document has no attachments, or an invalid index value is specified, the function returns undefined.

11.11.1.4 OIT.attachments.setOptions

OIT.attachments.setOptions( object )

options: An object with zero or more of these fields set:

  • cursor: A CSS value for specifying the mouse cursor to be displayed for email attachment file names.

  • color: A CSS value for specifying the text color to be used for email attachment file names.

Example 11-3 Example

// this will cause attachment names to have the same cursor as links 
OIT.attachments.style( {cursor:"pointer"} );

11.12 OIT.toolbars

The API supports adding a toolbar to each of the four sides of a web view. The API functions address a toolbar by the edge of the view on which it is located – "top," "bottom," "left," or "right." Toolbars may also be placed on top of the web view, as an overlay toolbar. (This should be used carefully, because while it is visible, an overlay toolbar at least partially obstructs the view of the document.)

In cases where two toolbars might overlap, priority is given to the first toolbar added. For example, if a toolbar is added to the top of the web view, and then another is added to the left side of the web view; the top toolbar will extend across the entire width of the web view, but the toolbar on the left edge will extend from the bottom of the top toolbar to the bottom of the web view.

11.12.1 OIT.toolbars.add

OIT.toolbars.add( edge, element, [options] )

Adds a toolbar to the Web View Export display.

edge: Must be one of "top," "bottom," "left," or "right." This parameter indicates the edge of the display where the toolbar will be located.

element: This is a DOM element supplied by the caller that contains the toolbar elements.

options: The options object may be used to specify additional properties of the toolbar.

Field Description

size

The size, in pixels, of the toolbar.

  • If the specified toolbar is attached to the top or bottom of the view, the size value represents the height of the toolbar.

  • If the toolbar is attached to the left or right of the view, the size value represents the width of the toolbar.

  • If a size is not specified, the element supplied for the toolbar must have a size defined for it through CSS.

visible

If true, the toolbar is shown immediately upon creation. If this parameter is false or not present, the toolbar is initially hidden.

border

An optional CSS border value to be applied between the toolbar and the document view. For example, a typical value might be "1px solid #c0c0c0". If the toolbar was attached to the top edge of the view, this value is used as the toolbar's bottom border; if the toolbar was attached to the bottom edge, this value would be used as its top border; etc.

overlay

If true, the toolbar is placed over the displayed document. (The default behavior is to place toolbars adjacent to the displayed document.)

Return Value

Returns the id of the newly added toolbar.

Example

This is an example of a simple status bar that shows the location of the current document:

OIT.document.addEventListener( "load", function(evt) {
 var tools = document.createElement("div");   
 tools.appendChild( document.createTextNode(evt.detail.url) );
 OIT.toolbars.add("bottom", tools, {size:20, visible: true} );
}

11.12.2 OIT.toolbars.remove

OIT.toolbars.remove( id )

Removes a toolbar from the display.

id: Must be one of "top," "bottom," "left", "right," or "all."

11.12.3 OIT.toolbars.show

OIT.toolbars.show( id )

Shows an existing toolbar.

id: Must be one of "top," "bottom," "left", "right," or "all."

11.12.4 OIT.toolbars.hide

OIT.toolbars.hide( id )

Hides a toolbar.

id: Must be one of "top," "bottom," "left", "right," or "all."

11.12.5 OIT.toolbars.setsize

OIT.toolbars.hide( id, size )

Sets the size of a toolbar.

id: Must be one of "top," "bottom," "left", or "right."

size: Either a number of pixels for the new size value, or "auto." If the size is set to "auto," the element containing the toolbar content (the element parameter provided to OIT.toolbars.add) must have a size specified via CSS.

11.12.6 OIT.toolbars.addEventListener

OIT.toolbars.addEventListener( name, fn )

Adds an event listener for OIT toolbar events. The event listener function receives the event as its argument. event.preventDefault() may be called to prevent the default behavior described below.

  • name: The name of the event to be monitored.

  • fn: A Javascript function that will be called with event information when the specified event occurs.

See Events from the Javascript API for information on how events are handled.

The name value may be any of the following:

Event Name Description Event Detail Default Behavior

add

Called after a toolbar has been successfully added to an edge of the web view.

id: The toolbar id

edge: The edge on which the new toolbar is placed ("top", "bottom", "left", or "right").

(none)

remove

Called after a toolbar has been removed from an edge of the web view.

id: The toolbar id

edge: The edge on which the toolbar had been placed ("top", "bottom", "left", or "right").

(none)

resize

Called after a toolbar has been resized.

id: The toolbar id

edge: The edge on which the new toolbar is located ("top", "bottom", "left", or "right").

width: The new width of the toolbar, in pixels.

height: The new height of the toolbar, in pixels.

(none)

show

Called after a toolbar has been shown.

id: The toolbar id

edge: The edge on which the toolbar is located ("top", "bottom", "left", or "right").

width: The current width of the toolbar, in pixels.

height: The current height of the toolbar, in pixels.

(none)

hide

Called after a toolbar has been hidden

id: The toolbar id

edge: The edge on which the toolbar is located ("top", "bottom", "left", or "right").

(none)

Example

OIT.toolbars.addEventListener( "resize", function(event) 
  {
    if( event.detail.edge == "top" )
       alert( "The top toolbar is now " + event.detail.width + " pixels wide." );
  });

11.12.7 OIT.toolbars.removeEventListener

OIT.toolbars.removeEventListener( name, fn )

Removes an event listener for OIT toolbar events.

name: The name of the event that was being monitored.

fn: The Javascript function to be removed from notifications of the specified event.

See Events from the Javascript API for information on how events are handled.

11.12.8 Navigation Toolbar

Web View supplies a standard toolbar called the "navbar", which is implemented in a supplied Javascript file OIT.navbar.js and a stylesheet OIT.navbar.css. This is a reference implementation of a navigation toolbar that may be enabled by an application simply by adding the appropriate references to the web view output.

In C code, this is accomplished via the options SCCOPT_POST_LIBRARY_SCRIPT and SCCOPT_EXTERNAL_STYLESHEET:

char * navbarJS = "/assets/OIT.navbar.min.js";
char * navbarCSS = "/assets/OIT.navbar.css";
DASetOption( hDoc, SCCOPT_POST_LIBRARY_SCRIPT, (VTLPVOID)navbarJS, strlen(navbarJS)+1 );
DASetOption( hDoc, SCCOPT_EXTERNAL_STYLESHEET, (VTLPVOID)navbarCSS, strlen(navbarCSS)+1 );
 

When the navbar is added to a web view, it enables itself automatically; no Javascript API calls are necessary.

11.12.9 Status Bar

Similar to the navbar, Web View supplies a minimal status bar, which is implemented in the asset files OIT.statusbar.min.js and OIT.statusbar.css. The status bar provides an area for displaying a line of text at the bottom of the web view. Adding the statusbar to a web view is accomplished in exactly the same way as adding the navbar.

Unlike the navbar, however, the status bar must be invoked by another script to be made visible. It contains no default messages; it only displays messages as instructed by a custom script. If the statusbar is installed, it may be controlled though a very simple API of its own, provided by an object called webview_statusbar.

11.12.9.1 webview_statusbar.show

webview_statusbar.show()
 

Makes the statusbar visible at the bottom of the view.

11.12.9.2 webview_statusbar.hide

webview_statusbar.hide()
 

Hides the statusbar.

11.12.9.3 webview_statusbar.message

webview_statusbar.message([text])
 

Specifies the text to be displayed in the statusbar. The text parameter may be omitted if the caller wishes only to retrieve the current message text.

Return Value

Returns the current status bar text.

11.13 OIT.local

Changes to localization strings must be made before the window "load" event fires, so changes must be made by Javascript code that executes when the document loads. Changes made to OIT.local after that point may not have any effect.

For instance, to use German language strings in the Web View Export UI, the customer would have top level Javascript code like this:

OIT.local.AUTHOR = "Verfasser"; (etc.)

Field Default Value

CANCEL

"Cancel"

DISCARD_CHANGES

"Discard changes"

DOCUMENT_ERROR

"Error occurred, document incomplete."

EMAIL_ATTACHMENTS

"Attachments:"

EMAIL_CALENDAREXCEPTIONS

"Calendar Exceptions"

EMAIL_CC

"CC"

EMAIL_BCC

"BCC"

EMAIL_FROM

"From"

EMAIL_TO

"To"

EMAIL_DATE

"Sent"

EMAIL_TOPIC

"Topic"

EMAIL_PRIORITY

"Priority"

EMAIL_IMPORTANCE

"Importance"

EMAIL_OWNER

"Owner"

EMAIL_STATUS

"Status"

EMAIL_PERCENT

"Percent Complete"

EMAIL_STARTDATE

"Start Date"

EMAIL_ENDDATE

"End Date"

EMAIL_DUEDATE

"Due Date"

EMAIL_CREATED

"Created"

EMAIL_CATEGORY

"Categories"

EMAIL_NAME

"Name"

EMAIL_FULLNAME

"Full Name"

EMAIL_FIRST

"First"

EMAIL_LAST

"Last"

EMAIL_MIDDLE

"Middle"

EMAIL_SUFFIX

"Suffix"

EMAIL_TITLE

"Title"

EMAIL_FILEAS

"File as"

EMAIL_DISPLAYAS

"Display as"

EMAIL_COMPANY

"Company"

EMAIL_JOBTITLE

"Job Title"

EMAIL_BPHONE

"Business Phone"

EMAIL_BADDRESS

"Business Address"

EMAIL_FAX

"Business Fax"

EMAIL_EMAIL

"Email Address"

EMAIL_HPHONE

"Home Phone"

EMAIL_HADDRESS

"Home Address"

EMAIL_MOBILE

"Mobile"

EMAIL_IM

"IM"

EMAIL_WEBPAGE

"Webpage"

EMAIL_ENTRYTYPE

"Entry Type"

EMAIL_STARTTIME

"Start Time"

EMAIL_ENDTIME

"End Time"

EMAIL_DURATION

"Duration"

EMAIL_REQATTEND

"Required Attendees"

EMAIL_OPTATTEND

"Optional Attendees"

EMAIL_LOCATION

"Location"

EMAIL_RECURTYPE

"Recurrence Type"

EMAIL_RECURRANGE

"Recurrence Range"

EMAIL_SUBJECT

"Subject"

LABEL_SEPARATOR

":"

NO

"No"

OK

"OK"

PAGE_DOWN

"Next Page"

PAGE_UP

"Previous Page"

PLEASE_WAIT

"Please wait"

PLEASE_WAIT_CONVERTING

"Document conversion in progress..."

PLEASE_WAIT_DOWNLOADING

"Loading document, please wait"

PLEASE_WAIT_INITIALIZING

"Please wait while your document is loaded..."

PREPARING_TO_PRINT

"Preparing to print..."

SAVE_CHANGES

"Save changes"

SHOWDETAILS

"Show Details"

HIDEDETAILS

"Hide Details"

YES

"Yes”

11.14 Events from the Javascript API

The Web View Export API allows scripts to register Javascript event handlers for certain events that occur while a document is being displayed. Instead of directly exposing the HTML DOM for registering event handlers, the API provides its own addEventListener methods for certain categories of objects, defined by Web View Export's own internal document model. The prototype is the same for all of these objects:

OIT.category.addEventListener( name, fn )

For every one of these functions, there is a corresponding:

OIT.category.removeEventListener( name, fn )

All Events are Custom Events

All events emitted by the Web View Export API are Javascript custom events, even when caused by a standard user action such as a mouse click event. The particular data associated with a Web View Export event is available from the "detail" object that is associated with the event object.

Example: Processing Events

In this example we react to the "document load" event by showing an alert box to indicate the URL of the newly loaded document. The url is contained in evt.detail.

 OIT.document.addEventListener( "load", function(evt) {  alert( "Just loaded " + evt.detail.url ); 
  });

Example: Preventing Default Behavior

If there is default behavior in the web view for a particular event, you can prevent it from occurring by calling the preventDefault() method on the event object.

 OIT.hyperlinks.addEventListener( "click", function(evt) {
   if( evt.detail.external ) /* don't follow external links */
     evt.preventDefault();
 });

Example: Events from DOM Events

Though all of the events defined by the Web View Export API are custom events, some events may be triggered in response to DOM events whose original event information is worth providing to your script. In these cases, the detail object will include the information from the original event object, as srcEvent.

OIT.hyperlinks.addEventListener( "click", function(evt) {
  alert( "Click event at x,y =" + evt.detail.srcEvent.clientX + ", " + evt.detail.srcEvent.clientY  );
  });