WP SET LINK

Home

4D v20

WP SET LINK


WP SET LINK ( targetObj ; linkObj )

Parameter	Type	Description
targetObj	Object	Range or element or 4D Write Pro document
linkObj	Object	Hyperlink value

Description

The WP SET LINK applies a hyperlink reference to the targetObj. Links to URLs, 4D methods, and bookmarks, are supported. The link triggers an action when the user clicks on it (or uses Ctrl+click on Windows or Cmd+click on macOS if the text is not read-only for opening URLs).

In targetObj, pass the 4D Write Pro object where the link will be applied. You can pass:

a range, or
an element (table / row / paragraph / body / header / footer / section / subsection), or
a 4D Write Pro document

For example, if you pass a header, the entire contents of the header will be displayed as a hyperlink. When inserting links in your documents, 4D Write Pro applies the following rules:

If you set a link to a targetObj that contains several paragraphs, several separate links will be defined.
If you set a link to a targetObj that already contains link(s):
- any existing links that are fully included in the targetObj are removed and the new link is applied to the targetObj.
- if a link is partially selected (it intersects the targetObj), it is reduced so that the external part keeps the previous link and the new link is applied to the targetObj.

In the linkObj parameter, pass an object that describes the hyperlink. It must contain only one the following properties (except the parameter property which can be used in conjunction with the method property):

Property

Type

Description

Hyperlink action

url

Text

Destination for a URL type hyperlink (encoded url).

References a standard web address (http or https://website, mailto:abc@xyz.com, etc.): opens the URL in the default application (usually a browser)
References a file path (absolute or relative to the 4D structure file). When referencing a .4wp or .4w7 file (file://filepath or filepath/file.4wp): loads and replaces the current document. When referencing other file types, opens file in the system default application for the file type.

bookmark

Text

Bookmark name

Accesses the specified bookmark in the current document. (See Bookmark commands)

method

Text

Project method name - method must exist and be allowed with the SET ALLOWED METHODS command.

Executes the 4D method when clicked. The method automatically receives two parameters in $1 and $2:

Parameter	Property	Type	Description
$1		Text	Name of 4D Write Pro area
$2		Object
	method	Text	Name of 4D method
	parameter	Text \| Number	User parameter sent to the method through the parameter property (optional, see below)
	range	Object	Range of the targetObj

parameter

Text | Number

Used only with a method type link, not mandatory if the method does not require parameter. Contains an additional parameter to send to the method.

Received in $2.parameter within the method

Notes:

4D Write Pro accepts only valid (encoded) URLs. Special characters in links are not translated. If special characters are necessary, you must expressly encode them (e.g., %20 instead of " " for a space character). If the link is not valid, an error is generated.
Links to 4D methods are removed from 4D Write Pro documents when they are exported in HTML, MIME HTML, or .docx format.
If you want to remove a link from targetObj, please refer to the Link commands paragraph.

Example 1

You want to add a link to your website in the footer area of your document:

 C_OBJECT($footer)

 $footer:=WP Get footer(WPArea;1)

 WP SET TEXT($footer;"Please visit our website";wk replace)

 WP SET LINK($footer;New object("url";"http://www.4d.com"))

Example 2

You want to create a table of contents with links using all of the bookmarks in your document:

 C_LONGINT($i;$n;$p;$memoStart)

 C_OBJECT($range;$link;$toc;$tocRange;$positionInfo;$target)

 C_TEXT($text)

 

 ARRAY TEXT($_bookmarks;0)

 WP GET BOOKMARKS(WParea1;$_bookmarks) //find all the bookmarks

 

 $n:=Size of array($_bookmarks)

 If($n>0)

    $tocRange:=WP Text range(WParea1;wk start text;wk start text) //find the beginning of the text

    WP INSERT BREAK($tocRange;wk page break;wk append;wk exclude from range) //add a page break before the text

 

    For($i;1;$n) // Insert the table of contents and links

       $range:=WP Bookmark range(WParea1;$_bookmarks{$i})

       $positionInfo:=WP Get position($range)

       $memoStart:=$tocRange.end

       WP SET TEXT($tocRange;Char(Tab)+$_bookmarks{$i}+Char(Tab)+String($positionInfo.page);wk append;wk include in range)

 

       $target:=WP Text range($tocRange;$memoStart+1;$memoStart+1+Length($_bookmarks{$i}))

       $link:=New object("bookmark";$_bookmarks{$i})

       WP SET LINK($target;$link)

       WP INSERT BREAK($tocRange;wk line break;wk append;wk include in range)

    End for

 End if

Example 3

You want to set a link to a 4D method on each "4D" string in the document:

 C_TEXT($text,$find)

 C_LONGINT($p)

 C_OBJECT($range;$link)

 

 $text:=WP Get text(wpArea;wk expressions as value) //retrieves all text in document

 

 $find:="4D" //target for link

 

 $p:=Position($find;$text) //loop through text to find all instances of the target

 If($p>0)

    $range:=WP Text range(wpArea;$p;$p+Length($find)) //set the length of the target

  //create the link object

    $link:=New object("method";"myAlert";"parameter";"4D rocks!") //Don't forget to authorize with SET ALLOWED METHODS  

 

    WP SET LINK($range;$link)

 End if