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.
See Hyperlinking Screens for more information about using this method.
The Hyperlink method is included on the Screen object.
Objects.Screen.Hyperlink(path, source, mode);
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 four possible 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. |
|||||||||||||||||||||||||||||||||||
Example — Hyperlinking modes
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:
|
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 |
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.
Example — Passing a SiteService or facility
The following example code shows how to pass a SiteService and facility to a hyperlinked screen via a button click event:
|
public ScreenClass() { // control event handler code goes here -- do not modify Objects.Screen.OpenedViaHyperlink += new EventHandler(this.Screen_OpenedViaHyperlink); Objects.Button2.Click += new EventHandler(this.Button2_Click); Objects.Button1.Click += new EventHandler(this.Button1_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.SiteService.SiteService, Objects.Screen.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.SiteService.SiteService, Objects.Screen.Facility.FacilityID, DateTime.Now); } #endregion |
Example — Passing an object
The following example code snippet shows how to pass a DateTime object to a text tool on a hyperlinked screen:
|
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 |
|
|
|