ViewerConfig – Doconut Documentation

ViewerConfig (namespace Doconut) describes the browser viewer's appearance and behavior. It does not affect document rendering quality; use a format config for that. The C# class and the long-standing JavaScript widget have different defaults, so map values explicitly.

C# properties

Type	Property	Default	Description
`bool`	`ShowThumbs`	`true`	Show the thumbnail panel.
`bool`	`AutoLoad`	`false`	Automatically load after initialization. The normal token flow calls `View(token)` explicitly.
`bool`	`AutoFocus`	`true`	Move browser focus/scroll to the viewer during initialization.
`bool`	`AutoPageFocus`	`true`	Keep the current thumbnail visible while pages change.
`int`	`PageZoom`	`100`	Initial zoom percentage.
`int`	`ZoomStep`	`10`	Percentage added or removed by zoom commands.
`int`	`MaxZoom`	`300`	Maximum zoom percentage.
`bool`	`ShowToolTip`	`true`	Show the page-position tooltip while scrolling.
`string`	`ToolTipPageText`	`"Page "`	Prefix used in the page tooltip.
`bool`	`CacheEnabled`	`false`	Retain a moving window of page images in browser memory. It does not use `localStorage`.
`bool`	`LargeDoc`	`false`	Append page elements in timed batches for large documents.
`bool`	`ShowHyperlinks`	`false`	Render hyperlink overlays when the server config extracted them.
`bool`	`FixedZoom`	`true`	Use a fixed zoom percentage rather than responsive recalculation.
`int`	`FixedZoomPercent`	`100`	Fixed desktop zoom.
`int`	`FixedZoomPercentMobile`	`75`	Fixed mobile zoom.
`string`	`BasePath`	`"/"`	Branch where the host maps `UseDoconut()`.
`string`	`ResPath`	`"doconut-res"`	Resource base used by the widget. In a normal setup point it to `<ResourcesPath>/images`.
`string`	`FitType`	`"width"`	`"width"`, `"height"`, or empty for no automatic fit. `"page"` is not accepted by the current widget.
`bool`	`RetryOn409`	`false`	Enable polling when asynchronous/distributed page production responds `202 Accepted`; `409` is also accepted for compatibility with older servers. Not needed by the normal synchronous viewer.

csharp

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "/doconut",
    ResPath = "/doconut-res/images",
    ShowHyperlinks = true
};

C# to JavaScript mapping

Do not pass a directly serialized ViewerConfig to docViewer(...). Most widget keys are camelCase, while three established path/fit keys are PascalCase.

C#	JavaScript
`ShowThumbs`	`showThumbs`
`AutoLoad`	`autoLoad`
`AutoFocus`	`autoFocus`
`AutoPageFocus`	`autoPageFocus`
`PageZoom`	`pageZoom`
`ZoomStep`	`zoomStep`
`MaxZoom`	`maxZoom`
`ShowToolTip`	`showToolTip`
`ToolTipPageText`	`toolTipPageText`
`CacheEnabled`	`cacheEnabled`
`LargeDoc`	`largeDoc`
`ShowHyperlinks`	`showHyperlinks`
`FixedZoom`	`fixedZoom`
`FixedZoomPercent`	`fixedZoomPercent`
`FixedZoomPercentMobile`	`fixedZoomPercentMobile`
`BasePath`	`BasePath`
`ResPath`	`ResPath`
`FitType`	`FitType`
`RetryOn409`	`retryOn409`

JavaScript defaults

The widget has older defaults that differ from the C# class. The following values come from the current docViewer.js implementation.

Option	Default	Notes
`leftMinWidth` / `leftMaxWidth`	`220` / `800`	Thumbnail pane width bounds.
`showThumbs`	`true`	Initial thumbnail visibility.
`autoFocus` / `autoPageFocus`	`true` / `false`	`autoPageFocus` differs from the C# default.
`thumbWidth` / `thumbHeight` / `thumbPadding`	`150` / `200` / `10`	Thumbnail geometry in pixels.
`pageZoom` / `zoomStep` / `maxZoom`	`100` / `10` / `200`	JavaScript `maxZoom` differs from C# (`300`).
`showToolTip` / `toolTipPageText`	`true` / `"Page "`	Page-position tooltip.
`format` / `doc` / `AccessToken`	`""` / `0` / `""`	Internal initialization values; normally populated by `View(token)`.
`debugMode`	`false`	Additional client diagnostics.
`FitType`	`""`	No automatic fit unless supplied.
`BasePath`	`"DocImage.axd"`	Historical client default retained for compatibility. Current ASP.NET Core hosts must set it explicitly to the mapped middleware branch.
`ResPath`	`""`	Set explicitly to the embedded images path.
`cacheEnabled` / `cacheCount` / `cacheDelay`	`false` / `3` / `3`	In-memory page preloading window and delay.
`autoLoad`	`false`	Explicit token flow is recommended.
`largeDoc`	`true`	Differs from the C# default.
`fixedZoom`	`false`	Differs from the C# default.
`fixedZoomPercent` / `fixedZoomPercentMobile`	`100` / `50`	Mobile value differs from C# (`75`).
`showHyperlinks`	`true`	Requires server-side extraction to produce overlays.

Set all behaviorally important values instead of relying on either set of defaults:

html

<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

<script>
const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    autoFocus: true,
    autoPageFocus: true,
    pageZoom: 100,
    zoomStep: 10,
    maxZoom: 300,
    FitType: 'width',
    cacheEnabled: false,
    largeDoc: false,
    showHyperlinks: true,
    fixedZoom: true,
    fixedZoomPercent: 100,
    fixedZoomPercentMobile: 75,
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onViewerReady: function () {},
    onError: function (message) { console.error('DocViewer:', message); }
});
</script>

Callbacks

Callback	Arguments	Purpose
`onPageLoading`	`pageNum`	A page request is starting.
`onPageLoaded`	`pageNum`	A page image finished loading.
`onThumbnailClicked`	`pageNum`	The user selected a thumbnail.
`onPageClicked`	`pageNum`	The user selected a page.
`onDoubleClick`	none	The viewer received a double-click.
`onViewerBusy`	none	The viewer entered a busy state.
`onViewerReady`	none	Initialization completed.
`onViewerError`	none	The viewer entered its error state.
`onError`	`message`	An operation returned an error message.
`onCopy`	`data`	Text-copy data is available.
`onAutoLoadStatus`	`pageNum`	Auto-loading progressed to a page.
`onThumbsShown`	none	The thumbnail panel became visible.
`onAnnLoaded`	none	Annotation data loaded.
`onAnnSaved`	none	Annotation data saved.
`onAnnSaveError`	none	Annotation saving failed.
`onAnnClosed`	none	Annotation UI closed.

Keep callbacks fast; send telemetry asynchronously and do not block page rendering.

Public method groups

Group	Common methods
Lifecycle	`View(token, accessToken?)`, `Close(server?)`, `Token()`, `Init()`, `IsLoaded()`
Navigation	`GotoPage(page)`, `ShowPage(page, focus?)`, `Next(next)`, `CurrentPage()`, `TotalPages()`
Zoom and fit	`Zoom(zoomIn)`, `CurrentZoom()`, `FitType(value)`, `Refit()`
Orientation	`Rotate(page, angle)`, `Flip(page, flipType)`
Thumbnails	`HideThumbs(hide)`, `ThumbSize(size)`, `ReloadThumbs(width)`, `ScrollToThumb(thumb)`
Search	`CanSearch()`, `Search(...)`, `SearchMatchCount()`, `SearchSummary(...)`, `GotoSearchMatch(...)`
Annotation	`SaveAnnotations()`, `GetAnnotations()`, `PushAnnotations(...)`, `CloseAnnotations(...)`, `ShowAnnotations(...)`
Copy	`Copy(...)`, `CopyPage(pageNumber)`, `CopyMode(enabled)`

The JavaScript file contains internal helpers too. Treat only methods used by the reference UI and documented here or in the feature guides as stable integration points.

Retry while a distributed page is still rendering

retryOn409 retains its historical name. It is for asynchronous page production and retries the current 202 Accepted readiness response as well as the older 409 Conflict signal. When enabled, the widget polls with these JavaScript defaults:

Option	Default
`retryInitialDelayMs`	`250`
`retryBackoffFactor`	`1.6`
`retryMaxDelayMs`	`2500`
`retryMaxAttempts`	`60`
`retryMaxTotalMs`	`120000`

Leave it disabled for the normal viewer. Enabling it cannot make an unsupported synchronous render asynchronous.

Path checklist

DoconutOptions.MiddlewarePath must describe the branch you actually map.
BasePath must target that branch.
DoconutOptions.ResourcesPath is the embedded resource route.
ResPath normally targets its /images subfolder.
ExtractHyperlinks must be enabled in the server format config before showHyperlinks can display anything.