2.0/Links

Links are used to display either a hyperlink to external web pages, or an internal link in ProcessMaker, such as a link to another case.

Properties

• Field Name *Required
• Label

Behavior

• Link
• Target
• Value
• Hint

Link property

The address for the link, such as "http://www.myhomepage.com/welcome.html" or "file://192.168.1.1/Reports/quarter9-09.xls".

If the address for the link does not include the protocol, such as http:, ftp: or file:, then it will be treated as a relative link found at:
   http://<IP-ADDRESS>/sys<WORKSPACE>/<LANGUAGE>/<SKIN>/dynaforms/
Remember to include the protocol. If it is not included, then the value of the Link property will be appended to the end, so "www.processmaker.com" becomes a URL like:
   http://localhost/sysworkflow/en/green/dynaforms/www.processmaker.com

Linking inside ProcessMaker

It is best to use relative links when linking to another page inside ProcessMaker. Below are a list of different types of links to use. See G::header() for an explanation of the different GET variables to pass in the following links:

• The login screen: "../login/login"
• The cases list:
  • In version 1.2: "../cases/cases_List"
  • In version 1.6: "../cases/main"
  • In version 2.0: "../cases/casesListExtJs"
  • To open in the top frame in version 2.0: "../cases/casesListExtJsRedirector"
• Start a new case: "../cases/cases_New"
• Open an existing case: "../cases/cases_Open?APP_UID=<CASE-UID>&DEL_INDEX=<INDEX>"
• To open a step in the same task: "../cases/cases_Step?TYPE=<TYPE>&UID=<STEP-UID>&POSITION=<STEP-NUMBER>&ACTION=<ACTION>"
  • DynaForm step:
    • For editing: "../cases/cases_Step?TYPE=DYNAFORM&UID=<STEP-UID>&POSITION=<STEP-NUMBER>&ACTION=EDIT"
    • For viewing: "../cases/cases_Step?TYPE=DYNAFORM&UID=<STEP-UID>&POSITION=<STEP-NUMBER>&ACTION=VIEW"
  • Input Document step:
    • For attaching: "../cases/cases_Step?TYPE=INPUT_DOCUMENT&UID=<STEP-UID>&POSITION=<STEP-NUMBER>&ACTION=ATTACH"
    • For viewing: "../cases/cases_Step?TYPE=INPUT_DOCUMENT&UID=<STEP-UID>&POSITION=<STEP-NUMBER>&ACTION=VIEW"
  • Output Document step:
    • For generating: "../cases/cases_Step?TYPE=OUTPUT_DOCUMENT&UID=<STEP-UID>&POSITION=<STEP-NUMBER>&ACTION=GENERATE"
    • For viewing: "../cases/cases_Step?TYPE=OUTPUT_DOCUMENT&UID=<STEP-UID>&POSITION=<STEP-NUMBER>&ACTION=VIEW"
  • External step: "../cases/cases_Step?TYPE=EXTERNAL&UID=<STEP-UID>&POSITION=<STEP-NUMBER>&ACTION="
  • Notification (Email): "../cases/cases_Step?TYPE=MESSAGE&UID=<STEP-UID>&POSITION=<STEP-NUMBER>&ACTION="
  • End of task for routing: "../cases/cases_Step?TYPE=ASSIGN_TASK&UID=-1&POSITION=10000&ACTION=ASSIGN"
• Route (derivate) the current case to the next task: "../cases/cases_Derivate"
• Reassign a case to another user: "../cases/cases_Reassign?APP_UID=<CASE-UID>&DEL_INDEX=<INDEX>"
• Open a particular Input Document file:
  • Latest version: "../cases/cases_ShowDocument?a=<CASE-DOCUMENT-UID>"
  • Specified version: "../cases/cases_ShowDocument?a=<CASE-DOCUMENT-UID>&v=<VERSION-NUMBER>"
• Open a generated Output Document:
  • Lastest Version: "../cases/cases_ShowOutputDocument?a=<CASE-DOCUMENT-UID>&ext=<EXTENSION>"
  • Specified Version: "../cases/cases_ShowOutputDocument?a=<CASE-DOCUMENT-UID>&ext=<EXTENSION>&v=<VERSION-NUMBER>"
• Open a file in the "public" directory of the Process Files Manager: "../<PROCESS-UID>/<FILENAME>"

Linking to Local Files

To link to a file stored locally on a Linux server, use the URL:
   file:///path/to/file
For a local file on a Windows server:
   file:///C:/path/to/file

Note that FireFox has a security policy which prevents opening local files by clicking on a link. To open the file, right click on the link, select "Copy Link Location", then go to the address box and press CTL+V to paste the link and then hit ENTER. To turn off this security policy, see these instructions. To avoid these problems, put files in the "public" directory of the Process Files Manager.

XML Definition:

<NAME ... link="URL" ...>...</NAME>

Target property

The Target dropdown box is a new feature in ProcessMaker version 2.0 and is used to select where the link will be opened when clicked. There are five available options:

• Blank: The default option. Open the link in a new, unnamed browser window (or tab if the web browser is so configured). This option allows the user to continue working on the DynaForm.
• Self: Open the link in the same frame as the current DynaForm. This option will replace the DynaForm, but will leave the ProcessMaker top menu bar, the Cases top menu bar, and the Cases side bar on the screen.
• Parent: Open the link in the parent of the current frame. This option will replace the DynaForm and the Cases top menu bar, but will leave the ProcessMaker top menu bar and the Cases side menu bar on the screen.
• Top: Open the link in the topmost frame. This will open the link in the current browser window, replacing all content on the window, but the current topmost frame name will be maintained.
• Framename: Open the link in a specified frame. The specified frame can be one of the frames used by ProcessMaker or a custom frame (either in the same window or in a different window). If the frame name already already exists, then the link will open in that frame, otherwise the brower will open in a new window (or tab) with that new frame name. To maintain the ProcessMaker top menu bar, but replace the DynaForm and Cases side bar with the link, specify the "casesFrame" frame.

XML Definition:

<NAME ... target_sel="_blank|_self|_parent|_top" target="_blank|_self|_parent|_top" ...>...</NAME>

For the Framename option:

<NAME ... target_sel="" target="FRAME-NAME" ...>...</NAME>

Value property

The Value is the text shown to the user for the link. It can be the same text as the Link, if you want the user to see the address. Do NOT put HTML formatting tags in the Value. If formatting needs to be added to the displayed text for a link, then use JavaScript to set the innerHTML property of the link. (See example below.)

Note that the Value is different from the Label, which is the text displayed on the right hand side of the link to give more information about the link or identify it.

XML Definition:

<NAME ... value="TEXT" ...>...</NAME>

Saving Addresses and Labels as Case Variables

Available version: From 2.5 on

Adding Addresses and Labels give the possibility to set and save them as Case Variables, this can be used to populate links in a grid via trigger and also using JavaScript.

Definition:

Link-Name: specifies the Link, using Case Variables: @@Link

Link-label: specifies the label used for the Link, using Case Variables: @@Link_label

Accessing Links with JavaScript

Link fields can not be accessed through their value and link properties, since they are just normal HTML hyperlinks. Instead, access DynaForm link fields through their href and innerHTML properties.

To read a link's address:

var x = getField(ĺink-name).href;

To change a link's address:

getField(link-name).href = "URL";

To read the displayed text for a link:

var x = getField(link-name).innerHTML;

To change the displayed text for a link:

getField(link-name).innerHTML = "display-text";

By default, links open in the same window as the DynaForm. To make a link open in a separate window add the code:

getField(link-name).target = "_blank";

To click on a link using code:

if (getField(link-name).getAttribute('click')) //Internet Explorer
   getField(link-name).click();
else                                           //Firefox & other browsers
   getField(link-name).onclick();

Example with a button

A DynaForm has a button named "ToggleLink" which causes a link named "MyLink" to switch between the two addresses for Google and Yahoo:

 function toggleLink()
 {
    if (getField("MyLink").href == "http://www.google.com")
    {
       getField("MyLink").href = "http://www.yahoo.com";
       getField("MyLink").innerHTML = "Yahoo!";
    }
    else
    {
       getField("MyLink").href = "http://www.google.com";
       getField("MyLink").innerHTML = "Google";
    }
 }
 getField("ToggleLink").onclick = toggleLink;

Example of a link containing a graphic

In HTML, a graphic can serve as a link. For example:

 <a href="http://www.processmaker.com"><img src="http://www.processmaker.com/logo.png"></a>

However, DynaForm links do not allow HTML codes to be used in their Value property, so graphics can't be used as links. Instead, use JavaScript to insert a graphic into a link's displayed text when the DynaForm is initially displayed:

 getField("MyLink").innerHTML = '<img src="http://www.processmaker.com/logo.png">';

Example with a dropdown box

A DynaForm has a dropdown box named "SelectProduct" with a list of products to be ordered. The value for each option is a link to the product, and its label is the text to display for the link. Depending upon which product is selected, the link named "ProductLink" will be changed:

 function changeLink()
 {
    getField("ProductLink").href = this.value;
    getField("ProductLink").innerHTML = this.options[this.selectedIndex].text;
 }
 getField("SelectProduct").onchange = changeLink;

A separate window could be automatically opened whenever a new option is selected in the dropdown box "SelectProduct":

 var productWindow;
 function changeLink()
 {
    if (productWindow)
        productWindow.location.href = this.value;
    else 
        productWindow = window.open(this.value, "productWindow", "width=350,height=450");
 }
 getField("SelectProduct").onchange = changeLink;

Populating a Link Using Case Variables

To populate a link field using JavaScript with Case Variables use the following code:

   getField("MyLink").href = "http://www.php.net"; [^]// to obtain Link
   getField("MyLink").innerHTML = "Read about PHP"; // To obtain Label

Accessing Links with Triggers

DynaForm links do not store their values as case variables like normal fields when a DynaForm is submitted. In order to save the value of a DynaForm link so it can later be used in a trigger, the link must be saved in a hidden field when the DynaForm is submitted.

For example, add the following JavaScript code to a Submit button in a DynaForm, so that the the address and displayed text of a DynaForm link named "MyLink" will be saved in two hidden fields named "MyLinkHref" and "MyLinkText":

 function saveLink()
 {
    getField("MyLinkHref").value = getField("MyLink").href;
    getField("MyLinkText").value = getField("MyLink").innerHTML;
 }
 getField("MySubmitButton").onclick = saveLink;

Then the address and displayed text can later be used in a Trigger by looking at the case variables @@MyLinkHref and @@MyLinkText:

 $x = @@MyLinkHref;
 $y = @@MyLinkText;

In order to set the value of a DynaForm link in a trigger, the link's address and displayed text have to be passed to the DynaForm in hidden fields. Then use JavaScript to read these hidden fields when the DynaForm is initially displayed and set the href and innerHTML properties of the link.

For example, if a DynaForm has a link named "MyLink", then add two hidden fields to the DynaForm named "MyLinkHref" and "MyLinkText" to hold the link's address and displayed text which will be set in the trigger. Then, create the following trigger to be fired before the DynaForm is displayed:

 @@MyLinkHref = "http://www.processmaker.com";
 @@MyLinkText = "ProcessMaker Open Source";

Add the following JavaScript to the DynaForm to set the properties of MyLink when the form is initially displayed:

 getField("MyLink").href = getField("MyLinkHref").value;
 getField("MyLink").innerHTML = getField("MyLinkText").value;

Populating Link fields with Triggers using case variables

In order to set the label and link in a Dynaform, using LinkField as the name of the Link field and LinkField_label where label of the link will be saved. Creating a trigger:

@@LinkField="http://www.php.net"; 
@@LinkField_label="Read about PHP";

Assigning it Before Dynaform results will be:

Setting Links in Grids

With JavaScript the getGridField() function can be used to access a grid field link and set its label and URL. For example, to set the "homePage" link in the first row of a grid named "contactsGrid":

 getGridField("contactsGrid", 1, "homePage").href = "http://www.janescorner.com";
 getGridField("contactsGrid", 1, "homePage").innerHTML = "Jane Doe's home page";

Similarly, a trigger could be fired beforehand to set case variables for the link's label and URL and pass those case variables as hidden fields in the DynaForm:

@@homePageHref = "http://www.janescorner.com";
@@homePageText = "Jane Doe";

Then, create hidden fields named "homePageHref" and "homePageText" in the DynaForm and use the following JavaScript would populate the "homePage" link in the first row of the "contactsGrid":

 getGridField("contactsGrid", 1, "homePage").href = getValueById("homePageHref");
 getGridField("contactsGrid", 1, "homePage").innerHTML = getValueById("homePageText");

The problem is that there can be a variable number of grid rows, and it would be difficult to create a variable number of hidden fields. The solution is to create an associative array of associative arrays (which is how a grid is stored) in a trigger and pass that array to the DynaForm as a serialized JSON string in a hidden field.

For example, this trigger is used to populate the "contactsGrid" with 3 rows and also create a serialized string of the grid which can be passed to hidden field named "sContacts" in the DynaForm:

 @=contactsGrid = array(
   "1" => array("firstName"=>"Jane", "lastName"=>"Doe",   "linkText"=>"Jane's Home", "linkHref"=>"http://www.janescorner.com"   ),
   "2" => array("firstName"=>"John", "lastName"=>"Smith", "linkText"=>"John's Page", "linkHref"=>"http://www.johnsmith.com/info"),
   "3" => array("firstName"=>"Jess", "lastName"=>"Depp",  "linkText"=>"Jess' Home",  "linkHref"=>"http://www.jessathome.com"    )
 );
 @@sContacts = json_encode(@=contactsGrid); //serialize the array

If the grid was populated with a database query, then the trigger would be very similar. For example:

 @=contactsGrid = executeQuery("SELECT firstName, lastName, linkText, linkHref FROM CONTACTS");
 if (is_array(@=contactsGrid) and count(@=contactsGrid) > 0)
    @@sContacts = json_encode(@=gridContacts); //serialize the array
 else
    @@sContacts = "";

Then, use JavaScript to unserialize the string and populate the "homePage" links in the grid:

 var oContacts = eval('(' + getValueById("sContacts") + ')'); //unserialize the grid as object
 if (oContacts) {
    for (var rowNo in oContacts) {
       getGridField('contactsGrid', rowNo, 'homePage').href = oContacts[rowNo]["linkHref"];
       getGridField('contactsGrid', rowNo, 'homePage').innerHTML = oContacts[rowNo]["linkText"];
       getGridField('contactsGrid', rowNo, 'homePage').target = '_blank'; //to open in separate page
    }
 }