# Tutorial: iText by Example

## Anchors, Actions and Annotations

Local Goto and Local Destination:
Sometimes you need a link to allow the reader of your document to jump from one position (LocalGoto) in the text to another (LocalDestination). You can achieve this with two methods of class Chunk: setLocalGoto and setLocalDestination. Both methods take 1 parameter: this is the unique name you want to give to the destination.

    new Chunk("localgoto").setLocalGoto("test");
    new Chunk("localdestination").setLocalDestination("test");

The HTML equivalent of the first line is <A HREF="#test">localgoto<A>; The equivalent of the second is <A NAME="test">localdestination<A>. However if we want to produce HTML (with HtmlWriter), we will use the Anchor object.
Example: java com.lowagie.examples.objects.anchors.LocalGoto
Creates a document with a local goto and a local destination: see LocalGoto.pdf
A LocalGoto-chunk isn't the only way to reach a LocalDestination. As you will see later on in this chapter and in the chapter on bookmarks, local destinations can be used in actions too.
Example: java com.lowagie.examples.objects.anchors.LocalDestination
Creates a document that jumps to a local destination upon opening: see LocalDestination.pdf
Go to top of the page
Remote Goto:
If you have defined a local destination in a certain document (see above), you can jump to this destination from another document. This is done with the method setRemoteGoto(String filename, String name). You don't necessarily need a local destination in the other document. You can also jump to a certain page withsetRemoteGoto(String filename, int page).

    new Chunk("go to a destination in document B")
    	.setRemoteGoto("DocumentB.pdf", "test");
    new Chunk("go to page 3 in document B")
    	.setRemoteGoto("DocumentB.pdf", 3);

Example: java com.lowagie.examples.objects.anchors.RemoteGoto
Creates two documents with links to eachother and to an external URL: see DocumentA.pdf DocumentB.pdf
Go to top of the page
the Anchor object:
There as some alternative ways to add external links such as <A HREF="http://www.lowagie.com/iText/">Bruno's site<A> or internal links such as <A NAME="top">top of the page<A> and <A HREF="#top">goto top<A>. One of them is using the Anchor object. This is a very simple class and the beauty of it is that it works, not only in PDF, but also in HTML and RTF.
This is the code to create an external link:

    Anchor anchor = new Anchor("website");
    anchor.setReference("http://www.lowagie.com/iText/");
    anchor.setName("website");

This is the code for an internal link:

    Anchor anchor1 = new Anchor("This is an internal link");
    anchor1.setName("link1");
    Anchor anchor2 = new Anchor("Go to the internal link");
    anchor.setReference("#link1");

Example: java com.lowagie.examples.objects.anchors.AHref
Using the Anchor object: see AHref.pdf AHref.html
Go to top of the page
Actions:
A PDF document can have a certain interactivity: you can create several 'actions', for instance to jump to another page or location, to start an other application, to invoke a JavaScript function,... In the next subsections, some actions that are supported in iText will be explained; see the javadocs (class PdfAction) for more types of actions. Remark that many of the action can be constructed in two alternative ways: with the constructor or with a static method that calls the constructor.
Named Actions
There are 5 predefined named actions in iText:

- PdfAction.FIRSTPAGE: jumps to the first page
- PdfAction.PREVPAGE: jumps to the previous page
- PdfAction.NEXTPAGE: jumps to the next page
- PdfAction.LASTPAGE: jumps to the last page
- PdfAction.PRINTDIALOG: opens a PrintDialog

It is very easy to use one of these named destinations:

    new Chunk("First Page")
    	.setAction(new PdfAction(PdfAction.FIRSTPAGE));

Example: java com.lowagie.examples.objects.anchors.NamedActions
Creates a document with named actions.: see NamedActions.pdf
JavaScript
Acrobat JavaScript is a programming language based on the JavaScript, aka ECMAScript, originally developed by Netscape Communications. Acrobat JavaScript adds new objects, methods and properties to the JavaScript language. These Acrobat-specific objects can allow you to handle file attachments, manage document security, perform form manipulations, etc, etc...
Acrobat JavaScript does not have access to objects within an HTML page and HTML JavaScript cannot access objects within a PDF file. For instance: Acrobat JavaScript cannot access the Window object (e.g. the browser window in which the Acrobat plugin is embedded).
You will have to read the Acrobat JavaScript Scripting Reference (Adobe Inc.) and the Client-Side JavaScript Reference (Netscape Communications Corporation); these documents and other JavaScript guides and references are available through the Adobe Web pages http://partners.adobe.com/NSjscript/ and http://partners.adobe.com/public/developer/acrobat/sdk/index_doc.html.

    new Chunk("Click to say Hello")
    	.setAction(
    		PdfAction.javaScript("app.alert('Hello');\r", writer));

The code above, adds an alert action to a Chunk. If you click the text in the Chunk, an alert is triggered with the message 'Hello'.
Example: java com.lowagie.examples.objects.anchors.JavaScriptAction
Creates a document with a Javascript action.: see JavaScriptAction.pdf
Goto Actions
If you want to jump to another document or URL, as yet another alternative way to do what we did in the previous sections, you can create a PdfAction using one of the following constructors:

- PdfAction(String filename, String name)
- PdfAction(String filename, int page)
- PdfAction(URL url)
- PdfAction(String url)

PdfAction.gotoLocalPage(int page, PdfDestination dest, PdfWriter writer), PdfAction.gotoLocalPage(String dest, boolean isName) and PdfAction.gotoRemotePage(String filename, String dest, boolean isName, boolean newWindow) are the alternative static methods to construct Goto actions.
PdfAction.gotoRemotePage("remote.pdf", "test", false, true) creates an action that goes to the destination "test" in remote.pdf in a new window.
Example: java com.lowagie.examples.objects.anchors.Actions
Creates a document with some goto actions: see Actions.pdf remote.pdf
Open Actions
We've already used an 'Open Action' twice. In the previous example with the method setOpenAction(PdfAction action) and in an earlier example with the method setOpenAction(String name):
Example: java com.lowagie.examples.objects.anchors.LocalDestination
Creates a document that jumps to a local destination upon opening: see LocalDestination.pdf
Chained Actions
If you want to trigger two or more actions after eachother, you can chain them using next(PdfAction action).

    PdfAction action = PdfAction.javaScript("app.alert('Welcome');\r", writer);
    action.next(new PdfAction("http://www.lowagie.com/iText/"));

Example: java com.lowagie.examples.objects.anchors.ChainedActions
Creates a document with chained actions.: see ChainedActions.pdf
Launching an Application
You can open an application from a PDF file using a Launch Action. Be carefull: this is a very platformdependent feature and it isn't very safe to use. Read the Javadocs on method PdfAction(String application, String parameters, String operation, String defaultDir) for more information concerning the parameters. In the example below, we launch NOTEPAD (only on Windows, change the param if WINROOT does not equal C://windows/).

    new Chunk("Click to open NOTEPAD")
    	.setAction(new PdfAction("C://WINDOWS/notepad.exe", null, null, null));

The alternative static method to construct this Action is PdfAction.createLaunch(String application, String parameters, String operation, String defaultDir)
Example: java com.lowagie.examples.objects.anchors.OpenApplication C://windows/
Creates a document with a link to open an external application.: see OpenApplication.pdf
Go to top of the page
Annotations:
Yes, using Annotations is yet another alternative to jump to a specific local or remote destination. Lets take a look at some simple things you can do with the class Annotation

- Text: you can add small pieces of text to your document that are not really part of the content. Annotations have a title and some content.

      Annotation a = new Annotation(
      	"authors",
      	"Maybe it's because I wanted to be an author myself that I wrote iText.",
      	100f, 700f, 200f, 800f);

- External links: you have to specify a clickable rectangle and a String (representing the URL) or an URL-object.

      Annotation annot = new Annotation(
      	100f, 700f, 200f, 800f,
      	new URL("http://www.lowagie.com/iText/"));
      Annotation annot = new Annotation(
      	100f, 700f, 200f, 800f,
      	"http://www.lowagie.com/iText");

- External PDF file: you have to specify a clickable rectangle and a String (the filename) and a destination or pagenumber.

      Annotation annot = new Annotation(
      	100f, 700f, 200f, 800f,	"other.pdf", "mark");
      Annotation annot = new Annotation(
      	100f, 700f, 200f, 800f,	"other.pdf", 2);

- Named action: you have to specify a clickable rectangle and a named action:

      Annotation annot = new Annotation(
      	100f, 700f, 200f, 800f, PdfAction.FIRSTPAGE);

- Application: you have to specify a clickable rectangle and an application:

      Annotation annot = new Annotation(
      	300f, 700f, 400f, 800f,
      	"C://windows/notepad.exe", null, null, null);

- Media Clip: you can specify a rectangle and a movie file and its MIMETYPE. You also need to specify if the clips needs to be shown on display of the page (since PDF 1.5).

      new Annotation(200f, 700f, 300f, 800f, "cards.mpg", "video/mpeg", true);

Example: java com.lowagie.examples.objects.anchors.SimpleAnnotations
Creates two documents with different types of annotations: see SimpleAnnotations1.pdf SimpleAnnotations2.pdf
External resources for this example: cards.mpg iText.gif
As an alternative for using the Annotation constructors, you can use the constructor in class PdfAnnotation. As you can pass any action to this constructor, you have a more options than with class Annotation. PdfAnnotation also has lots of static methods that allow you to create specific annotations. In the example below some more complex features are presented using the constructor and static methods of PdfAnnotation, but keep in mind that some of these features only work since PDF version 1.5.
Example: java com.lowagie.examples.objects.anchors.Annotations
Creates a document with some PdfAnnotations: see Annotations.pdf
External resources for this example: cards.mpg
Go to top of the page
Amazon books:
amazon.co.uk-link
amazon.co.uk-link
amazon.co.uk-link