Hyperlink

Word allows hyperlinks to be placed in a document wherever paragraphs can appear.

The target (URL) of a hyperlink may be external, such as a web site, or internal, to

another location in the document.

The visible text of a hyperlink is held in one or more runs. Technically a hyperlink can

have zero runs, but this occurs only in contrived cases (otherwise there would be

nothing to click on). As usual, each run can have its own distinct text formatting

(font), so for example one word in the hyperlink can be bold, etc. By default, Word

applies the built-in `Hyperlink` character style to a newly inserted hyperlink.

Note that rendered page-breaks can occur in the middle of a hyperlink.

A |Hyperlink| is a child of |Paragraph|, a peer of |Run|.

Candidate protocol

An external hyperlink has an address and an optional anchor. An internal hyperlink has

only an anchor. An anchor is also known as a *URI fragment* and follows a hash mark

("#").

Note that the anchor and URL are stored in two distinct attributes, so you need to

concatenate `.address` and `.anchor` if you want the whole thing.

.. highlight:: python

**Access hyperlinks in a paragraph**::

**Access hyperlinks in a paragraph in document order with runs**::

**Access hyperlink address**::

**Access hyperlinks runs**::

**Determine whether a hyperlink contains a rendered page-break**::

**Access visible text of a hyperlink**::

**Add an external hyperlink**::

**Add an internal hyperlink (to a bookmark)**::

**Modify hyperlink properties**::

**Add additional runs to a hyperlink**::

**Iterate over the run-level items a paragraph contains**::

**Paragraph.text now includes text contained in a hyperlink**::

Word Behaviors

* What are the semantics of the w:history attribute on w:hyperlink? I'm

suspecting this indicates whether the link should show up blue (unvisited)

or purple (visited). I'm inclined to think we need that as a read/write

property on hyperlink. We should see what the MS API does on this count.

* We probably need to enforce some character-set restrictions on w:anchor.

Word doesn't seem to like spaces or hyphens, for example. The simple type

ST_String doesn't look like it takes care of this.

* We'll need to test URL escaping of special characters like spaces and

question marks in Hyperlink.address.

* What does Word do when loading a document containing an internal hyperlink

having an anchor value that doesn't match an existing bookmark? We'll want

to know because we're sure to get support inquiries from folks who don't

match those up and wonder why they get a repair error or whatever.

Specimen XML

.. highlight:: xml

External links

The address (URL) of an external hyperlink is stored in the document.xml.rels

file, keyed by the w:hyperlink@r:id attribute::

... mapping to relationship in document.xml.rels::

A hyperlink can contain multiple runs of text (and a whole lot of other

stuff, including nested hyperlinks, at least as far as the schema indicates)::

Internal links

An internal link provides "jump to another document location" behavior in the

Word UI. An internal link is distinguished by the absence of an r:id

attribute. In this case, the w:anchor attribute is required. The value of the

anchor attribute is the name of a bookmark in the document.

Example::

... referring to this bookmark elsewhere in the document::

Schema excerpt

.. highlight:: xml

::

hyperlink