WebDocumentViewer

Atalasoft.Controls. WebDocumentViewer

new WebDocumentViewer(settingsopt, openCallbackopt) → {WebDocumentViewer}

Control that views, modifies, and saves documents, annotations and forms.

Parameters:
Name Type Description
[settings] WebDocumentViewerConfig

Object of key value pairs representing initial settings
[openCallback] OpenUrlCallback

callback that is called when document load complete(if documenturl is specified).
Returns:

A new control with the given settings.

Type
WebDocumentViewer

Classes

AnnotationController
DocumentController
TextController

Members

(static, constant) domattributes :string

Exposes list of well-known attributes that are used to provide additional information for DOM elements

Properties:
Name Type Description
atala_page_index string

Index of the page currently displayed within the element. applies to elements having .atala_page_div class

(static, constant) domclasses :string

Exposes the list of internal DOM elements classes that could be used to query and customize UI behavior.

Properties:
Name Type Description
atala_page_div string

Page element class. Container for all page elements - image, annotations, forms, text, etc layers.
atala_page_loading string

Page image container that is in initial image load state
atala_page_image_anchor string

Page image anchor container element class
atala_page_image string

Page image element class
atala_page_number string

Page index element class. see showpagenumber config option
atala_active_page string

Active page class
atala_active_thumb string

Active thumbnail class
atala_thumb_caption string

Thumbnail caption class
atala_toolbar string

Document toolbar element class
atala_annotation_toolbar string

Annotations toolbar element class
atala_toolbar_button string

Toolbar button element class
atala_main_container string

Class of the main outer object that holds the scrollbars
atala_scroller string

Class of the inner object that controls scrolling
atala_viewport string

Class of the inner object that defines the viewable area
atala_content string

Inner content container object class
atala_thumb_draggable string

Thumbnailer draggable area
atala_drag_placeholder string

Placeholder element that is inserted into Thumbnailer to highlight drop location
atala_dom_edge_first string

Placeholder inserted before page dom object that is used in virtual scrolling
atala_dom_edge_last string

Placeholder inserted after page dom object that is used in virtual scrolling
atala_scroll_horizontal string

Inner horizontal scroll bar object class
atala_scroll_vertical string

Inner vertical scroll bar object
atala_page_label string

Toolbar span element containing the page number
atala_context_menu string

Context or dropdown menu element. Could be multiple instances within same viewer DOM sub tree
atala_statusbar string

Status div
atala_tool_button_save string

"Save Changes" toolbar button
atala_tool_button_page_prev string

"Previous Page" toolbar button
atala_tool_button_page_next string

"Next Page" toolbar button
atala_tool_button_zoom_out string

"Zoom Out" toolbar button
atala_tool_button_zoom_in string

"Zoom In" toolbar button
atala_tool_button_fit_none string

"Full Size" toolbar button
atala_tool_button_fit_best string

"Best Fit" toolbar button
atala_tool_button_fit_width string

"Fit To Width" toolbar button
atala_tool_button_zoom_area string

"Zoom Area" toolbar button
atala_tool_button_rotate_left string

"Rotate Left" tooltip button
atala_tool_button_rotate_right string

"Rotate Right" tooltip button
atala_tool_button_text_tool string

"Text selection" toolbar button
atala_tool_button_pan_tool string

"Pan" toolbar button
atala_tool_button_ellipse_anno string

"Draw Ellipse" annotation toolbar button
atala_tool_button_highlight_anno string

"Draw Highlight" annotation toolbar button
atala_tool_button_line_anno string

"Draw Line" annotation toolbar button
atala_tool_button_lines_anno string

"Draw Poly Lines" annotation toolbar button
atala_tool_button_freehand_anno string

"Draw Freehand" annotation toolbar button
atala_tool_button_polygon_anno string

"Draw Polygon" annotation toolbar button
atala_tool_button_rect_anno string

"Draw Rectangle" annotation toolbar button
atala_tool_button_fillrect_anno string

"Filled Rectangle" annotation toolbar button
atala_tool_button_text_anno string

"Draw Text" annotation toolbar button
atala_tool_button_stamp_anno string

"Add a Stamp" annotation toolbar button
atala_tool_button_note_anno string

"Add a Sticky Note" annotation toolbar button
atala_tool_button_comment_anno string

"Add a Comment" annotation toolbar button
atala_tool_selection_band string

Selection Rubberband div object
atala_tool_selection_grip string

Selection Rubberband grip div object
atala_tool_selection_mask string

Selection Rubberband mask div object
atala_tool_selection_tooltip string

Selection Rubberband tooltip div object
atala_search_container string

Text search containing div object
atala_search_input string

Text search input box
atala_search_next string

Text search next match button
atala_search_prev string

Text search previous match button
atala_tool_button_upload string

"Upload document" toolbar button
atala_upload_control string

Upload control root container
atala_upload_file string

Upload input control
atala_upload_flex_area string

Upload control working area container
atala_upload_single_file string

Upload control single file status control
atala_upload_multiple_files string

Upload control multiple files status control
atala_upload_flex_buttons string

Upload control buttons area container
atala_upload_buttons string

Upload control buttons container
atala_upload_cancel_button string

Upload control Cancel button
atala_upload_ok_button string

Upload control Ok button
atala_upload_add_button string

Upload control Add button
atala_upload_files_header_name string

Upload control multiple files Name column header
atala_upload_files_header_size string

Upload control multiple files Size column header
atala_upload_files_header_status string

Upload control multiple files Status column header
atala_tile_column string

Tile column
atala_tiled_page_image string

Tiled page
atala_tool_button_bookmarks string

Show bookmarks' toolbar button
atala_bookmark_content string

Bookmark control
atala_bookmark_header string

Header of bookmark control

annotations :Atalasoft.Controls.WebDocumentViewer~AnnotationController

Annotations API. Will be available if config.allowannotations is set to true. Otherwise will be undefined

config :WebDocumentViewerConfig

Current control configuration.

document :Atalasoft.Controls.WebDocumentViewer~DocumentController

Document operations API.

text :Atalasoft.Controls.WebDocumentViewer~TextController

Text selection API.

Methods

reloadPage(index, annotationsopt, formsopt, paramsopt, callbackopt)

Reloads the specified page. If the thumbnailer is linked with viewer, viewer page is reloaded and callback is called when both viewer and thumbnailer completely reloaded, including image data itself.

Viewer page won't be reloaded if the viewer is currently controller by other thumbnailer and requested page was not loaded in viewer before. In such case page will be lazy-loaded as usual. If special parameters should be passed, beforehandlerrequest event to modify request parameters.

Parameters:
Name Type Default Description
index number

The index of the page to reload.
[annotations] string | boolean false

Url of the annotation xmp file or flag indicating whether to reload annotations of boolean flag indicating whether to load annotations data.
[forms] string | boolean

Url of the form file or flag indicating whether to reload forms of boolean flag indicating whether to load forms data.
[params] object

A plain object containing optional reload parameters that will be passed to server.
[callback] NotificationCallback

function that is called when page have been loaded.

This object will be available on the server side handler as an key-values collection. This allows to pass specific load options for individual pages.

bind(event, handler) → {Atalasoft.Controls.WebDocumentViewer}

Attaches a handler to an event.

Parameters:
Name Type Description
event string

the name of the event to bind to.
handler function

event handler.
Returns:

reference to this.

Type
WebDocumentViewer

zoomIn(callbackopt)

Zooms in one level.

Parameters:
Name Type Description
[callback] NotificationCallback

Function to execute when the zoom operation is finished

zoom(zoom, callbackopt)

Asynchronously zooms the viewer to the given zoom over the default zoom duration

Parameters:
Name Type Description
zoom number

Desired zoom level to zoom to.
[callback] NotificationCallback

function to execute after the zoom is finished animating.

dispose()

Removes all DOM elements, internal references, and empties memory intensive objects. The WebDocumentViewer will no longer function after a call to this method.

empty(callbackopt)

Resets the viewer to its default state.

Parameters:
Name Type Description
[callback] OpenUrlCallback

Function to execute when the empty process is finished

filterFilesForUpload(files, filteredFilesopt, callbackopt) → {Array.<File>}

Filters files for upload using the settings from config upload section.

Filters files that should be uploaded using the settings from config upload section. This includes filtering by size, by type and even by name in order to find out files for upload that have same names. It can be useful, because all events in WDV related to upload use filename as a key, thus you can find duplicates and upload such files in separate uploadFiles method calls.

This method is fully optional and even if some files failed to pass this filtering, they still can be uploaded to server,

Parameters:
Name Type Description
files Array.<File>

An array of file objects that can be used for upload.
[filteredFiles] Array.<string>

An array of filenames that previously were filtered. It's used for find duplicates in a new bunch of files.
[callback] NotificationCallback

Function to execute when the filtering has finished.
Returns:

An array files that have passed the filtering.

Type
Array.<File>

fit(fit, pageNumber, callback)

Asynchronously zooms the viewer to fit to a page.

Parameters:
Name Type Description
fit Fitting

Type of fitting to fit the page to.
pageNumber number

Page number to fit to. Note, that it's 1-based.
callback NotificationCallback

Function to execute after the fit is done animating.

uploadFiles(files, uploadpathopt, callbackopt)

Uploads several files on server to the predefined upload folder or to the given path.

Parameters:
Name Type Description
files Array.<File>

Array of file objects that should be uploaded.
[uploadpath] string

Relative path to upload to starting from uploadpath. Must be writable.
[callback] NotificationCallback

Function to execute when the upload has requested.

getCurrentPageIndex() → {number}

Gets the current page index

Returns:

Zero based index of the current page.

Note, that current page index detection could be affected by pageselectlocation configuration parameter.

Type
number

getDocumentInfo() → {Object}

Gets the current document info

Returns:

object indicating document main page size, and number of pages

Type
Object

getZoom() → {number}

Gets the current zoom level of the viewer.

Returns:
Type
number

isPageLoaded(index) → {boolean}

Checks whether specified document page have been loaded.

Parameters:
Name Type Description
index number

Page index.
Returns:

true if page have already been loaded; false otherwise.

Type
boolean

isReady() → {boolean}

Indicates whether the viewer is ready to receive commands.

If all dependent JavaScript libraries are included to the web page, control is initialized synchronously. Otherwise dependencies are asynchronously loaded automatically using scripturl parameter or from the same url where JQuery library is referenced. When all dependent JavaScript libraries are loaded, initialized event is fired.

Returns:
Type
boolean

next(n, callbackopt)

Scrolls to the next viewable page.

Parameters:
Name Type Description
n number

Number of pages to scroll forward.
[callback] NotificationCallback

Function to execute when the scroll operation is finished.

openUrl(documenturlopt, annotationsurlopt, formurlopt, callbackopt)

Opens the document at the given urls. It's possible to call this method multiple times for the same document to load document and the forms or annotations data separately.

Parameters:
Name Type Description
[documenturl] string

url of the document file with respect to the config.serverurl.

If set to empty string, call is equivalent to empty.
[annotationsurl] string

url of the annotation xmp file with respect to the config.serverurl.

Note, If empty string is passed, annotations from the previous document are cleared. if not passed or undefined, annotations from the previously opened document are preserved.
[formurl] string

url of the form file with respect to the config.serverurl.
[callback] OpenUrlCallback

Function to execute when the open operation is finished.

previous(n, callbackopt)

Scrolls to the previous viewable page.

Parameters:
Name Type Description
n number

Number of pages to scroll backward.
[callback] NotificationCallback

Function to execute when the scroll operation is finished.

uploadFile(file, uploadpathopt, callbackopt)

Uploads one file on server to the predefined upload folder or to the given path.

Parameters:
Name Type Description
file File

File object that should be uploaded.
[uploadpath] string

Relative path to upload to starting from uploadpath. Must be writable.
[callback] NotificationCallback

Function to execute when the upload has requested.
Example

Assuming you have a File object in your script. It can be retrieved from a input control or from server or any other way.

let viewer = new Atalasoft.Controls.WebDocumentViewer({
         ...
         upload:{} //enable upload support with default parameters. Where uploadpath is the web-project root folder.
         });
let file = document.getElementById('fileInput'); //Retrieve File object

viewer.uploadFile(file, 'uploadDirectory'); //Upload the file to the 'uploadDirectory' web-project root sub folder.

reloadPage(index, annotationsopt, formsopt, paramsopt, callbackopt)

Reloads the specified page.

Parameters:
Name Type Default Description
index number

The index of the page to reload.
[annotations] string | boolean false

Url of the annotation xmp file or flag indicating whether to reload annotations of boolean flag indicating whether to load annotations data.
[forms] string | boolean

Url of the form file or flag indicating whether to reload forms of boolean flag indicating whether to load forms data.
[params] object

A plain object containing optional parameters that will be passed to server.

Params could contain any application specific information that should be passed to server. For example, this could be the aggregated list of the parameters that was used in reloadPage calls for different pages.
[callback] NotificationCallback

function that is called when page have been loaded.

This object will be available on the server side handler as an key-values collection. This allows to pass specific load options for individual pages.

save(subpathopt, saveformatopt, paramsopt, callbackopt)

Saves the client changes in this document to the predefined save folder or to the given path.

Parameters:
Name Type Description
[subpath] string

Relative path to save to starting from savepath. Must be writable.
[saveformat] string

Save file format. If specified, the value overrides savefileformat form config.
[params] object

A plain object containing optional reload parameters that will be passed to server.
[callback] NotificationCallback

to execute when the save has finished
Example
const _viewer = new Atalasoft.Controls.WebDocumentViewer({
		parent: atalaJquery('#atala-document-container-left'),
		toolbarparent: atalaJquery('#atala-document-toolbar-left'),
		serverurl: 'WebDocumentHandler.ashx',
		savepath: 'Save/',
		savefileformat: 'pdf'
});

// document will be saved to the subpath subfolder. So if the savepath configuration
// parameter was set to Save/ then the save path will be Save/subpath. The format to save the file to will
// be taken from the configuration parameter savefileformat (in this example, 'pdf').
// This means that the file in pdf format will be saved in Save/subpath folder.
 _viewer.save(‘subpath’) // saves to ‘Save/subpath’ in ‘pdf’ format

// document will be saved to ‘Save/’ folder in ‘tif’ format.
_viewer.save(‘’, ‘tif’)

scrollBy(dx, dy, aniopt, callbackopt)

Scrolls by the given deltas, does not account for zoom, i.e. dx and dy values are passed in window coordinate space.

Parameters:
Name Type Default Description
dx number

Indicating delta of the x axis.
dy number

Indicating delta of the y axis .
[ani] boolean false

Indicating whether to animate this scroll.
[callback] NotificationCallback

Function to execute when the scroll operation is finished.

scrollTo(x, y, aniopt, callbackopt)

Scrolls to the given coordinates, does not account for zoom, i.e. x and y values are passed in window coordinate space.

Parameters:
Name Type Default Description
x number

Indicating the coordinate of the x axis.
y number

Indicating the coordinate of the y axis.
[ani] boolean false

Indicating whether to animate this scroll.
[callback] NotificationCallback

function to execute when the scroll operation is finished.

unbind(event, handleropt) → {Atalasoft.Controls.WebDocumentViewer}

Detaches the handler from the event.

Parameters:
Name Type Description
event string

the name of the event to unbind.
[handler] function

the event handler to unbind. If not specified, all handlers are unbound.
Returns:

reference to this.

Type
WebDocumentViewer

trigger(event, parametersopt) → {Atalasoft.Controls.WebDocumentViewer}

Triggers the event.

Parameters:
Name Type Description
event string

the name of the event to trigger.
[parameters] Object

the event data.
Returns:

reference to this.

Type
WebDocumentViewer

setMouseTool(tool)

Sets the current mouse tool

Parameters:
Name Type Description
tool MouseToolType

Type of the tool to set.

Mouse tool configuration could be passed using mousetool configuration option.

showPage(index, callbackopt)

Scrolls the viewer to the given page index and executes the callback when finished.

Parameters:
Name Type Description
index number

Index of the page to show.
[callback] NotificationCallback

Function to execute after this operation is done.

zoomOut(callbackopt)

Zooms out one level.

Parameters:
Name Type Description
[callback] NotificationCallback

Function to execute when the zoom operation is finished.

setStamps()

Deprecated:

showPageNumber(pageNumber, callbackopt)

Scrolls the viewer to the given page number and executes the callback when finished.

Parameters:
Name Type Description
pageNumber number

Number of the page to show. Note that page number is expected 1-based.
[callback] NotificationCallback

function to execute after this operation is done
Deprecated:

setImages()

Deprecated:

setAnnotationDefaults()

Deprecated:

createAnnotationOnPage()

Deprecated:

getAnnotationsFromPage()

Deprecated:

deselectAll()

Deprecated:

deleteAnnotationOnPageAtIndex()

Deprecated:

Events

activedocumentchanged :NotificationCallback

Triggers when viewer has been activated by another thumbnailer or reactivated by the same thumbnailer with changed document data.

beforehandlerrequest :BeforeHandlerRequestCallback

Triggers before a request is sent to the server.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
request Request

The request object.

This event could be used to override or extend request parameters which is exposed through event.request.data. Requests could be distinguished using event.request.type field. For supported request types see Request structure.

documentinfochanged

Triggers when the document info has changed, usually after a new document is opened.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
info DocumentInfo

The event document info.
customData Object

The event customer data from server.

documentloaded

Triggers when the document is done loading.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
customData Object

The event customer data from server.

documentsaved

Triggers after a response from the server while saving the document.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
success boolean

Flag indicating whether or not save were successful.
fileName string

File path to the saved file. By default it represents a path to the file relative to application path. However, if 'DocumentStream' property was initialized or 'PreventDefaultSaving' flag is used on server-side, then this property contains a value of 'DocumentStreamName' property.
customData Object

The event customer data from server.

documentunloaded :NotificationCallback

Triggers when the document has been unloaded from the control.

error :ErrorCallback

Triggers when the control has encountered and error. Populated keys: e.name, e.message

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
name string

The error type identifier.
message string

The error clarification message.

fileaddedtoupload

Triggers when the file added to upload files through UI controls.

Parameters:
Name Type Description
event object

The event object.

Properties
Name Type Description
filename string

Name of the file for upload.
reason FileUploadRejectReason

The reason of why file was rejected from the adding to upload.
success boolean

Flag indicating whether or not file has passed filtering.

fileuploaderror

Triggers when file upload has failed or was canceled.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
errorinfo UploadFileErrorInfo

The error information.

fileuploadfinished

Triggers when file upload has finished successfully.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
filename string

Name of the file for upload.
filepath string

Relative path on server to the uploaded file.
customData Object

The event customer data from server.

fileuploading

Triggers during file upload process. Can be used to track upload progress.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
uploadinfo UploadingFileInfo

The progress information.

fileuploadstarted

Triggers when file upload is started

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
fileinfo UploadFileInfo

The file information.

initialized :NotificationCallback

Triggers when the control has completed asynchronous initialization.

Asynchronous initialization happens when some dependent scripts are not included to web page and control trying to load them on background. In case of synchronous initialization, this event won't be fired. isReady method could be used after construction to check whether control is initialized.

pagenumberchanged

Triggers when the page number has changed. Populated keys: e.number

Parameters:
Name Type Description
event Object

The event object.

pagerecycled

Triggers when the control has recycled a pageDiv object.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
index number

Index of the recycled page.

pageresize

Triggers when the control has resized a pageDiv object.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
index number

Index of the resized page.
width number

Width of the page after resize.
height number

Height of the recycled page.

pageshown

Triggers when the control has shown a page in the viewable area.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
index number

Index of the page.

pagesizechanged

Triggers when the page size returned from the server is different than expected. The expected page size is the size returned from server along with other document info.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
index number

Index of the resized page.
width number

Width of the page after resize.
height number

Height of the recycled page.
dx number

Difference with the previous(expected) page width. Scaled images are compared.
dy number

Difference with the previous(expected) page height. Scaled images are compared.

pagetextloaded :LoadPageTextCallback

Triggers when page text loaded.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
index number

index of the page for which text data has been loaded.
customData Object

The event customer data from server.

scriptsloaded :NotificationCallback

Triggers when dependencies have finished loading.

scroll

Triggers for every pixel movement registered by the scrollable area.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
x number

Horizontal scroll position.
y number

Vertical scroll position.
dx number

Distance scrolled horizontally.
dy number

Distance scrolled vertically.

statusmessage

Triggers when the control has updated the status bar.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
message string

The status message.

textselected :NotificationCallback

Triggers when UI text selection complete.

uploadfinished

Triggers when the files upload is finished

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
success boolean

Flag indicating whether or not upload was completed without errors.
canceled boolean

Flag indicating whether or not upload was canceled.

uploadstarted

Triggers when the files upload is started.

Parameters:
Name Type Description
event Object

The event object.

Properties
Name Type Description
info UploadStartInfo

The upload information.

zoomchanged

Triggers when the zoom level of the control has changed.

Parameters:
Name Type Description
event Object

The event object.
zoom number

Current document zoom value.

zoomstarted :NotificationCallback

Triggers when a zoom operation has been started.