Hyperlinking in Canvas allows you to open another Canvas screen via script from the screen you are currently viewing. This is accomplished via script using the Hyperlink method on the sending (hyperlinking) screen and the OpenedViaHyperlink event on the receiving (hyperlinked) screen. Hyperlinking is supported between screens, objects, and nested views in Canvas, Canvas View, and Canvas View Lite. The Hyperlink method supports several modes:
- Open — Opens the specified screen in a new window (default).
- Modal open — Opens the specified screen in a new modal window. A modal window is a type of popup that is subordinate to a parent window that appears in front of the parent and usurps the parent’s control. You cannot interact with the parent window until the modal window has been closed. This type of window is used when you want a user to focus on or interact with information in the popup.
- Open and close — Opens the specified screen in a new window and closes the current screen.
- Replace — Replaces the current screen with the specified screen.
- Replace with navigation — Replaces the current screen with the specified screen and adds a navigation toolbar to the top of the screen.
- Close — Closes the current screen.
Optionally, you can pass a siteService, facility ID, or a data object to a hyperlinked screen.
Note:
See the Navigation Button for information about adding a non-scripted button to your screen that uses the same the hyperlinking modes.
Hyperlink Method
The Hyperlink method is included on the Screen object.
Syntax
Objects.Screen.Hyperlink(path, source, mode);
Parameters
There are several parameters that can be passed in via the Hyperlink method:
| Parameters | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
path |
The path to the file to open. This parameter is required.
Linking between Canvas screens, objects, and nested views is quite flexible. You don't need to specify the service or folder information in the path to find related screens, objects, or nested views, although you can if desired. When specifying a path to another file, the following notes apply: If the screen or object file is in the APPS or BSS, you can specify the:
If the screen or object file is in the local file system, you can specify the:
|
||||||||||||||||||||||||||||||||||||||||
|
source |
The source of the file to open. This parameter is optional. Options include:
|
||||||||||||||||||||||||||||||||||||||||
|
mode |
The optional mode of hyperlinking. There are several modes and the behavior differs depending on the application initiating the hyperlink:
|
||||||||||||||||||||||||||||||||||||||||
|
siteService |
An optional string parameter that can be used to pass content to a hyperlinked screen. Used to pass a siteService to override the hyperlinked screen's siteService with a passed value. |
||||||||||||||||||||||||||||||||||||||||
|
facilityID |
An optional string parameter that can be used to pass content to a hyperlinked screen. Used to pass a facility ID to override the hyperlinked screen's facility ID with a passed value. |
||||||||||||||||||||||||||||||||||||||||
|
data |
An optional string parameter that can be used to pass content to a hyperlinked screen. Used to pass in an object to the hyperlinked screen, for example, a DateTime object, but it can be anything you want to send. This parameter is of type object, but is actually called data. |
||||||||||||||||||||||||||||||||||||||||
Hyperlinking Modes Example
The following example code shows the four hyperlink modes applied to four buttons on a screen. The path of the hyperlink is defined in the Objects.HyperlinkEditBox.Text:
CopyHyperlinking modes example
public ScreenClass()
{
// control event handler code goes here -- do not modify
Objects.Button4.Click += new EventHandler(this.Button4_Click);
Objects.Button2.Click += new EventHandler(this.Button2_Click);
Objects.Button1.Click += new EventHandler(this.Button1_Click);
Objects.Button3.Click += new EventHandler(this.Button3_Click);
// add your custom initialization code here
}
#region Button3
private void Button3_Click(object sender, EventArgs args)
{
Objects.Screen.Hyperlink(Objects.HyperlinkEditBox.Text, CanvasFileSource.Local, HyperlinkMode.Open);
}
#endregion
#region Button1
private void Button1_Click(object sender, EventArgs args)
{
Objects.Screen.Hyperlink(Objects.HyperlinkEditBox.Text, CanvasFileSource.Local, HyperlinkMode.OpenAndClose);
}
#endregion
#region Button2
private void Button2_Click(object sender, EventArgs args)
{
Objects.Screen.Hyperlink(Objects.HyperlinkEditBox.Text, CanvasFileSource.Local, HyperlinkMode.Replace);
}
#endregion
#region Button4
private void Button4_Click(object sender, EventArgs args)
{
Objects.Screen.Hyperlink(Objects.HyperlinkEditBox.Text, CanvasFileSource.Local, HyperlinkMode.ReplaceWithNavigation);
}
#endregion
OpenedViaHyperlink Event
The mechanism by which Canvas accesses this object is the OpenedViaHyperlink event on the hyperlinked screen, which is triggered whenever a screen is opened via a hyperlink. The screen issuing the hyperlink must also provide a value for a data parameter; without this custom data, the event will not fire.
The event requires a parameter that will contain the object that was passed into the Hyperlink method. This way the hyperlinking screen can pass generic data to the hyperlinked screen.
For example, Hyperlink_Screen_A.can can hyperlink to Hyperlink_Screen_B.can and pass in a SiteService and facility to the recipient text tool(s). The hyperlinked screen will load the screen, load the SiteService and facility as originally configured, then clear out the original values, and replace the screen with the overridden values from the hyperlinking screen.
Passing a SiteService or Facility Example
The following example code shows how to pass a SiteService and facility to a hyperlinked screen via a button click event:
CopyPassing a SiteService or Facility example
public void ScreenClassInitializer()
{
// control event handler code goes here -- do not modify
Objects.Button1.Click += new EventHandler(this.Button1_Click);
Objects.Button2.Click += new EventHandler(this.Button2_Click);
// add your custom initialization code here
}
#region Button1
private void Button1_Click(object sender, EventArgs args)
{
Objects.Screen.Hyperlink(@"C:\Canvas Screens\Hyperlink\Hyperlink_Screen_B.can",
CanvasFileSource.Local,
HyperlinkMode.Open,
Objects.Screen.CygNetConfiguration.SiteService.SiteService,
Objects.Screen.CygNetConfiguration.Facility.FacilityID,
DateTime.Now);
}
#endregion
#region Button2
private void Button2_Click(object sender, EventArgs args)
{
Objects.Screen.Hyperlink(@"C:\Canvas Screens\Hyperlink\Hyperlink_Screen_B.can",
CanvasFileSource.Local,
HyperlinkMode.ReplaceWithNavigation,
Objects.Screen.CygNetConfiguration.SiteService.SiteService,
Objects.Screen.CygNetConfiguration.Facility.FacilityID,
DateTime.Now);
}
#endregion
Passing an Object Example
The following example code snippet shows how to pass a DateTime object to a text tool on a hyperlinked screen:
CopyPassing an object example
public ScreenClass()
{
// control event handler code goes here -- do not modify
Objects.Screen.OpenedViaHyperlink += new EventHandler(this.Screen_OpenedViaHyperlink);
// add your custom initialization code here
}
#region Screen
private void Screen_OpenedViaHyperlink(object sender, EventArgs args)
{
var hyperlinkEvent = args as OpenedViaHyperlinkEventArgs;
var date = (DateTime)hyperlinkEvent.Data;
Objects.TextTool3.Text = date.ToString();
}
#endregion
