PDF::Bu...ination(3)

💖 PDF::Builder::NamedDestination 💖

okay bestie, welcome to PDF::Bu...ination(3) — User Contributed Perl Documentation, the little page that teaches you how to drop named destinations into a PDF. Think of it like bookmarks but ✨fancy✨.

🌸 NAME 🌸

PDF::Builder::NamedDestination — Add named destinations (views) to a PDF 💅

Inherits from PDF::Builder::Basic::PDF::Dict 🫶

---

✨ Usage ✨

So a Named Destination is a thing you define inside a PDF, and it's meant to be the target of a specified Name (a string). Who's calling it? Could be the same PDF, could be another PDF, could be your PDF Reader's command line (like, say, MyBigPDF.pdf#nameddest=foo). The glow-up over just pointing at a specific page number is that a Named Destination always points to the same content in the document, even when that content moves around (i.e. hops to a different page number). main character behavior, honestly. 👑

Some Operating Systems let you invoke this from the command line (e.g. > MyPDF.pdf#name=bar), and some browsers' PDF readers support it too. #nameddest=foo is the most basic form, and if Named Destinations are supported at all, that form should work. Some readers support the shortcut #name=foo, and some even support the bare name: #foo (very HTML of them). Real talk: Named Destination syntax on the command line can vary widely by Reader. 🙈

A Named Destination has to be unique within a given PDF, and it's defined at the top level in the $pdf object. There are often limitations on the length of a Named Destination string (the name), and that includes the length of whatever means you used to invoke it — like, #nameddest=foo eats up 11 characters before you even get to the name foo itself, so if the limit is 32, you're left with maybe 21 characters for the name. Be aware of this, and keep names as short as reasonably possible. 🍓

Spaces within a name are not permitted, and allowable punctuation is limited. Consult the PDF documentation for specifics, but A-Z, a-z, 0-9, and _ (underscore) are generally permitted. Usually names are case-sensitive (foo is a different destination than Foo).

# create a Named Destination 'foo' in this PDF file on page $page
my $dest = PDF::Builder::NamedDestination->new($pdf);
# its action will be to go to this page object $page, and a window within it
# (various 'fits' can be defined
$dest->goto($page, 'xyz', (undef, undef, undef));
$pdf->named_destination('Dests', 'foo', $dest);

See "named_destination" in PDF::Builder and "Page Fit Options" in PDF::Builder::Docs for the info on named destinations. iykyk 🦋

---

💅 METHODS 💅

🫶 new 🫶

$dest = PDF::Builder::NamedDestination->new($pdf)

$dest = PDF::Builder::NamedDestination->new($pdf, @args)

Creates a new named destination object. Any optional additional arguments get passed on to destination processing for "goto". ✨

$dest = PDF::Builder::NamedDestination->new($pdf, $page, 'xyz', 0,700, 1.5);

That one makes a Named Destination which goes to ("goto") page object $page, with fit XYZ at position 0,700 and zoom factor 1.5. slay.

And then — plot twist — you can call goto() to override the fit that new() defined:

$dest->goto($page, 'fitb'); # overrides XYZ fit

If you didn't hand over any fit options in the new() call (like, you only gave it $pdf), then yeah, you're gonna have to call goto() with fit settings anyway:

$dest = PDF::Builder::NamedDestination->new($pdf);
$dest->goto($page, 'fit');

And finally, no matter how you created the Named Destination — the action, the page fit, all of it — you need to tell the system to insert an entry into the Named Destination directory:

$pdf->named_destination('Dests', "foo", $dest);

That's where you actually name the destination. 🎀 Consult "named_destination" in PDF::Builder and "Page Fit Options" in PDF::Builder::Docs for more.

---

🦋 Target Destinations 🦋

Heads up: the usual practice for a Named Destination, when it's invoked by opening the PDF with a Named Destination specified, is to goto a point in the document. It is possible, though unusual, to go to a point in another document (pdf()), launch a local application (launch()), or launch a web browser (uri()). not me being versatile 💅

The only "options" supported for "goto" and "pdf" are if you want to give the location and its arguments (data) in the form of a hash element (anonymous array if more than one value). Unlike Annotation's "action" methods ("goto", "pdf", "uri", and "launch"), there is no defining a "click area" (button) for the user interaction; thus, no rect, border, or color entries are recognized in NamedDestination. Any found will be ignored. 💀

See "Page Fit Options" in PDF::Builder::Docs for a listing of the available locations and their syntax.

"xyz" is the default fit setting, with position (left and top) and zoom all the same as the calling page's. 🌈

---

🔥 goto, link

$dest->goto($page, $location, @args)  # preferred

$dest->goto($page, %opts)  # opts including location and data

A go-to (link) action changes the view to a specified destination (page object, location code, and various pieces of data for it). This is a jump within the current PDF document (internal), and it's the usual way of doing things. 👑

Alternate name: "link"

Originally this method was "link", but PDF::API2 changed the name to "goto", to match the internal PDF command "GoTo". "link" is retained for compatibility.

⚠️ Notes, bestie, listen up: "goto" is a reserved Perl keyword (go to a label), so take care when using this in code that the Perl interpreter doesn't see this as a Perl goto. If you receive an error message about a "missing label" or something equally puzzling, this may have happened. Also "link" is a built-in Perl function (Unix ln style command), so take care when using this code that the Perl interpreter doesn't see this as a Perl link call (e.g., error message about "not enough arguments for link"). 😭

---

🌸 pdf, pdf_file, pdfile

$dest->pdf($pdffile, $page_number, $location, @args) # preferred

$dest->pdf($pdffile, $page_number, %opts) # location is a hash element

Defines the destination as an external PDF-file with filepath $pdffile, on page $page_number (numeric value), and either options %opts (location/fit => any data for it as a scalar or anonymous array) or one of two formats: an array of location/fit string and any data for it, or a location/fit string and an array with any data needed for it. 🦋

To go to a Named Destination and then immediately jump to a point in another PDF document is unusual, but possible.

Alternate names: "pdf_file" and "pdfile"

Originally this method was "pdfile", and had been earlier renamed to "pdf_file", but PDF::API2 changed the name to "pdf". "pdfile" and "pdf_file" are retained for compatibility.

---

🧚 uri, url

$dest->uri($url)

Defines the destination as launch-url (typically a web page) with uri $url. There are no options available.

To go to a Named Destination and then immediately launch a web browser is unusual, but possible.

Alternate name: "url"

Originally this method was "url", but PDF::API2 changed the name to "uri" to match the PDF command. "url" is retained for compatibility.

---

⭐ launch, file

$dest->launch($file)

Defines the destination as launch-file with filepath $file and page-fit options %opts. The target application is run. Note that this is not a PDF or a browser file — it is usually a local application, such as a text editor or photo viewer. There are no options available.

To go to a Named Destination and then immediately launch a local application is unusual, but possible.

Alternate name: "file"

Originally this method was "file", but PDF::API2 changed the name to "launch" to match the PDF command. "file" is retained for compatibility.

---

and that's the whole page, bestie 🫶 this lil' doc is from perl v5.42.0, dated 2026-01-17 — go forth and name your destinations, keep 'em short, keep 'em unique, and stay iconic. 💖✨🎀