PDFs Not Launching Correctly from WebHelp

[MichaelDa]

Hi.

As I mentioned in previous threads, we recently upgraded from Oxygen Author 13.2 to 14.2, and have experienced some issues with the new WebHelp format that are affecting our users. The latest is related to opening PDFs from hyperlinks in WebHelp. They are not opening in a new tab, or they are not opening at all. Please see below for test cases.

Questions:

1) Is there a fix for this issue so that PDFs open in a new tab in WebHelp?

2) Is there a setting in Oxygen Author that would force PDFs to open in a new tab from WebHelp?


Test Case 1:

Demonstrate the current issue:

1) Open the latest version of our Documentation Library, created with Author 14.2 WebHelp.

2) In the topic AgilePoint Documentation Library, in the PDF column of the table, click v5.0 SP4 Release Notes.

Observed result A: In some browsers, the PDF opens in the content (right) pane.

Observed result B: In some browsers, the PDF does not open. Instead, the content (right) pane shows a blank white page.

Expected result: The PDF opens in a new tab.

DITA Markup for this link and all other PDF links on this page:

Code: Select all

<xref href="AgilePoint_ReleaseNotes_5_0_SP_4.pdf" scope="external" format="html">v5.0 SP4 Release Notes</xref>

3) Click the Back button on the browser to return to the AgilePoint Documentation Library page.

4) In the PDF column of the table, click v5.0 SP3 Universal Edition Release Notes.

Observed result: The PDF does not open. Instead, the content (right) pane shows a blank white page.

Expected result: The PDF opens in a new tab.



Test Case 2:

Compare the results of Test Case 1 to an older version of our Documentation Library using WebHelp generated from Author 13.2:

1) Open an older version of our Documentation Library, created with Author 13.2 WebHelp.

2) In the topic AgilePoint Documentation Library, in the PDF column of the table, click v5.0 SP4 Release Notes.

Observed result: The PDF opens in a new tab.

3) Return to the tab with the AgilePoint Documentation Library page.

4) In the PDF column of the table, click v5.0 SP3 Universal Edition Release Notes.

Observed result: The PDF opens in a new tab.



Test Case 3:

Demonstrate this issue seems to only be occurring with links to PDFs, not external web pages:

1) Open this topic, created with Author 14.2 WebHelp.

2) In the topic Why Does an "Input String" Error Occur During Envision Installation?, in the More Information section, click the URL http://www.mydigitallife.info/how-to-di ... windows-7/.

Observed result: The external web page opens in a new tab.

DITA Markup for this link:

Code: Select all

<xref href="http://www.mydigitallife.info/how-to-disable-and-turn-off-uac-in-windows-7/" format="html" scope="external">http://www.mydigitallife.info/how-to-disable-and-turn-off-uac-in-windows-7/</xref>

[MichaelDa]

I forgot to mention that this issue is observed on multiple machines on Mac and Windows, in IE, Safari, and Chrome.

Thanks.

[sorin_ristache]

Hi,

There is a difference between test cases 1 and 2 because versions 13.2 and 14.2 of Oxygen include different versions of the DITA-OT toolkit. I think the actual result from test case 1 is correct because you have attribute scope="external" which means the resource is external to the DITA process and an external process (e.g. other application, a different install process executed by the user, etc) must make sure that the resource exists at the referenced location. This is why in test case 3 the referenced URL (http://www.mydigitallife.info/how-to-di ... windows-7/) is opened correctly: the resource exists at that location independent of the DITA transformation.

I suggest setting on the xref element in the XML source file the attributes scope="local" for having the PDF file copied to the output directory and format="pdf" because it is a PDF file, not an HTML file. If you set these attributes the link will work as expected in the Webhelp output in browser.


Regards,
Sorin

[MichaelDa]

HI Sorin.

This does not appear to be an issue with the DITA-OT. The Frames-based WebHelp output still works as expected when generated from Author 14.2. See Test Case 4 below.

Also, I tried the changes you suggested: Change scope="local" and format="pdf". Changing the scope seems to change whether the file tries to open in a new tab in Chrome, but does not change whether the file open is successful or not. (File open still fails, and I get a blank white content (right) pane.) In Safari this change has no observable effect. Changing the format to PDF has no observable effect. I still have the same errors noted in Test Case 1 above.


Test Case 4:

Demonstrate the issue does not occur in frames-based WebHelp in Author 14.2:

1) Open the latest version of our Documentation Library, created with Author 14.2 WebHelp.

2) Click the With Frames icon in the upper right corner.

The Frames-based WebHelp (index_frames.html) opens. This is auto-generated from Oxygen Author 14.2 along with the JavaScript-based WebHelp with no customizations other than topic CSS.

3) In the topic AgilePoint Documentation Library, in the PDF column of the table, click v5.0 SP4 Release Notes.

Observed result: The PDF opens in a new tab without errors. This is the same behavior in 13.2 frames-based WebHelp output, and the behavior we would expect.

You can repeat step 3 a few times with various links in the PDF column to confirm they are working as expected.

[sorin_ristache]

Hi,

I tested your situation in test case 4 on a simple DITA map and the result is the same as I said above for both the internal frames version (the index.html main file) and the frameset version (the index_frames.html main file, the version opened by the link With Frames), that is:

• the link to a PDF file does not work if the xref element has the scope="external" attribute; this is correct behavior because, as I said above, for this attribute value the PDF file is not copied to the output directory, but the PDF file must be copied there by other means (this is the meaning of the scope="external" attribute); you can test this yourself by removing completely the output directory of the Oxygen Webhelp transformation, checking that you have the scope="external" attribute on the xref element and repeating the Webhelp transformation in Oxygen Author 14.2
• the link to the PDF file works correctly in the Webhelp output if the scope="local" attribute is used (preferably also the format="pdf" attribute, which will help the browser to start the appropriate application for opening the linked PDF file)

If some browsers do not open the PDF file when you click on the link to the PDF file and the PDF file is there in the output directory (copied there automatically by the Webhelp transformation only if the scope="local" attribute is used) then you should check the settings in your browser application on various machines (Mac, Windows, etc) to see the application that the browser should start for viewing a linked PDF file and to check that the application really can be started without errors by the browser.


Regards,
Sorin

[MichaelDa]

Hi Sorin.

Our testing has shown that browsers and even browser sessions do not show consistent with the behavior on this issue, so I understand it may be difficult to reproduce reliably. I have created a video to demonstrate our observed behavior in Mac and Windows in Safari, IE, and Chrome. I have sent a separate email to your support group with the link to the video. You can test various link settings with our test WebHelp here.

I think it boils down to this: PDFs are not displaying consistently or reliably in the new WebHelp output in 14.2, regardless of how the xref is configured. One thing that would help fix the issue would be to set the PDFs to display in a new tab or window, so there is no conflict between whatever PDF reader software is locally installed and the WebHelp JavaScript.

When an <xref> includes scope="external" , the resulting <a href...> tag in the output includes target="_blank". In frames-based WebHelp (index_frames.html), target="_blank" causes the PDF to open in a new tab. In the new, non-frames WebHelp (index.html), PDFs do not open in a new tab, even though other web links do (see Test Case 3 above).

It seems like there needs to be some additional logic in the WebHelp wrapper to better handle PDFs. Would it be possible to add a fix for this to the product?

Alternatively, is there some other parameter or setting that we could set up to force the PDFs to open in a new tab when launched from the new WebHelp?

[sorin_ristache]

Hi Sorin.

Our testing has shown that browsers and even browser sessions do not show consistent with the behavior on this issue, so I understand it may be difficult to reproduce reliably. I have created a video to demonstrate our observed behavior in Mac and Windows in Safari, IE, and Chrome. I have sent a separate email to your support group with the link to the video. You can test various link settings with our test WebHelp here.

Thank you for the video description of the problem. I tried every link from your example page in Firefox 14.0.1, Internet Explorer 9.0 build 9.0.8112.16421, Chrome 26.0.1410.64 and every link opens a PDF document. I have set Internet Explorer to open PDF documents in the default application for PDF documents on my machine which is Adobe Acrobat Reader, so clicking on any link opens the PDF file in the PDF application. That means the link is correct and the browser is instructed correctly what file is to be opened. It seems the plugin for PDF documents configured in your browser cannot open the PDF documents, maybe that PDF plugin for the web browser was not correctly installed/configured? On Windows it happens all the time.

To conclude: unfortunately I cannot reproduce the problem by testing your example in all of the above-mentioned three browsers. Please can you try first to configure your browser to open any PDF documents in a new window, that is by starting the default PDF application on your system in a new window and passing the PDF file to that application?

When an <xref> includes scope="external" , the resulting <a href...> tag in the output includes target="_blank". In frames-based WebHelp (index_frames.html), target="_blank" causes the PDF to open in a new tab. In the new, non-frames WebHelp (index.html), PDFs do not open in a new tab, even though other web links do (see Test Case 3 above).

The attribute target="_blank" is already there on a elements that come from xref elements with the attribute scope="external", as you can see in the HTML page from your own example, and that should be enough for instructing the browser to open the PDF file. It seems the problem is the application that should handle opening the PDF file, because that is not the browser itself, but usually some browser plugin of a third party application (in my case Adobe Acrobat). This is what I suggest we clear up first: whether the PDF plugin works correctly in the browser.

It seems like there needs to be some additional logic in the WebHelp wrapper to better handle PDFs. Would it be possible to add a fix for this to the product?

First we need to reproduce the problem. Unfortunately right now we cannot reproduce it. Only after that can we talk about fixing it.

Alternatively, is there some other parameter or setting that we could set up to force the PDFs to open in a new tab when launched from the new WebHelp?

Sorry, there is no setting for configuring the links to external resources, such links should just work because they are handled by the browser as a result of the <a ... target="_blank"> element. First we need to reproduce the problem before trying to find any fix.


Regards,
Sorin

[MichaelDa]

unfortunately I cannot reproduce the problem by testing your example in all of the above-mentioned three browsers.

Do the PDFs open in a new tab by default in WebHelp generated from Oxygen Author 14.2, as they do in frames WebHelp? As I've mentioned, this is an essential part of the issue, but your comments suggest this requires some additional configuration on the part of the end user. If additional configuration is required by the end user to produce the desired result, then you are suggesting a workaround, rather than a fix.

We are looking for the same behavior in WebHelp generated from Oxygen Author 13.2 and current frames WebHelp, where file open in a new tab or window when scope="external" in the source and/or target="_blank" in the output. We are requesting a fix for this issue, rather than a workaround.

This is what I suggest we clear up first: whether the PDF plugin works correctly in the browser.

We only see this issue in WebHelp produced from Oxygen Author 14.2. PDFs from other web pages do not demonstrate this issue, suggesting that the PDF browser plugins are working as designed.

Further, we see this issue on Oxygen Author 14.2 WebHelp in at least one browser on every machine in our environment.

I have updated the example file to demonstrate that the way WebHelp in Oxygen Author 14.2 constructs URLs, it is not possible, with default settings, for any PDF or HTML file to open in a new browser window. Please review the further details on the results for this issue.

Examples in 14.2 WebHelp with Complete URL in Xref

In the Test WebHelp, links A.1. and A.2. demonstrates that when scope="external" and the href includes the complete URL, PDF and HTML files open in a new tab or window by default with the following URLs. Please look closely at the file name portion:

http://documentation.agilepoint.com/Sup ... 3_Net4.pdf[/b]

http://documentation.agilepoint.com/Sup ... ction.html[/b]


Examples in 14.2 WebHelp with File Name Only in Xref

Compare this to the URLs when clicking links B.1. and B.2. In this case, scope="external", but the href includes only the file name, rather than the complete URL. Again, please look closely at the file name portion of the URL, and notice that the actual file name is appended to index.html#:

http://documentation.agilepoint.com/Sup ... 3_Net4.pdf[/b]

http://documentation.agilepoint.com/Sup ... ction.html[/b]

Examples in Frames WebHelp with File Name Only OR Complete URL in Xref

Now, compare this to the frames version of the WebHelp. In this case, links B.1. and B.2. generate the same URLs as A.1. and A.2. Thus the links open in a new tab or window.

http://documentation.agilepoint.com/Sup ... 3_Net4.pdf[/b]

http://documentation.agilepoint.com/Sup ... ction.html[/b]


The result appears to be that because of the way the JavaScript is handling files without a complete URL -- appending the file name with a hash (#) to index.html, rather than referring directly to the file name -- the files are being "trapped" in the lower right frame of the WebHelp, and cannot "escape" to a new tab or window.

Would it be possible to provide a fix so that when scope="external", the full URL is not required for the file to open in a new tab or window? Is it possible to change your handling for URLs when scope="external" in the source and/or target="_blank" in the output?

If these links could open by default in a new tab or window in the browser, it would mitigate the need for the end users to do any special configuration to their PDF browser plug-ins for the sake of viewing documentation from WebHelp generated from Oxygen Author 14.2. Our users would prefer this to work as expected, rather than having to do any special configuration to make it work.

I'm sure you will understand also why we would prefer not to have to hard code the full URLs to our PDFs in our source, as the URLs may change from time to time, or when reference from output from different ditamaps.

Can Oxygen please provide a fix to provide the same functionality level in frames WebHelp in the WebHelp generated from Oxygen Author 14.2?

[MichaelDa]

And to follow up from my previous post regarding URLs, it was also noticed that similar behavior happens with external files that are not meant to display in the Help, such as downloadable Zip files. This is a common scenario in our documentation.

Test Scenario for Download Files:

1. Open the sample WebHelp.

2. Click link B.3.

Expected Result: The file is downloaded, but the lower right topic frame does not change. This is the behavior in the frames version.

Observed Result:
a) The file is downloaded.
b) The URL is http://documentation.agilepoint.com/Sup ... adTest.zip[/b]
c) The lower right content frame shows a blank page.

In this case, there are no mitigating plugins, such as the PDF viewer, but the results are similar to what we are seeing with PDFs, and with similar URL structure (see my previous post for details.)

Surely it would not ever be the desired behavior to show a blank page to the user after clicking a link?

[sorin_ristache]

Hello,

We are looking for the same behavior in WebHelp generated from Oxygen Author 13.2 and current frames WebHelp, where file open in a new tab or window when scope="external" in the source and/or target="_blank" in the output. We are requesting a fix for this issue, rather than a workaround.

Oxygen 14.2 creates the same Webhelp output as Oxygen 13.2 (the index_frames.html file) which uses a XHTML frameset plus a new version of Webhelp output (the index.html file) which uses XHTML internal frames. I understand you want the same behavior on links as in the Webhelp created in Oxygen 13.2. In this case please use the index_frames.html file, which is created by Oxygen 14.2 in the same transformation that creates the index.html file (which is opened by default in the web browser at the end of the transformation). The internal frames version of the Webhelp output (the index.html file) will never work exactly in the same way as in the frameset version (the index_frames.html file) and this is due to the different behavior of the two types of XHTML frames, not due to a difference in the form of links that are created by the Oxygen Webhelp transformation.

Please use the index_frames.html file if you want the same behavior as in the Oxygen 13.2 Webhelp.

We only see this issue in WebHelp produced from Oxygen Author 14.2. PDFs from other web pages do not demonstrate this issue, suggesting that the PDF browser plugins are working as designed.

Further, we see this issue on Oxygen Author 14.2 WebHelp in at least one browser on every machine in our environment.

...

Can Oxygen please provide a fix to provide the same functionality level in frames WebHelp in the WebHelp generated from Oxygen Author 14.2?

Please use the index_frames.html output file which works the same as the Oxygen 13.2 Webhelp.


Regards,
Sorin

[sorin_ristache]

Hello,

And to follow up from my previous post regarding URLs, it was also noticed that similar behavior happens with external files that are not meant to display in the Help, such as downloadable Zip files. This is a common scenario in our documentation.

...

Surely it would not ever be the desired behavior to show a blank page to the user after clicking a link?

We fixed the problem and we will include the fix in the next maintenance build of Oxygen 14.2.


Regards,
Sorin

[MichaelDa]

Thanks for the fix, Sorin. We appreciate it.