Viewer.js

A viewer for documents converted with the Box View API.

Contents

• Quick Start
  • Get the Source
  • Loading a Simple Viewer
• Logos
• Documentation
  • Library Methods
  • Viewer Config
  • Viewer Methods
  • Event Handling
    • Viewer Events
    • Page Events
  • Setting the Layout Mode
    • Built-in Layout Modes
    • Other Layout Modes
  • Styling Pages
  • Presentation Transitions
  • Realtime Page Streaming
  • Plugins
  • Data Providers
  • Text Documents
    • Syntax Highlighting
• Browser Support
• Contributing
• Getting Started with the Code
  • Dev Dependenvies
  • Git Hooks
  • Grunt
  • Logo Options
• Common Issues
• Change Log
• Copyright and License

Quick Start

Get the Source

You can find the pre-built development and production source files in the dist/ directory in this repository.

Viewer.js is available on npm and Bower:

npm install viewer

bower install viewer

All stable versions of viewer.js are hosted on CloudFlare's CDN, cdnjs. The unminified versions are available through the following URLs:

//cdnjs.cloudflare.com/ajax/libs/viewer.js/<VERSION>/crocodoc.viewer.css

//cdnjs.cloudflare.com/ajax/libs/viewer.js/<VERSION>/crocodoc.viewer.js

and the minified versions through:

//cdnjs.cloudflare.com/ajax/libs/viewer.js/<VERSION>/crocodoc.viewer.min.css

//cdnjs.cloudflare.com/ajax/libs/viewer.js/<VERSION>/crocodoc.viewer.min.js

For additional information, please see the cdnjs website.

v0.10.8

Development

• crocodoc.viewer.js 230.1 kB
• crocodoc.viewer.css 14.8 kB

Production

• crocodoc.viewer.min.js 51.9 kB (10.7 kB gzipped)
• crocodoc.viewer.min.css 11.4 kB (2.5 kB gzipped)

Loading a Simple Viewer

Crocodoc.createViewer(element, config)

Example

<link rel="stylesheet" href="crocodoc.viewer.min.css" />
<script type="text/javascript" src="jquery.min.js"></script>
<script type="text/javascript" src="crocodoc.viewer.min.js"></script>
<div class="viewer" style="height: 400px"></div>
<script type="text/javascript">
    var viewer = Crocodoc.createViewer('.viewer', {
        url: 'https://view-api.box.com/1/sessions/3c6abc0dcf35422e8353cf9c27578d5c/assets/'
    });
    viewer.load();
</script>

Logos

As per section 2.6 of our agreement of our API terms, we require that all apps using Box View with the Standard tier conspicuously display a Box logo when displaying Box View documents. We have included an approved logo within this repository. If your Box View plan permits custom branding of the viewer, please refer to Logo Options for instructions on how to build the viewer without the Box logo or with a custom logo.

Documentation

Library Methods

Crocodoc.createViewer(element, config)

Create and return a viewer instance initialized with the given parameters.

• element the DOM element to initialize the viewer into
  • string: a query selector
  • Element: a DOM Element
  • Object: a jQuery object
• config the configuration object

Crocodoc.addPlugin(pluginName, creatorFn)

Register a new plugin with the framework. See Plugins for more details.

• pluginName the name of the plugin
• creatorFn a function that creates and returns an instance of the plugin (which should be an object) when called

Viewer Config

The only required config parameter is url. All others are optional.

url (required)

The url parameter specifies the base URL where the document assets are located. Viewer.js will look for document assets (including info.json, stylesheet.css, etc) in this path.

layout

The layout parameter specifies the layout mode to use. Default Crocodoc.LAYOUT_VERTICAL. See Setting the Layout Mode for available layouts.

zoom

The zoom parameter specifies the initial zoom level to use. Default Crocodoc.ZOOM_AUTO.

Possible values:

• Crocodoc.ZOOM_FIT_WIDTH - zooms to fit the width of the (largest) page within the viewport
• Crocodoc.ZOOM_FIT_HEIGHT - zooms to fit the height of the (largest) page within the viewport
• Crocodoc.ZOOM_AUTO - zooms to best fit the document within the viewport

page

The page parameter specifies the initial page number to show when the document loads. Default: 1.

enableTextSelection

The enableTextSelection parameter specifies whether or not users can select text. If true, users can select text. Default: true. Note: text selection is not supported in IE 8 see Browser Support for more information.

enableLinks

The enableLinks parameter specifies whether or not hyperlinks are enabled. If true, hyperlinks are enabled. Default: true.

enableDragging

The enableDragging parameter specifies whether or not dragging is enabled. If true, click-and-drag scrolling/panning will be enabled for this document. Default: false. NOTE: text selection is not fully supported when dragging is enabled. It is recommended that you disable text selection if you plan to enable dragging.

plugins

The plugins parameter allows you to specify a map of plugin names to their respective configs. Plugin names specified in this object will be loaded when the viewer is initialized. See Plugins for more details.

Example:

{
    plugins: {
        // my-plugin will be initialized with the following config
        'my-plugin': {
            foo: 1,
            bar: 2
        }
    }
}

queryParams

The queryParams parameter allows you to specify query string parameters to append to each asset request (eg., info.json or page-1.svg). Can be an object or string. Default: null.

Examples:

// as a string
{
    queryParams: 'hello=world&foo=bar'
}

// as an object
{
    queryParams: {
        hello: 'world',
        foo: ['bar', 'baz']
    }
}

useWindowAsViewport

The useWindowAsViewport parameter allows you to specify whether to use the browser window as the viewport for the document. This is useful when the document should take up the entire browser window (e.g., on mobile devices). Use this option on mobile devices to allow the browser to auto-hide browser chrome when scrolling. Default: false.

dataProviders

The dataProviders parameter allows you override default data providers by specifying names of replacement data providers. See data providers for more info.

Example:

{
    dataProviders: {
        // page-svg data provider will be overridden by the 'my-page-svg' data provider
        'page-svg': 'my-page-svg'
    }
}

Viewer Methods

destroy()

The destroy method removes and cleans up the viewer instance.

on(name, handler)

The on method binds an event handler for the specified event name fired by the viewer object. See Event Handling for available events.

off(name[, handler])

The off method unbinds an event handler for the specified event name and handler fired by the viewer object. If handler is not given, unbinds all event handlers on this viewer object with the given name.

scrollTo(page)

The scrollTo method scrolls the viewer to the specified page. The page argument may be one of the following:

• (number) - scroll the the specified page number
• Crocodoc.SCROLL_PREVIOUS - scroll to the previous page
• Crocodoc.SCROLL_NEXT - scroll to the next page

Examples

// scroll to page 2
viewer.scrollTo(2);

// scroll to the next page
viewer.scrollTo(Crocodoc.SCROLL_NEXT);

zoom(val)

The zoom method sets the current zoom level of the document. Possible values:

• Crocodoc.ZOOM_FIT_WIDTH - zooms to fit the width of the (largest) page within the viewport
• Crocodoc.ZOOM_FIT_HEIGHT - zooms to fit the height of the (largest) page within the viewport
• Crocodoc.ZOOM_AUTO - zooms to best fit the document within the viewport
• Crocodoc.ZOOM_IN - zooms in
• Crocodoc.ZOOM_OUT - zooms out

Examples

// zoom in
viewer.zoom(Crocodoc.ZOOM_IN);

// zoom to fit width
viewer.zoom(Crocodoc.ZOOM_FIT_WIDTH);

setLayout(mode)

The setLayout method sets the layout mode. See Setting the Layout Mode for available layouts.

Examples

viewer.setLayout(Crocodoc.LAYOUT_PRESENTATION);

Event Handling

The viewer object fires several different events. You can add and remove event listeners using the on and off methods.

Example

// ready event fi