Add UMD header to viewer.js

[sindilevich]

Adding a UMD header to viewer.js allows using it as a real module in environments that support modular resource loading. Such as require.js and similar.

[timvandermeij]

Could you fix the linting issues? After that, please squash the commits into one commit. Refer to https://github.com/mozilla/pdf.js/wiki/Squashing-Commits for how to do that easily.

[sindilevich]

@timvandermeij, thank you for stepping in. Seems I can't figure out, why the checks are failing. The most recent failure was on ERROR:./web/viewer.js: AMD name does not match module name. Can't understand what name to use here.

[timvandermeij]

I think https://github.com/mozilla/pdf.js/pull/7916/files?w=1#diff-dd42e9b2d2a652b8e312efa567698aa6R22 should be pdfjs-web/viewer, just like https://github.com/mozilla/pdf.js/blob/master/web/app.js#L21. You should also be able to remove https://github.com/mozilla/pdf.js/pull/7916/files?w=1#diff-dd42e9b2d2a652b8e312efa567698aa6R19 as it's already listed a few lines below.

[sindilevich]

@timvandermeij, the 'use strict'; is as here https://github.com/mozilla/pdf.js/blob/master/src/pdf.js#L19. I can remove it from my commit as you've requested, however.

[sindilevich]

@timvandermeij, I work with the repository through a web browser. I don't have git installed. Can I still squash the commits from the web interface?

[sindilevich]

@timvandermeij, looking at GitHub documentation I can see there is an option to squash commits upon merging PR's by repository maintainers (https://github.com/blog/2141-squash-your-commits).

[sindilevich]

@Snuffleupagus, understood, thank you. I added indentation, as most of the code is now a function body, thus should be indented one more level. Do you suggest not to indent, even it is a function body now?

Can you please let me use your code you've tested the PR with? I assume it is a single HTML with a PDF constellation. But I would like to have the exact environment you checked the PR with, making sure I miss nothing.

[sindilevich]

@Snuffleupagus, you've just removed your change request. Does it mean you'll proceed wit h the code as is now?

[Snuffleupagus]

For some reason, it seems that my review comment vanished, hence I'm re-submitting it below.

I work with the repository through a web browser. I don't have git installed. Can I still squash the commits from the web interface?

Please follow the work-flow described in https://github.com/mozilla/pdf.js/wiki/Contributing, see also https://github.com/mozilla/pdf.js#getting-the-code, since this allows you to actually test the changes made in the PR locally, to ensure that it works as intended!

Having just tested the PR locally, using gulp server (as described in the links above), I'm sorry to have to tell you that in its current form this PR does not actually work.
Hence this needs to be addressed, before we can test/review this PR properly.

Furthermore, please revert all the indentation changes made in the PR. We want to avoid unnecessarily changing the blame on every single line in this file. (This is consistent with the adding of UMD headers in all other files, which is the only case where not indenting is acceptable.)

Finally, as outlined in https://github.com/mozilla/pdf.js/wiki/Squashing-Commits, please squash the commits; we want to avoid a PR landing with "broken" intermediate commits.
Since you'll need to follow the contribution guidelines linked above anyway, in order to test the PR, squashing shouldn't be a problem.

[yurydelendik]

The concrete example is needed how it is/will be used. I have a feeling that this PR is incomplete solution and will be needing further and bigger chunk of work to be published at pdfjs-dist. At the moment app.js is better entry point and already has all needed API to create a custom viewer.

[sindilevich]

@yurydelendik, the general idea is that you'd use a module loader, such as require.js to load viewer.jsand, then, run it at an appropriate lifecycle of the page/web application. PDF.js is already module-loader compatible in its core: pdf.js and pdf.worker.js. This PR would allow the same paradigm for viewer.js as well.

One of drawbacks of the current state of viewer.js is that it is hardcoded loading upon DOM loaded event. Yet some advance uses may require additional setup/layout/etc. work to be done before viewer.js loads and displays a PDF file.

I'll try to change the test files as well to use require.js with viewer.js, as a reference implementation.

[yurydelendik]

the general idea is that you'd use a module loader, such as require.js to load viewer.js

I understand what you are trying to do, but I don't see who and how will benefit from the change. Please provide example that will consume the patched viewer.js and how it's different from just loading non-patched viewer.js.

[sindilevich]

@Snuffleupagus, reverted the indentation and fixed viewer.html to absorb the module nature of viewer.js. Am not 100% sure about the way I've handled DEFAULT_URL, maybe the viewer.js module itself should put it global, through the pdfjs/display/global module.

@yurydelendik, viewer.html consumes the module version of viewer.js now. Sometimes it is required the window with a PDF.js viewer will show a PDF only at a later stage in page's lifecycle. For example, a customer requirement: the user gives his/her consent to view a PDF file on the PDF viewer page itself; only users that have explicitly agreed can view the PDF; user consent is audited and logged. Another example: using PDF.js as a part of a tabbed page, without an iframe; only display a PDF, when you switch to the PDF viewer tab. I am pretty sure that 1) breaking the hardcoded dependency on the DOMContentLoaded event, 2) introducing a mechanism of a manual bootstrap of the PDF.js viewer, and 3) tidying up the global scope even more brings its benefit in a vast majority of development scenarios.

I hope you'd agree. Thank you in advance.

[sindilevich]

@Snuffleupagus, re-worked the global export of DEFAULT_URL.

[yurydelendik]

I am pretty sure that 1) breaking the hardcoded dependency on the DOMContentLoaded event, 2) introducing a mechanism of a manual bootstrap of the PDF.js viewer, and 3) tidying up the global scope even more brings its benefit in a vast majority of development scenarios.

Agree with above, plus I'm adding few of my own:
4) refactor UI to not use document.getElementById or similar queries from global page context;
5) create UI from the JS instead of having static HTML

I'm blocking this PR with the items above.

[sindilevich]

@yurydelendik, thank you for the review. I can think about yet another commit that will solve the enhancement №4: "refactor UI to not use document.getElementById or similar queries from global page context".

I could make the viewer.js.run() method take an options: Object parameter. One of the properties of the options method would be called, say, host: DOMElement. Then I could revise other parts of the viewer.js suite to use that host object as the scope for DOM queries and events.

The only tricky part here, is the very different nature of viewer.js when it is compiled vs. at development. The compiled viewer.js keeps all the other modules inside of itself. That way declaring a variable at the scope of the enclosing IIFE, makes this variable accessible by every part that comprises viewer.js. When working with the sources, you somehow need to pass that reference to the DOM element from outside to every module, required by viewer.js.

I would like to hear your opinion, please.

[yurydelendik]

The only tricky part here, is the very different nature of viewer.js when it is compiled vs. at development.

You can just use web/app as "main" module for your app and use your choice of packager to produce your own bundle.

[yurydelendik]

That said, I probably would like to see pdf_viewer.js to contain all the classes including app.js but this effort is blocked by the items mentioned above

[sindilevich]

@yurydelendik, this PR already resolves items: 1, 2, and 3. But I don't feel myself confident enough in PDF.js codebase to also resolve items 4 and 5. Would be glad for any help, though.

[timvandermeij]

Closing for now since there has been no more progress in a few months and we're moving away from UMD headers in favor of ES6 modules soon anyway (see https://github.com/mozilla/pdf.js/projects/3).