A Link object represents a single hyperlink applied to some text in the document.
Existing Link objects can be obtained through the commands:
Text.linkAtIndex
Attributes.linkObject
Link Type Commands
Link.selectedLink v3.0.2
Returns the first Link object applied to text selected in the active document. If the selection is zero length (ie: an insertion point) this returns the link associated with the typing attributes. If there’s no active document or selection, this returns the undefined value.
Link.newWithBookmarkName bookmarkName v2.0.5
Returns a new link that targets a bookmark of the given name. The bookmark need not exist.
Link.newWithFilePath filePath v2.0.5
Returns a new link that targets a file on disk. The target file must exist at the time the link is created and Nisus Writer must have proper access, otherwise this command will return the @undefined value.
NOTE: prior to v2.1 the target file did not need to exist. However, now that Nisus Writer is sandboxed, this captures a security-scoped alias to the target file, which must exist.
Link.newWithAliasToFileAtPath filePath v2.0.5
Returns a new link that targets a file on disk by capturing alias data for that file (ie: the link will still resolve even if the file is moved or renamed). The target file must exist at the time the link is created and Nisus Writer must have proper access, otherwise this command will return the @undefined value.
Link.newWithURL urlString, [isPercentEncoded] v2.0.5
Returns a new link that targets the given URL, which can be any kind of URL, eg:
http://nisus.com
ftp://myhost.com
mailto:whatever@example.com
The optional argument isPercentEncoded says whether or not the given string already has percent encodings for special characters. The default is false, where percent encoding will be added as necessary.
Link.newRunMacroWithMenuPath menuPath, [arguments] v2.0.5
Returns a new link that when clicked/activated would run the macro with the given menu path. The path can be a full menu path, a path fragment, or just the name of the macro. The menu does not have to exist yet, as the path is only used when the link is activated to run the macro.
Optionally, a Hash object can be provided, which will be passed to the target macro when it is run via the link. These arguments are made available via Macro.arguments. Note: all the argument keys and values will be converted to strings when they are captured by the link, so more complex values may not survive the conversion.
A macro that is run in response to an activated link will be able to access the document that contains the link via the command Document.macroCaller.
Link.newRunMacroWithFilePath filePath, [arguments] v2.0.5
Works just like newRunMacroWithMenuPath, but instead of taking a menu path, should be given a path to a file on disk. The file does not have to exist yet, as the path is only used when the link is activated to run the macro.
Link.newRunThisMacro [arguments] v2.0.5
Returns a new link that when clicked would rerun the macro currently being run (ie: the link reruns the macro which contains the newRunThisMacro command).
The way the new link references the macro is either by menu path or file path, thus the macro must already be loaded into the menus or saved on disk, otherwise this command returns the @undefined value.
This can be used to embed links in documents which can run macros as the user interacts with the document. See the Link Object Examples section for such a macro.
Link Object Properties
.targetType v2.0.5
Returns a string describing what the link targets. The value is either "bookmark", "file", or "url". Read-only.
.urlScheme v2.0.5
If the link targets a URL, returns the scheme of that URL, eg: "http", "ftp", etc. If the link is not a URL, returns the @undefined value. Read-only.
.linkString v2.0.5
Returns a string that represents the link, eg: "http://nisus.com" or "/path/to/file". Read-only.
.targetBookmarkName v2.0.5
If the link targets a bookmark, returns the name of that bookmark. If the link does not target a bookmark, returns the @undefined value. Read-only.
.targetFilePathFragment v2.0.5
If the link targets a file, this returns the path fragment used to identify that file. This fragment could be a full path or a relative path like "images/blerg.png". If the link is an alias, the path may be stale. Read-only.
Warning: in most cases you will want to use the command resolvedFilePath instead, which always returns a full path, and resolves aliases to ensure the target exists.
If the link does not target a file, this returns the @undefined value.
.targetAliasData v2.0.5
If the link is an alias, returns the data that was captured for the original target file. If the link is not an alias, returns the @undefined value. Read-only.
.runMacroPath v2.0.5
If the link would run a macro, returns the menu path (or file path) to that macro. That path is not necessarily valid. If the link does not run a macro, returns the @undefined value. Read-only.
.runMacroDisplayName v2.0.5
If the link would run a macro, returns the display name of that macro. If the link does not run a macro, returns the @undefined value. Read-only.
.runMacroArguments v2.0.5
If the link would run a macro, returns a Hash object holding all the arguments that would be passed to the macro when the link is clicked/activated. If the link does not run a macro, returns the @undefined value. Read-only.
Link Object Commands
.apply v2.0.5
Applies the link to the currently selected text in the active document.
.activate sourceDocument v2.0.5
Activates the link exactly as if the user had clicked on the hyperlink, eg: shows the target file, opens a web browser, runs a macro, etc.
In order to resolve links properly, you must pass the document this link is contained within. If the link is not applied in a document, you may pass the @undefined value instead, but this is not recommended because it may fail (consider a relative link like "images/blerg.png").
.resolvedFilePath sourceDocument, [allowUserInteraction] v2.0.5
If the link targets a file, this returns the full path to that file. This path does not necessarily refer to a file that actually exists, unless the link is an alias; an alias that fails to resolve may return the @undefined value instead of an invalid file path.
In order to resolve links properly, you must pass the document this link is contained within. If the link is not applied in a document, you may pass the @undefined value instead, but this is not recommended because it may fail (consider a relative link like "images/blerg.png").
The allowUserInteraction argument says whether resolving the link may show dialogs to the user, in case an alias requires mounting an external drive or some other authorization. The default is @false, no user interaction is allowed.
Here’s an example macro that will generate a document with some links. These links are created so they re-run the same macro when clicked, but with some arguments that augment its behavior: instead of again generating a document, the macro will interact with the user.
# check if this macro is being run in response to a clicked link
$args = Macro.arguments
$name = $args{'name'}
If $name
Prompt "Hello $name!"
Exit
End
# This sub command inserts a link which reruns this macro
Define Command InsertHelloLink( $name )
$args = Hash.new('name', $name)
$link = Link.newRunThisMacro($args)
Insert Text "Say hello to $name"
$link.apply
Select End
Type Text ".\n"
End
# make a document and insert links that rerun this macro
$doc = Document.new
InsertHelloLink( 'Tony' )
InsertHelloLink( 'Jason' )
InsertHelloLink( 'Chris' )
NOTE: the above example code must be saved as a file on disk before it will run correctly; you cannot select the code snippet and use the “Run Selection as Macro” command. The reason for this is because the command Link.newRunThisMacro cannot generate a valid link unless the macro has a file path.
| Previous Chapter Image Object |
<< index >> |
Next Chapter ListItem Object |