Working with Links and References

Working with Links and References

Word’s link and cross-reference field codes – HYPERLINK, REF, PAGEREF, NOTEREF, STYLEREF, SET, ASK, FILLIN, CITATION, BIBLIOGRAPHY, and more – are each implemented as a dedicated Field subclass in Aspose.Words FOSS for .NET. All of these classes live in the Aspose.Words.Fields namespace alongside every other field type; this page groups the ones specifically concerned with links, cross-references, prompted values, and citations, and covers what each one exposes.

Hyperlinks

FieldHyperlink represents the HYPERLINK field: Address and SubAddress hold the target URL or in-document location, ScreenTip sets the hover tooltip, OpenInNewWindow and IsImageMap are display flags, and Target names a browser frame. For simple cases, DocumentBuilder.InsertHyperlink() inserts a hyperlink field directly without constructing the Field object by hand.

Cross-References to Bookmarks

FieldRef (the REF field), FieldPageRef (PAGEREF), and FieldNoteRef (NOTEREF) each resolve to content at a named bookmark via their BookmarkName property, with InsertHyperlink and InsertRelativePosition controlling whether the reference is clickable and whether it reports a relative position (“above” / “below”). FieldRef adds paragraph numbering options (InsertParagraphNumber, InsertParagraphNumberInFullContext, InsertParagraphNumberInRelativeContext, NumberSeparator) and IncludeNoteOrComment. FieldStyleRef (STYLEREF) instead resolves to the nearest paragraph formatted with a given StyleName, with SearchFromBottom to search backward from the field’s position. The bookmarks these fields target are created with DocumentBuilder.StartBookmark() and EndBookmark(), and can be navigated to with MoveToBookmark(). FieldSet (SET) defines a bookmarked text value – BookmarkName and BookmarkText – that a REF field elsewhere can resolve.

Prompted-Value Fields

FieldAsk (ASK) and FieldFillIn (FILLIN) request a value from whoever updates the field: PromptText is shown to the user, DefaultResponse supplies a fallback, and PromptOnceOnMailMerge limits repeated prompting during a mail merge. FieldAsk additionally stores its answer at BookmarkName for other fields to reference. See the fields guide for IFieldUserPromptRespondent, the callback that supplies answers to these fields programmatically instead of prompting interactively.

External and Linked Content

FieldDde (DDE) and FieldDdeAuto (DDEAUTO) link to content in another application via ProgId, SourceFullName, and SourceItem, with InsertAsText, InsertAsHtml, InsertAsPicture, InsertAsRtf, InsertAsUnicode, and InsertAsBitmap selecting the inserted representation, and AutoUpdate / IsLinked controlling refresh behavior. FieldLink (LINK) is the OLE-link equivalent, adding FormatUpdateType. FieldImport (IMPORT) and FieldIncludePicture (INCLUDEPICTURE) pull in an external graphic via SourceFullName and GraphicFilter. FieldInclude (INCLUDE) and FieldIncludeText (INCLUDETEXT) pull in external document content, with BookmarkName to scope the included range and LockFields to prevent it from being refreshed; FieldIncludeText additionally supports XML sources through Encoding, MimeType, NamespaceMappings, XPath, and XslTransformation.

AutoText and Glossary References

FieldAutoText (AUTOTEXT), FieldAutoTextList (AUTOTEXTLIST), and FieldGlossary (GLOSSARY) all reference a named building-block entry through EntryName; FieldAutoTextList adds ListStyle and ScreenTip for its list-style presentation.

Citation and Bibliography Fields

FieldCitation (CITATION) and FieldBibliography (BIBLIOGRAPHY) render content sourced from the document’s bibliography data. FieldCitation.SourceTag (and the alternate AnotherSourceTag) identifies which source it cites, with Prefix, Suffix, PageNumber, VolumeNumber, and the Suppress* flags (SuppressAuthor, SuppressTitle, SuppressYear) controlling how the citation is formatted. FieldBibliography.SourceTag, FilterLanguageId, and FormatLanguageId control which sources appear in the rendered bibliography and in what language. The underlying source records these fields render – Source, Contributor, Person – are covered in the bibliography guide.

Quote and Shape Text Fields

FieldQuote (QUOTE) and FieldShape (SHAPE) both expose a Text property holding literal field text – FieldQuote inserts it directly at the field’s position, while FieldShape associates it with a drawing shape’s text-carrying field code.

Tips and Best Practices

• Prefer DocumentBuilder.InsertHyperlink() for straightforward hyperlink insertion; drop down to constructing a FieldHyperlink directly only when you need properties such as ScreenTip or IsImageMap that the builder shortcut doesn’t expose.
• FieldRef, FieldPageRef, FieldNoteRef, and FieldSet all coordinate through BookmarkName – make sure the target bookmark exists (via DocumentBuilder.StartBookmark() / EndBookmark()) before the field that references it is updated.
• Set FieldOptions.UserPromptRespondent (see the fields guide) before updating a document containing FieldAsk or FieldFillIn fields in an unattended pipeline.
• FieldDde and FieldDdeAuto model a legacy Windows OLE linking mechanism – treat AutoUpdate and IsLinked as informational when processing documents outside of Windows, since the external application they’d normally refresh from is not available.
• Citation and bibliography fields only render correctly once the document’s underlying Source records exist – see the bibliography guide for building those.

Common Issues

FAQ

What’s the difference between FieldRef and FieldStyleRef?

FieldRef resolves to content at a named bookmark (BookmarkName); FieldStyleRef instead resolves to the nearest paragraph formatted with a given StyleName, independent of bookmarks.

How do I insert a simple hyperlink without building a Field by hand?

Call DocumentBuilder.InsertHyperlink().

Are these link and reference field classes in a separate namespace from other fields?

No – FieldHyperlink, FieldRef, FieldCitation, and the rest of the classes on this page are ordinary Field subclasses in the Aspose.Words.Fields namespace, the same namespace covered in the fields guide.

How do citation fields relate to the bibliography data model?

FieldCitation and FieldBibliography render content by looking up SourceTag against the Source records described on the bibliography guide – the field classes handle rendering, and the Source / Contributor classes hold the underlying data.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation