Link an event to another page

Add a link to the destination event handler within UI Builder so that an event action can open another page. You can also configure the event handler to follow the App Route to the desired page.

Before you begin

You must have a workspace page that contains a component that is intended to open another page when a user clicks it. The dashboard overview is an example of such a component. Components such as Link to Destination do not support the link to destination event handle. The component link property takes priority over the link to destination event handler.

Role required: ui_builder_admin

About this task

To configure an event action to open another page, you must know what page you want to open, what the required and optional parameters are for that page, and what payload values to set on the event handler to pass the required parameters to the destination page.

Tip:

You may be able to find examples of both the components that you want to link from and the destination pages that you want to link to in the Base Agent Workspace Experience. This Next Experience is provided in the base system. If you create a page from a page template, you should only copy the contents of the template. Do not reference it. For more information about the difference between copying and referencing a page template, see Create a page from a template.

Procedure

1. Open your experience in UI Builder.
2. Optional: If the destination page doesn't exist in your experience, create one.
   For information about creating pages, see Create a page in UI Builder. Make sure that you set the required and optional parameters for the page so that you can use it as a destination. If a particular component in the page is a destination, you must include that component. You also must configure the properties on the component to consume the page parameters with @context.props.<parameter-name> values.

   You might consider creating the page from a page template. The Base Agent Workspace Experience has several page templates that are already configured to be destinations for other components. If you create a destination page from a template, the components are already configured with the correct properties. Any necessary state parameters or client scripts are also copied over. You have to add the page parameters. You can copy these parameters from the UX App Routes related list on the Agent app config [sys_ux_app_config] record of the experience that contains the page templates.

   To make sure that the pages that you are creating work reliably as destinations in your experience, your experience must have the same app shell UI as the experience with the page templates.

3. Switch to the page that you want to link to the destination page.
4. Navigate to the relevant component and select it.
5. Select the Events tab.
6. Select + Add event mapping.
7. Select the event you want to use.
8. Select + Add event handler.
   
9. In the Inherited event handlers section, select Link to destination.
   
10. Click Select destination.
    
11. Expand Pages and select the page in the experience that you want to link to.
    Fields appear for each of the parameters on the destination page that the route leads to. Required parameters are marked with an asterisk (*).
12. Complete each required parameter field and the applicable parameter fields with an appropriate @payload.* value.
    If the developers of your component included default payload values in your event, you can select one through autocompletion. As shown in the following example, the payload value may not match the parameter name.

    

    Note:

    You have the option to link to an External URL instead of specifying an App route.

    If no default values are provided, or you can't determine which values are correct for some fields, refer to the configuration and API documentation for the component in the . If you still can't find the necessary @payload.* values, contact Customer Service and Support.

    Tip:

    If you create your linking component by creating a page from a Base Agent Workspace page template, the component contains Link to destination Relay event handlers. These event handlers do not work. However, they contain the applicable @payload.* values for the parameters.

Configuring the event handlers for an Analytics Q&A component

Let's say that you want to take a new Next Experience and add a page with an Analytics Q&A component. First, you create the page from the Analytics Center page template that is provided in the Base Agent Workspace experience. Next, you create a target page for the first of the three events in Analytics Q&A and then you configure an event handler for that event.

By navigating to Now Experiences Framework > Experiences, you see the Test experience UX application. Because it uses the same Agent Workspace App Shell UI as the Base Agent Workspace, you can use the page templates from the Base Agent Workspace.

You next select the Test workspace admin panel, find an UX App Configuration record with no UX app routes or pages, and then click Open.

As the example shows, in the UI Builder, you have created a page named Analytics Center that is based on the Analytics Center page template from the Base Agent Workspace. Next, you select the option to copy only the contents of the page template.

You select the Analytics Q&A 1 component and open the Events tab. From here, you can open theLink to destination Relay event handler for the Report Visualization Clicked event. When a question in Analytics Q&A returns a report, you can trigger this event by clicking a value in the report. When you click a value, you also see a list of the records that contribute to this value. In the Route field, you see that the destination is expected to be a page that is based on the Simple List page template. You also see the parameters of the page that the @payload.* values correspond to, and that the Title field can be populated with @payload.listTitle.

Table 1. Parameters of suggested Simple List destination page and corresponding payloads

Parameter	@payload.* value
table (required)	@payload.table
listTitle	@payload.listTitle
query	@payload.query
disableInlineEditing	none

Next, you navigate to Menu > Create page and create a page that is based on the Simple List template. Let's say that you name the page as Record list. You then follow a similar process as when you created the Analytics Center page. This time, in the last steps of the process, you would add table as a required parameter and listTitle, query, and disableInlineEditing as optional parameters.

Because this page already contains a List component, when you open the Config tab for this component, you see that the parameters are already passed in the @context.props.* values.

Now, you return to the Analytics Center page. In the Report Visualization Clicked event, you add a new event handler. Next, you select the Record list page that you created and add the @payload.* values in the table, listTitle, and query fields, following the information that you got from the Link to destination Relay event handler. Predictive typing helps you to fill in these fields.

After you click OK and add @payload.listTitle as the Title, the event handler is done. You can now delete theLink to destination Relay event handler for this event.

The following example shows an Analytics Center page. On this page, you can enter a query for Incidents by Priority and get a report as a result. Also, by clicking a column, you trigger a Report Visualization Clicked event. The event handler enables you to see a simple list of the incidents in the report.

Figure 1. Triggering the configured Report Visualization Clicked event