Setting the URL property of a field turns the display value into a link to other content. The URL property setting is the target address of the link and supports using values from any field in the row as part of the URL it constructs.

Substitution Syntax

You can use one or more field values as parameters when creating the URL link, using the ${ } substitution syntax. Put the name of the column whose value you want to use inside the braces. The field with the URL property defined on it is available, but so are any other fields in the data structure.

For example, if your data includes a "GeneSymbol" field displaying values like "BRCA", you could link to related information in The Gene Ontology by using a search URL. When the user clicked the value "BRCA", they would go to:

In this case the field value is passed as a search parameter, so to construct the URL property on the GeneSymbol field, you would add this URL property to the GeneSymbol field:${GeneSymbol}

You could also define this URL property on a different field, letting you display the gene symbol unlinked and link a value in another field (like "Click to Search") to perform the search.

Substitutions are allowed in any part of the URL, either in the main path, in the query string, or both. For example, here are two different formats for creating links to an article in wikipedia, here using a "CompanyName" field value:

  • as part of the path:
  • as a parameter value:

Local Links

To link to content in the current LabKey folder, use the controller and action name. You can optionally prepend a / (slash) or ./ (dot-slash), but they are not necessary.


For example, you can link to a specific item on a list. If you had a list (here listId=5) that mapped building numbers to details about them, you could create a column "Building" and use this URL property, letting your users click the "Building" value to open the details page.


External Links

To link to a resource on an external server or any website, include the full URL link.


URL Encoding Options

You can specify the type of URL encoding for a substitution marker, in case the default behavior doesn't work for the URLs needed. This flexibility makes it possible to have one column display the text and a second column can contain the entire href value, or only a part of the href.

The fields referenced by the ${ } substitution markers might contain any sort of text, including special characters such as question marks, equal signs, and ampersands. If these values are copied straight into the link address, the resulting address would be interpreted incorrectly. To avoid this problem, LabKey Server encodes text values before copying them into the URL. In encoding, characters such as ? are replaced by their character code %3F. By default, LabKey encodes all special character values except '/' from substitution markers. If you know that a field referenced by a substitution marker needs no encoding (because it has already been encoded, perhaps) or needs different encoding rules, inside the ${ } syntax, you can specify encoding options as described in the topic String Expression Format Functions.

Related Topics