You are here: User interface > User interface rules > Harness and section forms > Harness and section forms - Adding a Link control

Harness and Section forms
Adding a Link control

  

About link controls

A cell in a layout or harness can contain a Link control (formerly called a URL control), which invokes one or more actions when the user clicks or hovers the mouse pointer over the text link. The Icon/Image and Button controls share most of the same capabilities — the differences are mainly in their presentation.

You can precede and follow a Link cell with static text in Label cells, achieving a presentation similar to an embedded link in a Web page:

You can recompute the interest due on this loan.

Configure styles for links using the Skin rule. See Skin form — Components tab — Controls — Links.

Upgrading link controls

As a best practice, use the Link control pxLink, rather than the deprecated URL control. See The Version 5 URL control. 

If a section contains a deprecated (URL) control, or another control for which there is an improved alternative, such as (pxLink), a warning displays, along with an Update Controls button. Click Update Controls to automatically update deprecated controls in the section. Automatic update is not available for all controls; see Upgrading deprecated and outdated controls on the PDN.

If you have a use case that requires a specific configuration of a standard control, such as a link, you can make a copy of the control and save it using a new name.
For example, if you use a Yes/No radio button frequently, you can save a copy of pxRadioButton as pxYesNoRadioButton. Configure pxYesNoRadioButton to display Yes/No radio buttons, and then use pxYesNoRadioButton wherever you'd like it. Do not modify the Control Modes and UI Element settings.

The UI Gallery landing page contains a working sample. To view and interact with the sample, select Designer Studio > User Interface > UI Gallery. In the Components area, select Link.

Adding a link control

1. Drag and drop the Link control

From the Basic control group, select the Link control. Drag the control to the desired cell. When the pointer changes shape to indicate that a single cell is selected, release the mouse button to drop the control.

If the cell is not empty, the dropped control replaces the current contents of the cell. Click the View propertiesicon to display the Cell Properties panel.

Complete the Cell Properties panel that appears. If the panel is pinned (Pinned), the wireframe presentation on the rule form changes immediately to reflect of your inputs. If the panel is not pinned (not pinned), click Apply to apply your inputs.

2. Complete the Cell Properties panel — Top fields

Field

Description

(Appears only when this field is in a section included within the current open rule.) Click to open the section that immediately contains the field.
Control

The default pxLink control appears. The Standard link format, as defined in the Skin rule, is the default. The default label is "Link." Click the Open icon to review the control identified in this field.

Customizing the control

The Link's default parameters represent the basic configuration. However, you will need to specify the text in the link and the action or actions that will execute when the user clicks or hovers the mouse pointer over the text. See Control Form — Completing the Control tab for descriptions of the available parameters and how to define behaviors.

For example, you can configure the control to refresh a section or display a new harness. In addition, you may want to:

Your edits apply only to the link within the context of the section that contains it and do not update the underlying rule. Do the following to customize an auto-generated control in a section:
  1. Open the section or harness that contains the rule.
  2. Select the cell containing the rule and open its Cell Properties panel.
  3. In the panel, clck the Gear icon next to the Control field. This displays the control Parameters dialog. See Control Form — Completing the Control tab for descriptions of the available parameters and how to define behaviors.
  4. Modify as necessary. You cannot edit the rule form's Control Modes and UI Element settings.
    To immediately render your changes, click OK in the dialog. If satisfactory, save the section. The system generates the XML representing your edits and stores it in the section.

3. Complete the Cell Properties panel — General tab

Complete the General tab.

Field

Description
Visible

Optional. Select to determine when the link appears.

  • Choose Always to have the link appear or be hidden based on the visibility of the enclosing section or flow action when the form is first presented or is refreshed. This condition is checked only once.
  • Choose Other Condition to make the visibility depend on a when condition rule or a Java expression..
Condition

If you selected Other Condition for the Visible field, complete this field.

  • The When Name key part of a when condition rule. Click Open icon to review or create the rule.
  • Simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.

As a best practice, use the Condition Builder to edit this field. Click the Gear icon to open the tool. See Using the Condition Builder to configure dynamic UI actions.

An link that is not visible is also disabled and cannot be clicked.
Run on Client?

Appears when you enter a simple expression in the Condition field. Select to cause evaluation and execution of the condition each time the value of a property stated in the condition changes. If unselected, the expression is evaluated and the condition executed when the form is initially presented and whenever the form is refreshed.

Identifiers  
Tour ID Optional. Provide an ID for use in a guided tour. Use a combination of numbers, letters, and underscores. PRPC uses the Tour ID when it finds an anchor button during a tour stop anchor point.
Test ID

Optional. If authorized, you can provide a unique Test ID for use in your test suite in order to support better automated testing against any Pega application.

When creating a control that supports Test ID, the Test ID field is initially blank. Use a combination of numbers, letters, and underscores, or click the Generate ID button to create a time stamp as a unique ID. The attribute data-test-id is then generated for the selected element.

When you save an existing section, any supported controls that do not have a Test ID will have one automatically generated. You can override these with a custom ID at a later time.

Once generated, you can view your Test ID in HTML or display it in the Live UI panel.

You also have the option to have all controls that support Test IDs in a ruleset updated in bulk.

A standard, out-of-the-box developer role, PegaRULES:SysAdm4, includes the privilege for Test ID. To disable Test ID for this role, modify the pxTestID privilege.

4. Complete the Cell Properties panel — Presentation tab

Complete the Presentation tab.

Control format Optional. Specifies the style format applied to the control. You can define multiple formats in the skin rule. Press the down arrow to select another format, if applicable.
Label format Read-only option. Specifies the format of the control's label.

Type

 

Select a type (editable) used with this property. Your selection filters the format options.

Group/Selection

Description
Email Renders the email address as a link. When the link is clicked, the email composer opens with this value populated in the To: field.
Number Numeric properties on output.
Phone Renders the phone number as a link. When the link is clicked, the phone dialer or another configured phone application opens.
Text Unedited text, which may contain spaces, tabs, line break characters, and other control characters.
URL Opens the URL as a link in new window.
Advanced Options

Note: As a best practice, define custom styles in the skin.

  • Cell read-write classes — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-write mode.
  • Cell read-only classes — Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-only mode.
  • Cell inline style — Type CSS code to define an inline style. As a best practice, define custom styles in the skin. See Skin form — Components tab — General — Custom styles.

5. Complete the Cell Properties panel — Advanced tab

Complete the Advanced tab.

Width

As a best practice, use SmartLayouts to achieve uniform width of cells throughout your application's forms. You can set the width of SmartLayout templates using the Skin rule. See Skin form —Components tab — Layouts — Smart layouts.

Optional. This field appears only when the cell is not controlled by SmartLayout column restrictions. Enter a positive number for the width in pixels of this cell. (At runtime, normal browser processing for rendering tables determines the actual displayed width.) You can also adjust the width this column directly:

  1. Click a vertical wireframe cell border.
  2. Wait until the pointer shape changes, then drag the border.
Height

As a best practice, use SmartLayouts to achieve uniform height of cells throughout your application's forms. You can set the width of SmartLayout templates in the Skin rule. See Skin form —Components tab — Layouts — Smart layouts.

Optional. This field appears only when all columns in the Layout are not controlled by SmartLayout column restrictions (that is, all columns have the None template). Enter a positive number for the height in pixels of this cell. (At runtime, normal browser processing for rendering tables determines the actual displayed height.) You can also adjust the height of a row directly:

  1. Click a horizontal wireframe cell border.
  2. Wait until the pointer shape changes, then drag the border.
Cell read-write classes

Optional. Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-write mode. Define custom styles in the Skin rule. See Skin form — Custom.

Cell read-only classes

Optional. Type the name of the custom style, for example, custom_stylename, that you want to apply to this cell when the user form or flow action form appears in read-only mode. Define custom styles in the Skin rule. See Skin form — Custom.

Show When Active

This check box appears when control is placed in the repeating area of a Grid, Tree Grid, or Tree layout. If checked, the icon displays in the row only when the user selects it.
Cell inline style

Note: As a best practice, define custom styles in the skin.

Optionally, enter CSS code for an inline style for a cell in the column. For guided assistance in composing a style definition, click the Open style editoricon to open the Style Editor. You can select from predefined lists or type a style definition directly, and preview the results.
Related information

Open topic with navigation