Topics

• Parameters
• Using the macro from WYSIWYG editor
• Using the macro from wiki editor (code)
  • PDF file attached to a wiki page
  • PDF file attached to a terminal wiki page
  • PDF accessed from an external resource via URL
• Display multiple PDF files in the same page using a tab system layout
• Manually register mime type for ECMAScript modules (.mjs)
• Administration Page
  • Trusted Origins
  • With Credentials

Parameters

Below are described the parameters of the PDF Viewer Macro that need be used in order to define the way a PDF file is displayed in a wiki page.

Name	Pretty name	Mandatory?	Default	Description
asauthor	Delegate my view right		0	If this value is true (or 1 or yes) and the viewing user has no access to the document containing the PDF file, the PDF file could still be viewed on behalf of your view right (as long as you have view right on the containing document). This parameter is helpful when you want to add to a page B a macro pointing to the PDF from another page A, that is protected for some users. Note that the view right is delegated only if the last person that saved page B had indeed view rights on page A. Also, this will not alter the view right on page A.
document	Document		current document	Reference to the XWiki document to which the file is attached (e.g. xwiki:Path.To.Document). The xwiki: part can be ignored if the file is located in the current wiki). If file argument is an absolute URL, this argument is ignored.
file	File		N/A	Name or the absolute URL of the PDF file.
height	Height		1000	The viewer height, accepts values in pixels or in percentage.
width	Width		100%	The viewer width, accepts values in pixels or in percentage.

Using the macro from WYSIWYG editor

Edit a wiki page in WYSIWYG mode and look in the tool bar for the icon (XWiki Macro), search for PDF Viewer Macro and fill in the parameters values. 

Using the macro from wiki editor (code)

PDF file attached to a wiki page

To note that when using this option to display a PDF on a wiki page, the URL for the PDF will be generated using the XWiki API which can handle different setups for the wiki (path based, domain based, alias updates, etc).

PDF file attached to a terminal wiki page

When having a PDF file attached to a terminal page, the syntax is slightly different, leaving out the "WebHome" mention.

PDF accessed from an external resource via URL

When using an absolute/explicit URL to display the PDF on a wiki page, keep in mind that you might need to update the URL if the alias of the source where the PDF is located will be changed.

Display multiple PDF files in the same page using a tab system layout

Add more PDF files, separated by comma.

Manually register mime type for ECMAScript modules (.mjs)

PDF Viewer Macro (Pro) is based on pdf.js which uses ECMAScript modules. This requires the registration of the mime type for ECMAScript modules (.mjs), which should occur automatically. If the automatic registration fails, manual actions are required.

The administrator should manually add the custom-mimetypes.xml file inside the XWiki WAR at the path: WEB-INF/classes/org/apache/tika/mime/.

Administration Page

Trusted Origins

If you use URLs of PDFs from external domains, you might encounter an error with the following message `Message: file origin does not match viewer's`.

This error appears, as the message suggests, because domain of the viewer is different from the domain where the pdf is located.

To avoid this problem, you should append the domain of you wiki and/or subwiki to the `Trusted Origins` field of the Administration Section.

With Credentials

If you are trying to access pdf files located on servers that need authentication and your cookies contain the validation data, you will need to set the `With Credentials` field to yes. This way, the cookies will be forwarded when making a request to the said pdf file.

Installation Steps

This paid extensions requires XWiki 13.10 or above. In order to install the extension, follow the next steps inside your XWiki instance (on cloud or on premise).

Navigate to the Extension Manager

In the Applications Panel click on "More Applications..." and then "Install new applications...". Alternatively navigate directly to the Administration and select the "Extensions" section.

Install the Extension

Search for the extension you wish to install and use the Install button to install it.

Get a License

Navigate to the "Licenses" section of the Administration, fill your details, look for the extension you just installed in the live table and click the buttons to get a trial license or to buy a license.

Install the License

If you have selected a trial license then you're good and there's nothing else to do. Your trial license is automatically installed.

However if you've selected to buy a license you'll be redirected to a page to perform the payment. At the end you need to come back to the "Licenses" administration section and click on the "Check for Updates" button. This will download and apply the license you bought.

Use the Extension

Start using the Extension! Refer to the extension's documentation to know how to use it.

Installing Paid Apps on Subwikis

If you want to install an application on the whole farm (main wiki + subwikis), you can do so directly from the main wiki’s Extension Manager, as seen below:

Extensions can also be installed only on a particular subwiki by global admins. Subwiki admins will not be able to install these extensions due to their limited rights.

Options

The price is per year and varies depending on the support level and the number of users.

Benefits

What do you get when you purchase an XWiki extension?

How to Buy

To buy, install this extension from inside your XWiki instance and follow the instructions.

Release notes

v2.6

Upgrades:

• #62 Upgrade pdf.js to v4.2.67.
• #63 Upgrade parent version to 14.10.

v2.5.6

Security:

• Fixed 3 security issues.

v2.5.5

• #66 PDF viewer is breaking the editor's "add macro" dialog in XWiki 16.4.1

v2.5.4

Upgrades:

• #59 Upgrade Licensor dependency to version 1.25

v2.5.3

Upgrades:

• #53 Upgrade Licensor dependency to version 1.24.3

v2.5.2

Bugs fixed:

• #48 The PDF file isn't shown when it contains a comma in the title

v2.5.1

Bugs fixed:

• #52 PDFViewer page should be hidden
• #46 Link to Licenses section is not displayed properly in the info message when there is no valid license
• #49 User with no view rights on a page can see a PDF in another page even if the "asauthor" value is set to 0 or false when using an absolut/explicit URL

v2.5

Bugs fixed:

• #43 The file parameter cannot be edited correctly when comprising multiple entries
• #44 The "Upload file" button does not appear when trying to upload using the PDF Viewer Macro, if edit right is not given at wiki level to that group/user

Tasks done:

• #47 Upgrade parent to 13.10-3

Upgraded licensing version to 1.24.1.

v2.4

Improvements:

• #40 Add a copyable link of the PDF file location in the macro toolbar

Update the Licensing dependency version to 1.22.1

v2.3.3

Update the Licensing dependency version to 1.22

v2.3.2

Regressions fixed:

• #10 XWiki custom improvements skipped at upgrade.
• #15 External PDFs are not displayed

Caused by:

• #7 Remove bundling of pdf.js sources from this extension

v2.3.1

Bugs fixed:

• #35 PDF files with spaces in their names are not properly viewed anymore.

v2.3

Improvements:

• #7 Remove bundling of pdf.js sources from this extension.
• #9 Electronic signature is not displayed.
• #24 Differences between the document from the attachment picker and the document macro paremeter.

Bugs fixed:

• #22 File picker field prevent from displaying file outside the current page.
• #28 The macro is not working on certain XWiki versions.

Upgrades:

• #26 Update the minimal supported version to XWiki 11.10.
• Update the Licensing dependency to version 1.20.

v2.2.1

• Upgrade the Licensing dependency to version 1.17.1
• Make the PDF Viewer macro discoverable by the Extension Manager (without installing it)
• Fix the attachment picker for the file macro parameter

v2.2

Improvements:

• #14 PDF Viewer Macro not modified to support attachment picker.

v2.1.1

Improvements:

• #17 External PDFs are not displayed using credentials.

v2.1

Bugs fixed:

• #15 External PDFs are not displayed.

Improvements:

• #10-1 Open the links inside the PDF documents in a new tab.
• #10-2 Allow author of the macro to delegate its view right on the PDF document.
• #16 Update PDF.js version from 2.1.266 to v2.5.207. Release notes: https://github.com/mozilla/pdf.js/releases/tag/v2.5.207
• #13 Update XWiki parent version to 9.11

v2.0.3

Update the Licensing dependency to version 1.14.4.

v2.0.2

Update the Licensing dependency to version 1.14.3.

v2.0.1

Bugs fixed:
#11 Some attachments don't work as expected anymore.

v2.0

Update the PDF.js dependency from version 1.1.3 to version 2.1.266. Full list of changes on https://github.com/mozilla/pdf.js/releases.

v1.9.4

Update the Licensing dependency to version 1.13.8.

v1.9.3

Update the Licensing dependency to version 1.13.4.

v1.9.2

Update the Licensing dependency to version 1.13.3.

v1.9.1

Update the Licensing dependency to version 1.13.2.

v1.9

Improvement:
#5 Display several PDF files using a tab system layout.

v1.8.3

Update the Licensing dependency to version 1.13.

v1.8.2

Update the Licensing dependency to version 1.12.2.

v1.8.1

Update the Licensing dependency to version 1.12.1.

v1.8

Improve the message displayed when there is no valid license.

v1.7

Initial paid version.

Extension details

License

• GNU Lesser General Public License 2.1

Sources

• https://github.com/xwikisas/macro-pdfviewer/tree/master/macro-pdfviewer-ui

Issues

• GitHub

Type

• xar

Developed by

• XWiki SAS

Compatibility

• Requires XWiki 13.10 or above.

Dependencies

• org.webjars:requirejs 2.3.6
• org.webjars:jquery 3.6.0
• com.xwiki.licensing:application-licensing-licensor-api 1.25
• com.xwiki.pdfviewer:macro-pdfviewer-api 2.6