Improve the viewer layer documentation

[Navds]

It would be straightforward to get started from the upper layer that is the viewer. Unfortunately, every tutorials and examples show basic display functionalities such as how to render a page in a canvas, how to add previous and next button, etc.
https://github.com/mozilla/pdf.js/wiki/Viewer-options is the only available resource on the viewer. There is no indication on how to customize it, like:

• How to reskin while being compatible with an upstream update ?
• How to pass request headers to the server serving the requested file ?
• How to disable/enable such and such options ?
• How to switch from continuous scrolling to single page per view ?

[Snuffleupagus]

Generally speaking: Please note that the lack of proper documentation for the default viewer is somewhat on purpose, given http://mozilla.github.io/pdf.js/getting_started/#introduction (emphasis mine):

The viewer is built on the display layer and is the UI for PDF viewer in Firefox and the other browser extensions within the project. It can be a good starting point for building your own viewer. However, we do ask if you plan to embed the viewer in your own site, that it not just be an unmodified version. Please re-skin it or build upon it.

[Navds]

Yeah, It clearly advises to re-skin it or build upon it but don't give enough materials on how.

[znap026]

So are you saying that viewer.js should not be used?

[GAGANsinghmsitece]

It's difficult to re-skin it as there are no docs available on how to customise its skin

[mstralka]

I agree that more documentation and examples for customizing the viewer would be extremely helpful.

For example, we want to hide the Save and Print buttons in certain situations:

[anggafsahid]

I am trying to re-skin it to hide some button in toolbar with editing viewer.html file and viewer.css file.
although I can hide some button in toolbar and change the button style,

but without documentation it was difficult, especially when you try to resize, change color and reposition the button.

when I saw this instruction on Github

Generally speaking: Please note that the lack of proper documentation for the default viewer is somewhat on purpose, given http://mozilla.github.io/pdf.js/getting_started/#introduction (emphasis mine):

The viewer is built on the display layer and is the UI for PDF viewer in Firefox and the other browser extensions within the project. It can be a good starting point for building your own viewer. However, we do ask if you plan to embed the viewer in your own site, that it not just be an unmodified version. Please re-skin it or build upon it.

I thought there is documentation for re-skin it or build upon it, as they say it as if it's easy to re-skin or build upon it, but there isn't.

[Snuffleupagus]

How to reskin while being compatible with an upstream update ?

Considering that the default viewer is written specifically to be used as the built-in PDF Viewer in Firefox, general re-use has never been a priority and we thus need to be able to make backwards incompatible changes where that makes sense for the Firefox use-case. (The viewer components, see https://github.com/mozilla/pdf.js/tree/master/examples/components, on the other hand should not break in backwards incompatible ways when updating.)

Hence we cannot guarantee that updating the default viewer will always work, however making e.g. CSS-only changes should reduce the risk of breakage when updating. Another good idea is to update frequently, and not wait e.g. a year before doing so, since that should also limit the number of changes that you need to deal with.

Please keep in mind that the versioning in this library is based on the API (see https://github.com/mozilla/pdf.js/blob/master/src/display/api.js) and also on the viewer components (see https://github.com/mozilla/pdf.js/blob/master/web/pdf_viewer.component.js), however the default viewer is not included in the versioning.

How to pass request headers to the server serving the requested file ?

Please note the following getDocument option

pdf.js/src/display/api.js

Line 134 in 41dab8e

* @property {Object} [httpHeaders] - Basic authentication headers.

, or if you're using the default viewer please see

pdf.js/web/app.js

Lines 876 to 885 in 41dab8e

	/**
	* Opens PDF document specified by URL or array with additional arguments.
	* @param {string|TypedArray|ArrayBuffer} file - PDF location or binary data.
	* @param {Object} [args] - Additional arguments for the getDocument call,
	* e.g. HTTP headers ('httpHeaders') or alternative
	* data transport ('range').
	* @returns {Promise} - Returns the promise, which is resolved when document
	* is opened.
	*/
	async open(file, args) {

How to disable/enable such and such options ?

It's unclear exactly what "options" that's referred to here, and if it's the API or the default viewer that's relevant.
For the API itself, see e.g.

pdf.js/src/display/api.js

Lines 126 to 218 in 41dab8e

	/**
	* Document initialization / loading parameters object.
	*
	* @typedef {Object} DocumentInitParameters
	* @property {string|URL} [url] - The URL of the PDF.
	* @property {TypedArray|Array<number>|string} [data] - Binary PDF data. Use
	* typed arrays (Uint8Array) to improve the memory usage. If PDF data is
	* BASE64-encoded, use `atob()` to convert it to a binary string first.
	* @property {Object} [httpHeaders] - Basic authentication headers.
	* @property {boolean} [withCredentials] - Indicates whether or not
	* cross-site Access-Control requests should be made using credentials such
	* as cookies or authorization headers. The default is `false`.
	* @property {string} [password] - For decrypting password-protected PDFs.
	* @property {TypedArray} [initialData] - A typed array with the first portion
	* or all of the pdf data. Used by the extension since some data is already
	* loaded before the switch to range requests.
	* @property {number} [length] - The PDF file length. It's used for progress
	* reports and range requests operations.
	* @property {PDFDataRangeTransport} [range] - Allows for using a custom range
	* transport implementation.
	* @property {number} [rangeChunkSize] - Specify maximum number of bytes fetched
	* per range request. The default value is {@link DEFAULT_RANGE_CHUNK_SIZE}.
	* @property {PDFWorker} [worker] - The worker that will be used for loading and
	* parsing the PDF data.
	* @property {number} [verbosity] - Controls the logging level; the constants
	* from {@link VerbosityLevel} should be used.
	* @property {string} [docBaseUrl] - The base URL of the document, used when
	* attempting to recover valid absolute URLs for annotations, and outline
	* items, that (incorrectly) only specify relative URLs.
	* @property {string} [cMapUrl] - The URL where the predefined Adobe CMaps are
	* located. Include the trailing slash.
	* @property {boolean} [cMapPacked] - Specifies if the Adobe CMaps are binary
	* packed or not.
	* @property {Object} [CMapReaderFactory] - The factory that will be used when
	* reading built-in CMap files. Providing a custom factory is useful for
	* environments without Fetch API or `XMLHttpRequest` support, such as
	* Node.js. The default value is {DOMCMapReaderFactory}.
	* @property {boolean} [useSystemFonts] - When `true`, fonts that aren't
	* embedded in the PDF document will fallback to a system font.
	* The default value is `true` in web environments and `false` in Node.js;
	* unless `disableFontFace === true` in which case this defaults to `false`
	* regardless of the environment (to prevent completely broken fonts).
	* @property {string} [standardFontDataUrl] - The URL where the standard font
	* files are located. Include the trailing slash.
	* @property {Object} [StandardFontDataFactory] - The factory that will be used
	* when reading the standard font files. Providing a custom factory is useful
	* for environments without Fetch API or `XMLHttpRequest` support, such as
	* Node.js. The default value is {DOMStandardFontDataFactory}.
	* @property {boolean} [useWorkerFetch] - Enable using the Fetch API in the
	* worker-thread when reading CMap and standard font files. When `true`,
	* the `CMapReaderFactory` and `StandardFontDataFactory` options are ignored.
	* The default value is `true` in web environments and `false` in Node.js.
	* @property {boolean} [stopAtErrors] - Reject certain promises, e.g.
	* `getOperatorList`, `getTextContent`, and `RenderTask`, when the associated
	* PDF data cannot be successfully parsed, instead of attempting to recover
	* whatever possible of the data. The default value is `false`.
	* @property {number} [maxImageSize] - The maximum allowed image size in total
	* pixels, i.e. width * height. Images above this value will not be rendered.
	* Use -1 for no limit, which is also the default value.
	* @property {boolean} [isEvalSupported] - Determines if we can evaluate strings
	* as JavaScript. Primarily used to improve performance of font rendering, and
	* when parsing PDF functions. The default value is `true`.
	* @property {boolean} [disableFontFace] - By default fonts are converted to
	* OpenType fonts and loaded via the Font Loading API or `@font-face` rules.
	* If disabled, fonts will be rendered using a built-in font renderer that
	* constructs the glyphs with primitive path commands.
	* The default value is `false` in web environments and `true` in Node.js.
	* @property {boolean} [fontExtraProperties] - Include additional properties,
	* which are unused during rendering of PDF documents, when exporting the
	* parsed font data from the worker-thread. This may be useful for debugging
	* purposes (and backwards compatibility), but note that it will lead to
	* increased memory usage. The default value is `false`.
	* @property {boolean} [enableXfa] - Render Xfa forms if any.
	* The default value is `false`.
	* @property {HTMLDocument} [ownerDocument] - Specify an explicit document
	* context to create elements with and to load resources, such as fonts,
	* into. Defaults to the current document.
	* @property {boolean} [disableRange] - Disable range request loading of PDF
	* files. When enabled, and if the server supports partial content requests,
	* then the PDF will be fetched in chunks. The default value is `false`.
	* @property {boolean} [disableStream] - Disable streaming of PDF file data.
	* By default PDF.js attempts to load PDF files in chunks. The default value
	* is `false`.
	* @property {boolean} [disableAutoFetch] - Disable pre-fetching of PDF file
	* data. When range requests are enabled PDF.js will automatically keep
	* fetching more data even if it isn't needed to display the current page.
	* The default value is `false`.
	*
	* NOTE: It is also necessary to disable streaming, see above, in order for
	* disabling of pre-fetching to work correctly.
	* @property {boolean} [pdfBug] - Enables special hooks for debugging PDF.js
	* (see `web/debugger.js`). The default value is `false`.
	*/

For the default viewer, options can be set using either the Preferences and/or the AppOptions, please see https://github.com/mozilla/pdf.js/blob/master/web/preferences.js and https://github.com/mozilla/pdf.js/blob/master/web/app_options.js

Possibly https://github.com/mozilla/pdf.js/wiki/Third-party-viewer-usage is also helpful here.

How to switch from continuous scrolling to single page per view ?

Please see PR #14112, which is available in the latest release; see https://mozilla.github.io/pdf.js/getting_started/#download.