Named Destination support in FOP 0.94

[Tai Hu <hu...@yahoo.com>]

Hi,
    I want to find a way to add a named destination into PDF file by using FOP 0.94. Then later on, I could open a pdf file by pass in #nameddest=<named destination> on URL to jump to a particular section. I checked 0.94 change history which states that Named Destination support is added for version 0.94. However, I couldn't find any document on how to use it. Could anyone show me an example of usage of this feature? Thanks!

---------------------------------------------------------------------
To unsubscribe, e-mail: fop-users-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-users-help@xmlgraphics.apache.org

Re: Named Destination support in FOP 0.94

[Paul Vinkenoog <pa...@vinkenoog.nl>]

> Now if you build flowers.fo -> flowers.fop, the named destinations will be present in the PDF.

Sorry, I meant "flowers.fo -> flowers.pdf" of course.

Paul

---------------------------------------------------------------------
To unsubscribe, e-mail: fop-users-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-users-help@xmlgraphics.apache.org

Re: Named Destination support in FOP 0.94

[Paul Vinkenoog <pa...@vinkenoog.nl>]

Hello Tai Hu,

> I want to find a way to add a named destination into PDF file by using FOP 0.94. Then later on, I could open a pdf file by pass in #nameddest=<named destination> on URL to jump to a particular section. I checked 0.94 change history which states that Named Destination support is added for version 0.94. However, I couldn't find any document on how to use it. Could anyone show me an example of usage of this feature? Thanks!

Let's say your target document is called flowers.pdf, and you want certain sections to be reachable from outside the document. To do that, first declare this namespace in flowers.fo:

  xmlns:fox="http://xmlgraphics.apache.org/fop/extensions"

And declare the destinations like this:

  <fox:destination internal-destination="intro"/>
  <fox:destination internal-destination="tulips"/>
  <fox:destination internal-destination="roses"/>
  <fox:destination internal-destination="daisies"/>

Notes:
- "intro", "tulips", "roses" and "daisies" must be existing ids in flowers.fo;
- the declaration order of the destinations is unimportant, and they don't have to be all together either. Just make sure that each <fox:destination> is the direct child of a <fo:block>. Any block will do, it doesn't have to be the block that bears the corresponding id.

Now if you build flowers.fo -> flowers.fop, the named destinations will be present in the PDF.


In the referring document, you can link to flower.pdf's named destinations in two ways:

1) URI-style (using a relative or absolute *URL*):

     <fo:basic-link external-destination="flowers.pdf#tulips">Surf to relative Tulips!</fo:basic-link>
     <fo:basic-link external-destination="http://www.nature.com/botany/flowers.pdf#tulips">Surf to absolute Tulips!</fo:basic-link>

   If you're reading flowers.pdf with e.g. Acrobat Reader on your local computer and it encounters this type of link, it will launch a web browser and pass it the URL. The target file will be opened in the browser.

2) GoToR-style (using a relative or absolute *file path*):

     <fo:basic-link external-destination="flowers.pdf#dest=tulips">GoToR to relative Tulips!</fo:basic-link>
     <fo:basic-link external-destination="/home/sharon/flowers.pdf#dest=tulips">GoToR to relative Tulips!</fo:basic-link>

   GoToRs work via the local filesystem. Acrobat Reader will open the target document itself if the link is a GoToR.
   GotToRs "should not" work across the Web, but in practice FOP-built relative GoToRs often did, because of a bug in the source code which generated a URL link instead of a GoToR. That bug has been fixed, so I suppose this "feature" stopped working in 0.94 (if it didn't, don't count on it to keep working forever).


You should also know that web browsers sometimes (Firefox) or often (MSIE) screw up if you add a named destination to a URL. They always open the target document, but they don't always jump to the targeted named destination (however, even if they don't, they do show the named dest in the address bar). A lot of investigation and testing has been done in April/May and the PDF objects generated by the FOP named destination code are absolutely, one-hundred-percentedly compliant with the formal PDF specification. Still these errors occur, but they are very erratic: clicking on the same destination ten times may get you to the right spot eight times and to top-of-document two times. Or the other way round, depending on the browser.


Hope this helps!
Paul Vinkenoog

---------------------------------------------------------------------
To unsubscribe, e-mail: fop-users-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-users-help@xmlgraphics.apache.org