finna-pdf-viewer

Features

• Searching
• Printing
• Sidebar with thumbails, outlines, and attachments
• Rotating
• Download and upload
• Zoom
• Full-screen mode
• various selection tools
• standard display or even / odd spreads (like a book)
• various approaches to scrolling (vertical, horizontal, "wrapped" scrolling)
• Internationalization (providing translations to several dozen languages)
• plus the ability to deactivate each of these features.

Not to mention the ability to display PDF files, running on Mozilla's pdf.js 2.1.266.

Compatibility to Bootstrap (and other CSS frameworks)

Bootstrap interferes with the printing algorithm of pdf.js. Guard it with a media query to avoid unwanted effects, such as scaling the print to 65%. For example, if you're using SCSS and Bootstrap 4, remove the import of Bootstrap.min.css from the Angular.json file. Instead, import it by including Bootstrap by adding this line to the global styles.scss file:

@media screen {
  @import '../node_modules/bootstrap/scss/bootstrap';
}

## How to use the library



1.  Install the library with npm i finna-pdf-viewer --save
2.  Open the file "angular.json" (or ".angular-cli.json" if you're using an older version of Angular)
    and add these three JavaScript files to the "scripts" section:

            "scripts": [
              "node_modules/finna-pdf-viewer/assets/pdf.js",
              "node_modules/finna-pdf-viewer/assets/pdf.worker.js",
              "node_modules/finna-pdf-viewer/assets/viewer.js"
            ]

3.  Add the translations to the assets by adding them to the "assets" section in the angular.json:

            "assets": [
              "src/favicon.ico",
              "src/assets",
              {
                "glob": "**/*",
                "input": "node_modules/finna-pdf-viewer/assets/locale",
                "output": "/assets/locale/"
              }
            ]

    If you need only one language, you can reduce the list to 'locale.properties' and your language folder.

    _Hint:_ There are two ways to define the language files needed for the labels of the buttons and screen elements of the PDF viewer. The second method is described below in the "internationalization" section.

4.  Add "FinnaPdfViewerModule" to the import section of your module file. If your IDE doesn't find
    the import automatically, here it is:

          Finna } from 'finna-pdf-viewer';

5.  Now you can display the PDF file like so:

```html
<finna-pdf-viewer [src]="'assets/example.pdf'" useBrowserLocale="true"> </finna-pdf-viewer>

6. If you want to display a PDF file you've downloaded from a server, you probably have a Blob instead of an URL. You can simply use URL.createObjectURL() to convert this Blob into something the PDF viewer can display:

<finna-pdf-viewer [src]="currentPdf"></finna-pdf-viewer>

public currentPdf: DOMString = null;

set src(input: Blob) {
  this.currentPdf = URL.createObjectURL(input);
}

Configuration

Legend:

• [(attribute)] attribute with two-way-binding
• [attribute] PDF-viewer reacts when the attribute changes
• attribute attribute is used at load time only (subsequent changes are ignored)

| Attribute | mandatory? | default value | description | | ---------------------------- | :----------: | :-------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | [src] | yes | | defines the URL of the PDF file to display. | | [backgroundColor] | no | ? | background color | | [height] | no | 80vh | define the height of the PDF window. By default, it's 80vh (i.e. 80% of the screen height). | | useBrowserLocale | no | false | if true, the PDF viewer assumes the locale files are in the assets folder. If false, you are responsible for providing the translated texts. | | delayFirstView | no | 0 | Number of milliseconds to wait between initializing the PDF viewer and loading the PDF file. Most users can let this parameter safely at it's default value of zero. Set this to 1000 or higher if you run into timing problems (typically caused by loading the locale files after the PDF files, so they are not available when the PDF viewer is initialized). | | [showSidebarButton] | no | true | Show or hide the button to toggle the sidebar | | [mobileZoom] | no | 100% | This attributes allows you to increase the size of the UI elements so you can use them on small mobile devices. Must be a percentage. | | | showSidebarOnLoad | no | undefined | If this flag is set to "false", the sidebar is hidden until the user clicks the "show sidebar" button. If this flag is set to "true", the sidebar is shown (unless [showSidebarButton]="false"). If the flag is undefined, the setting used when the PDF file was shown previously is used. | | [showFindButton] | no | true | Show or hide the "find" button | | [showPagingButtons] | no | true | Show or hide the buttons to navigate between pages and the input field to navigate to a particular input field | | [showZoomButtons] | no | true | Show or hide the "zoom" button | | [showPresentationModeButton] | no | true | Show or hide the "full screen" button | | [showOpenFileButton] | no | true | Show or hide the "open file" button | | [showPrintButton] | no | true | Show or hide the "print" button | | [showDownloadButton] | no | true | Show or hide the "download" button (aka "save" button) | | [showBookmarkButton] | no | true | Show or hide the "bookmark" button | | [showSecondaryToolbarButton] | no | true | Show or hide the secondary toolbar (the menu hiding behind the arrows at the right-hand side) | | [showRotateButton] | no | true | Show or hide the "rotate" menu items in the secondary toolbar | | [showSelectToolButton] | no | true | Show or hide the "select text" menu item in the secondary toolbar | | [showHandToolButton] | no | true | Show or hide the "hand tool" menu item in the secondary toolbar. (The hand tool allows you to move the page by clicking and dragging) | | [showScrollingButton] | no | true | | | [showSpreadButton] | no | true | Show or hide the "spread" menu items in the secondary toolbar | | [showPropertiesButton] | no | true | Show or hide the "show document properties" menu item in the secondary toolbar | | [handTool] | no | false | setting this flag to true, activates the "hand tools" to scroll the PDF file by dragging. Setting this to false aktivate the "text selection" tool. | | [(page)] | no | undefined | two-way binding attribute to determine the page to display; more precisely: [page]="25" makes the PDF viewer show page 25 (at any time - even after load time); (page)="attribute" updates the attribute each time the user scrolls to another page | | [(zoom)] (two-way binding) | no | undefined | [zoom]="undefined" (default value): use the zoom level configured previously by the user, or "auto" if no configuration was found. If not undefined: Set the zoom level of the page, no matter which zoom level was previously configured. Legal values are [zoom]="'auto'", ="'page-actual'", ="'page_fit'", ="'page-width'", or ="50" (or any other percentage). Numbers are always considered percentages; the trailing "%" character is optional. This attribute supports two-way binding. [(zoom)]="zoomAttribute" updates the variable zoomAttribute each time the user changes the zoom setting. This is useful to use the same zoom accross multiple PDF viewer instances or PDF document. |

Internationalization

Slow default way

If you add the translation files to your project as described above in step 3, the PDF viewer uses the browser language setting to determine which language to load. First, it loads the locale.properties, scans it for the desired language files, and loads the language file from the corresponding folder. That's two additional (and even consecutive) HTTP calls. That's slow, and it may even lead to errors if the network is already congested loading other resource files.

Don't forget to set the attribute useBrowserLocale="true" if you follow this approach.

Slow way with custom translation files

If you want to use the slow way, but prefer to load the language files from a different URL, add a link to your application like so:

<link rel="resource" type="application/l10n" href="https://www.example.com/locale/locale.properties" />

In this case, don't set useBrowserLocale (or set it explicitely to false).

Inlining (aka embedding) the language files

Alternatively, you can provide the translations as a Json file. This Json file has to be part of the HTML page, like so:

<script type="application/l10n">
  {"default_locale":"de","locales":{"de": ... }}
</script>

Hint: Sometimes you need to copy the HTML snippet into the index.html at the root folder of the Angular project. The bottom line is that the HTML snippet is already part of the DOM when the PDF viewer is initialized. Cluttering the root index file with the translations is an ugly and inflexible hack, but it works.

If you're using the "inline" approach, don't set useBrowserLocale (or set it explicitely to false).

Troubleshooting

| Error message or description | Solution | | ----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | "TypeError: Cannot read property 'setPagesCount' of null" | The language files couldn't be loaded. If you're following the default approach, useBrowserLocale="true". In any case, check whether the language files are part of your project and if they are loaded from the correct path. Note that there's no default translation. You have to load a language file for any language, including English. In rare cases the language files are loaded, just not in time. In this case increase the value of delayFirstView. | | The browser locale is ignored. | The HTML snippets in the folder node_modules/finna-pdf-viewer/assets/inline-locale-files contain exactly one language. If you want to support multiple language, you have to add the additional languages to the Json data structure. | | sticky toolbar (when scrolling, the pdf file appears above the toolbar) | This happens if you're using the z-index to position the <finna-pdf-viewer>. If you can't avoid to do so, add the global CSS rule .body .toolbar { z-index: 0; }. The PDF viewer works without the z-index of the toolbar. The only difference is that the shadow of the toolbar is hidden by the PDF document. | | Print also includes UI elements | Usually, the entire screen is hidden automatically, but sometimes this fails, especially with widgets that are dynamically added, such as error messages, progress bars, and block UI overlays. Use media queries to hide the unwanted UI elements. For example, use something like @media print { #modal-error-dialog: display none; }. |

License

The library is based on https://github.com/mozilla/pdf.js, which has been published under an Apache V2 license.