Customized Links In PDFs - Tizra/Tizra-Customer-Tracker GitHub Wiki

Tizra linking support now includes a number of additional capabilities that can be used to control presentation in the browser. There are also a few "placeholder" features in place that will be of use in future revisions of the reader.

PDF does not supply a lot of controls for customizing links, and most of the ones that it does supply are a bit old-fashioned (in Acrobat) and poor fit for the web and other common reading technologies today. Scrolling and zooming into a portion of a Page really doesn't fit the modern model, and features like whether to open a new browser window are not allowed for.

Tizra's new linking features can be controlled from a PDF file, and we expect that other formats, as we support them, will make them even easier to use.

Links in the Tizra system are now divided into several types, depending on what they do and what kind of targets they address. This system is in place for links published after the system update on 12/21/12. The system may be able to guess the type of some earlier links, but the only way to ensure that the distinctions are in place is to republish older documents.

Tizra supports the following kinds of links:

• Page references are any internal links in a PDF, and they are treated as they always were: they navigate within the reader. Until the link upgrade, they were treated as URL links to the URL for the page. Now they may have potentially different behavior.
• Logical page links These link to a page based on its "Logical page number", e.g. roman numbered pages at the beginning of a book.
• Attachment references are links that target a Tizra attachment. They are created by Acrobat links that specify a file to open. In the conversion from a PDF file link to an attachment link, the filename found in the PDF is used as the name of the attachment -- minus any leading path components. Path information is eliminated as most applications use absolute file paths encumbered with extra levels of directory information. In particular, Acrobat does not even allow the user to manually edit the path. It is the publisher's job to make sure that any needed attachments are uploaded to the publication, or the resulting reader links will return page not found.
• URL references are links that specify a URL as the destination. In Acrobat they are opened by an external web browser. In Tizra, they are normally rendered as inline links within the reader window. Previous to the link upgrade, all relative URLs were treated as filenames (and turned into attachment links), because Microsoft word treats file links as URL links. Absolute URLs have always been preserved as-is, navigating to their destinations in the reader's browser window.
• Anchors are rectangular areas of a page with names. They can be targeted by other links, and highlight on arrival. In HTML or XML documents, these are HTML anchor elements.
• Anchor links are links to anchor elements with the document specified by the base URL. The links will automatically redirect to the page containing the anchor. Default browser behavior will scroll the anchor into view, and CSS styles may be used to ensure that the anchor is highlighted in the document.
• Script links (experimental) are links that specify a javascript to be executed in the browser. They are drawn from the Acrobat script links that execute Adobe's dialect of Javascript within Acrobat. Because Acrobat scripts won't work in a browser, these links have traditionally been ignored. Now these links will be preserved and run in the reader as onclick handlers for the link.

a typical Tizra link in the reader looks like this:

<a style="{Fixed style to position link in browser}"
 class="t-on-page-link {custom classes}" href="{destination}"
target="{target window}"> </a>

The style attribute is fixed, generated by the system, and should not be altered. It handles the proper positioning of the link on the graphical page.

The destination value is generated by the system depending on the type of link.

All Tizra links include the HTML class t-on-page-link. You can customize the color, border, and highlighting behavior of this class if you wish, but should not attempt to change its layout behavior, as we cannot guarantee that future reader markup will not break such customizations. The one exception to that rule would be the use of display:none;, if you wish to ensure that no links will be enabled for users. You can specify a string containing additional classes for links, on a link by link basis, if you have more than one kind of link that needs to be visually differentiated.

The target attribute is used to determine browser window behavior on fetching the target of a link. The default value for a URL or attachment link is _self which causes the new page to display in the same window (replacing the reader). The HTML standard defines the details, but useful values include _blank which forces the creation of a new blank window or tab. Other values can be used to target a named window or frame, and will create and name one if it does not already exist.

You can change the default value for the link target by adjusting the defaultLinkTarget design property.

Page links do not have a target attribute, because it suppresses the jQuery Ajax navigation that the reader depends on.

A Tizra Anchor looks like this:

<div style="{Fixed style to position link in browser}"
	class="t-anchor {custom classes}" id="{Anchor name}"> </div>

Again, your CSS can customize the visual style of the region in question, but should not make any changes to layout properties of these elements.

To customize a link in a PDF file, you must make it a URL-based link. The Tizra publishing system uses fragment identifiers (the part of a URL after a #) to customize links, and to specify that a URL link should create a link of one of the other types. This lets us add new functions while following the URL standard, and without introducing compatibility problems with the rest of the web.

A Tizra fragment identifier can have one or more customizations specified within it. Each customization contains a colon (:) and is divided into a command and a value, so: command:value. If there is more than one customization needed, they can be separated by commas (,). Customizations are removed from the fragment identifier before the final URL is stored. After splitting the fragment identifier at the commas, any portions of the fragment identifier that do not match a Tizra customization are restored, so a fragmentID like "#foo,bar" would be preserved into the browser as #foo,bar (as neither component contains a :).

The following customizations are defined at this time:

• tizra-target: sets target attribute of the link element (a tag).
• tizra-class: adds an HTML class or classes to the link element.
• tizra-define-anchor: defines a new link destination on the page to be highlighted on arrival when the browser URL contains a matching fragmentID.
• tizra-page: sets the type of this link to a page link, and specifies the page number within the current PDF.
• tizra-logical-page: sets the type of this link to a page link, and specifies the logical page number within the target.
• tizra-anchor-link: creates a link to a document page based on the name of an anchor within that document. The anchor will be looked up, and the correct page will be visited. The Fragment ID of link dekuvered to the user will contain the anchor id already, to signal that the anchor should be highlighted, if the stylesheet so specifies.
• link-rel: configures the html rel attribute for this link to a particular value. The value lightbox, for instance, will configure an image to appear in a popup lightbox window.
• link-title: configures the html title attribute for this link to a particular value. This is used for accessibility access, and browser popup prompts when a link is rolled over. For lightbox links, the title is used to configure the caption for the popup window. As an attribute, titles are limited in length.

Any remaining URL components are preserved intact (after the Tizra pieces are removed). So, for instance, a link to page 3, anchor "foo" could be made like this (in the pdf):

#tizra-page:3,foo

The resulting URL in the link sent to the browser would be /documentpath/3#foo.

That would be able to highlight the target foo on page 3, which could have been created by a URL link on page 3 of the PDF, like this: tizra-define-anchor:foo

A URL like this:

http://some.site.com/#tizra-target:_blank,tizra-class:myclass,normal

Would link to the URL:

http://some.site.com/#normal

The URL above would cause the link to open in a new window (because of the target attribute on the link), and would add the class myclass to the HTML markup for the link.