How do I add links to a custom view?

A custom view can give its users the same one-click links as the built-in providers, and point them anywhere with an address: a postcode on a map, a record in another system, or a dialog in LUSID. Links work in the Query Editor, dashboards and LumiCode, for every query that uses your view.

Prerequisites

Access to create custom views with Sys.Admin.SetupView. See Creating custom views (Sys.Admin.SetupView).
An understanding of how links work. See Understanding links in Luminesce query results.

Methods

Method 1: Pass on the links of the providers you use

A view column that returns a provider column unchanged keeps that column's link, with nothing to declare. Keep every column the link refers to, under its original name. Here, the LusidInstrumentId link needs Scope:

@x = use Sys.Admin.SetupView
--provider=Views.Examples.Bonds
----
select #SELECT {
  { LusidInstrumentId : LusidInstrumentId },
  { Scope : Scope },
  { Name : DisplayName },
  { MaturityDate : MaturityDate },
}
from Lusid.Instrument.Bond
where #RESTRICT {
  { LusidInstrumentId : LusidInstrumentId },
  { Scope : Scope },
  { Name : DisplayName },
  { MaturityDate : MaturityDate },
}
#LIMIT
enduse;

select * from @x

In this example:

LusidInstrumentId opens the Edit Instrument dialog, as it does on Lusid.Instrument.Bond.
Name is DisplayName renamed. It would keep a link if DisplayName had one.
A column calculated from others, such as upper(DisplayName), has no link unless you declare one (Method 2).

Method 2: Add a link to an external site

Add $"<address>" to a column in the #SELECT or #SELECT_AGG macro. Write a placeholder, such as {PostCode}, wherever a value from the row belongs. This view shows each office's postcode on a map:

@x = use Sys.Admin.SetupView
--provider=Views.Examples.Offices
----
@offices = values
  ('Head office', 'EC2V 7HH'),
  ('North office', 'M2 3AW'),
  ('Scotland office', 'EH2 2AD');

select #SELECT_AGG {
  { Office : column1 },
  { PostCode|"The office postcode. Select it to see the office on a map."$"https://www.google.com/maps/search/?api=1&query={PostCode}" : column2 },
}
from @offices
where #RESTRICT_AGG
#GROUP_BY
#LIMIT
enduse;

select * from @x

Then query the view:

select Office, PostCode from Views.Examples.Offices

Each postcode now opens Google Maps in a new tab. Luminesce encodes the value for you, so the space in EC2V 7HH is safe.

Method 3: Add a link to a LUSID page or dialog

An address that starts with / opens a page in the LUSID web app, in whichever domain the user is signed in to. The quickest way to get a working address is to copy one from Sys.Field:

select TableName, FieldName, ActionTemplate
from Sys.Field
where ActionTemplate like '/%'
order by TableName, FieldName

For example, this view makes each instrument's name open the View Instrument dialog, using the address from the LusidInstrumentId column of Lusid.Portfolio.Txn:

@x = use Sys.Admin.SetupView
--provider=Views.Examples.InstrumentNames
----
select #SELECT {
  { Name|"The instrument name. Select it to view the instrument."$"/data-virtualisation/action-templates/instruments-view?p1=LusidInstrumentId&p2={LusidInstrumentId}&p3={InstrumentScope}" : DisplayName },
  { LusidInstrumentId : LusidInstrumentId },
  { InstrumentScope : Scope },
}
from Lusid.Instrument
where #RESTRICT {
  { Name : DisplayName },
  { LusidInstrumentId : LusidInstrumentId },
  { InstrumentScope : Scope },
}
#LIMIT
enduse;

select * from @x

The placeholders name the view's own columns, so {InstrumentScope} is filled from the view column of that name, not from Scope.

If the provider already has the link you want, Method 1 is simpler. Use this method when it doesn't, or to put the link on a different column.

Check the link

After you publish the view, check that Luminesce registered your link:

select FieldName, ActionTemplate
from Sys.Field
where TableName = 'Views.Examples.Offices'

If ActionTemplate is empty or reads *INVALID*, the link won't show; *INVALID* means Luminesce rejected the address. Also click on a link to verify that they work.

Rules for writing a link

The link goes last in a column's name, after any +, ^, ~Type and |"description", for example { RunId+^~Text|"The run."$"/integrations/run-monitoring/{RunId}" : run_id }.
A link can't contain ".
A link can start with https:, http: or mailto:, or with / for a LUSID page. Other addresses don't show as links.
Placeholders name the view's own columns, using the exact column name. A row shows the link only when the query returns every column the link names, and none of them is empty.
A placeholder can't supply the site's host name. https://{Site}/home doesn't show as a link.
A link you declare on a column replaces any link it would have passed on from its provider.
You can only declare links in a view. A query run on its own can carry links from providers, but can't add its own.