Links and bookmarks offer an alternative and faster way to navigate through the contents of a document or to access information not contained within it.
Docxpresso creates automatically a series of internal bookmarks for cross-referencing so it is possible to generate automatic Tables of Contents (headings are bookmarked for that purpose) or respect anchor linking coming from HTML5 code (elements with a non-empty id are automatically bookmarked with it) but, of course, what bring us here is the possibility to “manually” generate bookmarks and links in our documents.
Links
With the help of Docxpresso you can insert hyperlinks in your document that will allow the final user to access remote content, like a web page or an external document, or go directly to a previously bookmarked element within the same document.
Its public API is given by:
Signature
public link ([$options])
Parameters
- $options (type: array). This array has the following available keys and values:
- text (type: string). The linked text. Notice that it can be empty because the link text may be later introduced via the text method.
- target (type: string, default: _blank). The target frame that can be: _blank, _parent, _self or _top.
- title (type: string). An optional link title useful for accesibility purposes.
- url (type: string). The link href attribute. It can be a http path or an anchor to a previously defined bookmark (#name).
- style (type: string). A string of styles in CSS format.
The relevant CSS style type styles that one may apply concide with the ones of the text method and we refer to them for further details (see Text)
Let us work a simple example with an external link and postpone the internal linking to the following Bookmark chapter.
<?php
/**
* This sample script inserts a simple paragraph with a link
*/
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph with a link
$linkData = array(
'url' => 'http://www.google.com',
'text' => 'Google',
'title' => 'Google search Engine',
);
$doc->paragraph(array('text' => 'This is a very simple paragraph with a link to '))
->link($linkData)->end('link')
->text(array('text' => '.'));
//include in the render method the path where you want your document to be saved
$doc->render('simple_link' . $format);
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'simple_link' . $format . '">Download document</a>';
DOWNLOAD:
Like the link method accepts content by chaining we have judiciously used the end method to avoid unwanted nesting of content (the final dot should not be included in the linked text). Of course, the chaining is optional and we could have perfectly done otherwise, i.e. capturing the paragraph object in a variable and inserting the content once at a time.
Bookmarks
All we need to generate a bookmark in Docxpresso is:
- A unique name.
- An optional text.
The name is needed for later referral and the text is optional because the bookmark may point to any containing element in the document and it is not necessary to associate a particular text to it.
Its public API is given by:
Signature
public bookmark ($options)
Parameters
- $options (type: array). This array has the following available keys and values:
- name (type: string). An unique name. This parameter is mandatory.
- text (type: string). An optional text.
- style (type: string). A string of styles in CSS format.
The relevant CSS style type styles that one may apply concide with the ones of the text method and we refer to them for further details (see Text)
The following code illustrates the bookmark method functionality:
<?php
/**
* This sample script inserts a link in the first page that points to a
* bookmark in the second page
*/
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph with a link to the bookmarked paragraph
$linkData = array(
'url' => '#myBookmark',
'text' => 'the bookmarked paragraph in the second page',
'title' => 'An internal cross-reference',
);
$doc->paragraph(array('text' => 'This is a very simple paragraph with a link to '))
->link($linkData)->end('link')
->text(array('text' => '.'));
//insert a paragraph with a bookmark in a new page
$doc->paragraph(array('style' => 'page-break-before: always'))
->bookmark(array('name' => 'myBookmark'))
->text(array('text' => 'This is the bookmarked paragraph.'));
//include in the render method the path where you want your document to be saved
$doc->render('bookmark' . $format);
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'bookmark' . $format . '">Download document</a>';
DOWNLOAD:
