Use SmartObject properties in a hyperlink expression to navigate to a URL

This article illustrates how to create a hyperlink expression that uses SmartObject properties for the expression parameters. You assign the expression to a hyperlink control on a view; when someone clicks the hyperlink, the target URL opens in a new window. For example, you may have a SmartObject that contains a URL value and a display value for the URL. You want to use those two properties to create a clickable hyperlink on a view so that someone can easily open the link.

The view you build in this topic with the hyperlink control
SmartObject Hyperlink

Try it yourself!

Scenario

You work in Human Resources, where you maintain an online form for employees to submit expense claims. Your company has a global presence, and employees often submit claims for more than one country. As a convenience, you provide a link to an exchange rate website for employees to reference since all amounts must be in US dollars. You configure the hyperlink control with an expression that retrieves the URL and display values from a SmartObject.

Steps

In this scenario, you build a SmartBox SmartObject called Expense Details. You design an item view based on the SmartObject. Editing the view, you add a hyperlink control to the canvas, then create a new expression that sets the display name and URL values for the control.

Prior to working through this how-to, you should know how to work with the category system and add elements such as SmartObjects and views. If you do not know how to build the basic application elements, see: Getting Started (with the Designer).

Setup Steps

The following steps set up the scenario from start to finish. If you want to skip the setup steps and view the topic step, go to Add and configure a hyperlink expression.

  1. In the Designer, create a SmartBox SmartObject called Expense Details. Add the following properties: Employee Name (Text), Amount (Number), Hyperlink Display (Text), and Hyperlink URL (Text). (Optional) Create categories first to keep your work organized.
    1. Launch the Designer.
    2. Create categories to keep your work organized. Right-click All Items and select New Category. Use the image below as a guide for category names.
      Create Categories
    3. Right-click the Hyperlink Expression category and select New SmartObject.
    4. Name the SmartObject
      Expense Details
      and confirm the SmartBox type is selected. Click Create.
      Create SmartObject
    5. On the Expense Details screen, click Add. Name the first property
      Employee Name
      and keep the default Text data type. Add the remaining three properties using the table below as a guide. Click OK. Click Finish to save and exit the SmartObject.
      NameTypeNotes
      AmountNumber 
      Hyperlink DisplayTextThis is the text that displays on the hyperlink control. (In this specific example, you hard-code this property in a rule action, then use it as a parameter value when configuring the hyperlink expression.)
      Hyperlink URLTextThis is the target URL that you want to open. (In this specific example you hard-code this property in a rule action, then use it as a parameter value when configuring the hyperlink expression.)
      Create SmartObject
  2. Design an item view based on the Expense Details SmartObject and name it Expense Details Item. Select Create Labels and Controls, then include the Employee Name and Amount fields (you don't need to include any other fields). Add a standard Create button.
    1. Right-click the Expense Details SmartObject and select Design View.
    2. On the General settings screen, name the view
      Expense Details Item
      and confirm the Item View type is selected. Click Create.
      Generate Expense Details Item View
    3. Click Create Labels and Controls.
      Create Labels and Controls
    4. On the Create Labels and Controls screen, include the Employee Name and Amount fields (in the Layout section). Include the standard Create button (in the Buttons section). Click OK.
      Create Labels and Controls
  3. Add a new row just above the Create button. Add a Hyperlink control to the canvas in the second row, first column cell.

    The next step is to add a hyperlink control to your details view. Later, you create a new expression for the control using the hyperlink function to set the expression parameters.

    1. Begin by adding a new row for the hyperlink control. Click the row containing the Create button. Click the Insert Row Above icon in the toolbar.
      Move Controls on View Canvas
    2. From the Toolbox on the left side of your screen, drag a Hyperlink control into the second row, first column cell.
      Add Hyperlink Control

Add and configure a hyperlink expression

In the next step, you add an expression to the hyperlink control that sets the control's display name value and URL. You use SmartObject properties as parameters in the expression.

  1. Add an expression to the Hyperlink control. Name the expression Exchange Rate Website. From the Operators menu, add the Hyperlink function (found in the Text menu tree) to the editor pane. From the Context menu, add the Expense Details (SmartObject) > Hyperlink Display property to the first parameter text box, and the Expense Details (SmartObject) > Hyperlink URL property to the second parameter text box. Your final expression should read: Hyperlink ( Hyperlink Display, Hyperlink URL ).
    1. Select the Hyperlink control. In the Properties, locate the Expression property and click the ellipses to open the expression editor.
      Open Expression Editor
    2. On the expression editor landing page, click Add. On the Add Expression screen, name the new expression
      Exchange Rate Website.
      Add Expression
    3. Next, you add the hyperlink function. The function provides a display name for the hyperlink that you see on the view, along with the URL to follow when you click the link. In the Context Browser, click the Operators tab. Drag the Text > Hyperlink function into the first text box in the editor pane. (The first text box appears as you drag the function into the editor pane.)
      Add Hyperlink Function

      4. Notice you now have two parameters for this function. The first parameter is for the hyperlink's display name and the second parameter is for the URL of the site you want to navigate to. Both parameters are required to complete the hyperlink expression.
      Hyperlink Function Parameters

    4. In the Context Browser, click the Context tab. Expand the Expense Details Item (view) > Expense Details (SmartObject). Drag the Hyperlink Display property into the first parameter text box. Drag the Hyperlink URL property into the second parameter text box. Click OK to save your settings. Click OK to save the expression.
      Add Parameter Values
  2. The two properties used to build the hyperlink must have values for the expression to work. Typically, the values are already stored in the SmartObject and retrieved when the view loads, but in this example we use rules to manually set the values for the Hyperlink Display and Hyperlink URL properties when the view loads. Add a new rule when the view loads with a transfer data action. From the Rules screen, add a view initialized rule. Add a Transfer Data action. In the Mapping Destination screen, expand the Expense Details SmartObject and enter the following two values:
    • Hyperlink Display: Live Exchange Rates
    • Hyperlink URL: https://www.xe.com/?
    Transfer Data Values

    To simulate loading the values of the Hyperlink Display and Hyperlink URL properties, add a transfer data action to the view initialized rule and manually enter the two values. When the view loads, the Hyperlink Display and Hyperlink URL parameters load with the values you used.

    1. Begin by adding a new rule for when the view loads. Click the Rules tab, then click Add Rule.
      Add Rule
    2. With the Events tab active, click When the View executes a method to add it to the rule definition pane. Click select method and select Initialized. This rule executes when the view opens.
      View Initialized Event
    3. Click the Actions tab and click Transfer data. (You can also search for the action instead of scrolling through the list.) Click configure.
      Transfer Data Action
    4. In the Mapping Destinations section, expand the Expense Details SmartObject. (Make sure you are working with the SmartObject properties and not controls.) For the Hyperlink Display value, enter
      Live Exchange Rates
      and for the Hyperlink URL value, enter
      https://www.xe.com/?
      then click OK to save the settings.
      Transfer Data Values
    5. Your rule should look like the image below. Click OK to save the rule and Finish to save and exit the view.
      Compete Rule
  3. Test the hyperlink expression by running the view. The display name link should read Live Exchange Rates. When you click the link, the exchange rate website should open in a new browser window.
    1. Right-click the Expense Details Item view and select Run.
    2. You should see the hyperlink control display Live Exchange Rates. Click the link and the exchange rate website opens in a new browser window.
      Run View to Test
Review

In this demonstration, you used an expression to create dynamic values for a hyperlink control. The hyperlink function has two parameters: Display Name and URL. These parameters can be stored in SmartObject properties, fields on the view, or other expressions. Combined with rules, you can create dynamic values to generate hyperlinks on your views.