Table of Contents

guest
2020-05-28
       LabKey URLs
         URL Actions

LabKey URLs


Overview

A client browsing pages on a LabKey web site typically sees URLs that look like this:

https://example.com/labkey/home/study-begin.view

The general form is:

<protocol>://<domain>/<contextpath>/<containerpath>/<controller>-<action>

Details on the meaning of each URL part:

URL PartExampleDescription
protocolhttps://Supported protocols are http or https (for secure sockets).
domainwww.labkey.orgYour server's host domain name.
contextpathlabkeyThis is the root of the LabKey web application on the server, and is accessible by developers if they need to build URLs that include it. In the JavaScript API library, see LABKEY.ActionURL.getContextPath(). In Java module code, this is accessible from AppProps.getInstance().getContextPath().
containerpathhome/myproject/myfolderThis may consist of multiple parts if the current container is a sub-folder (e.g., “/project/folder/subfolder/”). This helps the LabKey Server know which container the user is working in. The current container information is also available to developers. In the JavaScript API library, see LABKEY.ActionURL.getContainer(). In Java module code, you can get this information from the Container object returned from the getContainer() method on your action base class. (For details on the container hierarchy reflected in the container path, see Site Structure: Best Practices.)
controllerstudyThe term "controller" comes from the Model-View-Controller (MVC) design pattern, where a controller coordinates user interaction with the model (data) as seen through a particular view of that data. The LabKey Server uses the industry-standard Spring framework for its MVC implementation.
In the LabKey Server, the name of the controller typically matches the name of the module. The system assumes that the controller name is the same as the module name unless the module has explicitly registered other controllers.
actionbegin.viewModules/controllers may expose one or more actions, each of which may do several things. Simple actions may return a read-only view, while more complex actions may return an HTML form and handle the posted data, updating the database as necessary. Actions typically have the extension “.view” or “.post”.

Setting the Default URL Pattern

As of version 16.1, new server installations use the following URL pattern by default:

New URL Pattern

<protocol>://<domain>/<contextpath>/<containerpath>/<controller>-<action>

Servers installed before version 16.1 use the following URL pattern by default:

Old URL Pattern

<protocol>://<domain>/<contextpath>/<controller>/<containerpath>/<action>

The request parsing system will recognize both the older and new URL patterns, treating them as synonyms. For example, the following URLs are identical requests to the server: each URL will take you to the same page.

You can set the server to use the old URL pattern if you prefer. Go to Admin > Site > Site Console and click Site Settings. Locate the property Use "path first" urls. A checkmark next to this property tells the server to use the new URL pattern. No checkmark tells the server to use the older URL pattern. Note that servers installed before version 16.1 will continue to use the old URL pattern, unless an admin explicitly turns on the 'path first' property.

In some cases, the server will attempt to fix mis-constructed URLs. For example, if the server receives the following URL which mistakening refers to two different controllers:

http://<server>/<controllerA>/PATH/<controllerB>-<action>.view

then the server will redirect to following:

http://<server>/PATH/<controllerB>-<action>.view

Folder/Container-Relative Links

The new URL pattern supports folder-relative links in wikis and static files. For example, a static HTML page in a module can use the following to link to the default page for the current folder/container.

<a href="./project-begin.view">Home Page</a>

Build URLs Using the LabKey API

You can build URLs using the LABKEY.ActionURL.buildURL() API.

Note that URLs built on this API are not guaranteed to be backward compatible indefinitely.

Example 1: Show the source for this doc page:

window.location = LABKEY.ActionURL.buildURL("wiki", "source", LABKEY.ActionURL.getContainer(), {name: 'url'});

The above builds the URL:

https://www.labkey.org/Documentation/wiki-source.view?name=url

Example 2: Navigate the browser to the study controller's begin action in the current container:

window.location = LABKEY.ActionURL.buildURL("study", "begin");

Example 3: Navigate the browser to the study controller's begin action in the folder '/myproject/mystudyfolder':

window.location = LABKEY.ActionURL.buildURL("study", "begin", "/myproject/mystudyfolder");

URL Parameters

LabKey URLs can also include additional parameters that provide additional instructions to an action.

Filter Parameters

Filter parameters can be included in a URL to control how a query is displayed. See Filter Data for syntax and examples.

Variable values for some filtering parameters are supported in the URL (not all of which are supported using the filter UI). For example:

  • Current User: Using the "~me~" value for a filter (including the tildes) on a table using the core.Users values will substitute the current logged in user's username (or the user being impersonated by an admin). This is useful for showing a page with only items assigned to the viewing user, for instance, as shown here.
  • Relative Dates: Filtering a date column using a number (positive or negative) with "d" will give a date the specified number of days before or after the current date. For example, the URL shown in the following screencap contains the fragment "Created~dategt=-2d" which filters the Created column to show dates greater than two days ago.

Return URL (returnUrl)

Some actions accept a returnUrl parameter. This parameter allows you to tell the action where to forward the user after it is finished.

Some parameters are listed on the Web Part Configuration Properties page.

URL parameters can be written explicitly as part of an href link, or provided by LabKey APIs.

HREF Example:

Suppose you want to have a user input content to a list, then see a specific page after saving changes to the list.

The following snippet executes an insert action in a specified list ('queryName=lists&schemaName=MyListName'). After clicking the link, the user first sees the appropriate insert page for this list. Once the user has entered changes and pressed "Save," the user is delivered to the returnUrl page ('/MyProject/project-begin.view').

<a href="https://www.labkey.org/MyProject/query-insertQueryRow.view?queryName=lists&
schemaName=MyListName&returnUrl=/project/MyProject/begin.view"
>
Click here to request specimens</a>

returnUrl Example:

This sample navigates to the list controller's insert action, passing a returnUrl parameter that points back to the current page:

window.location = LABKEY.ActionURL.buildURL(
"query",
"insertQueryRow",
LABKEY.ActionURL.getContainer(),
{schemaName: "lists",
queryName: "MyListName",
returnUrl: window.location}
);

Other API Examples:

A more complex example of using URL parameters via the LabKey API can be found in the following topic:

  • Create an R Histogram - This step in the JavaScript API Tutorial creates a report in a LABKEY.WebPart by passing URL parameters to R.

Related Topics




URL Actions


Customize URLs for actions

You can use a custom URL for an action to redirect a user to a custom page when the user executes the action. You can customize actions that lead to insert, update, grid and details views. To set these URLs, add metadata XML to the table. An example of overriding the updateUrl on a DbUserSchema table:

<table tableName="testtable" tableDbType="TABLE">
<updateUrl>/mycontroller/foo.view?rowid=${rowid}</updateUrl>
</table>

updateUrls and tableUrls support a substitution syntax that embeds the value of one of the data row's columns into the URL, as shown above. If a column cannot be resolved, the URL will be ignored. For more information, see the documentation for ColumnType.url

Available options:

  • insertUrl - used to control the target of the Insert New (single row) button
  • updateUrl - used to control the target of the update link
  • deleteUrl - used to control the target of the Delete button
  • importUrl - used to control the target of the Import Data (bulk entry) button
  • gridUrl - used to control the default grid view of a table
  • tableUrl - used to control the target of the details link

Turn off default URL actions

insertUrl, updateUrl, tableUrl, deleteUrl, and importUrl may be set to a blank value to turn off the corresponding UI for a table.

For example:

<insertUrl />

This is handy if you wish to disallow edits on a per-record basis, or you wish to enforce additional conditions on where/when/which users can edit records. Developers have found that it is easier to turn off insert/edit/delete privileges by default and only enable editing in particular cases. For example, you might wish to allow updates only if the record is in a particular quality control state, or if the user is part of a particular security group. Note that this only changes the user interface presented to users, it does not actually change a user's ability to submit via the API or go directly to the default URL.