In a module, the views directory holds user interface elements, like HTML pages, and associated web parts.

To make it easier for users to access our query results, we will provide an HTML view for a direct link. Otherwise, users need to access the query schema to find it. You can do this in a wiki page, but that must be created on the server, and our goal is to provide everything in the module itself. Instead we will create an HTML view and an associated web part.

Add an HTML Page

Under the views/ directory, create a new file named reportdemo.html, and enter the following HTML:

<a id="pep-report-link"
Peptides With Counts Report</a>

Note that .html view files must not contain spaces in the file names. The view servlet expects that action names do not contain spaces.

Token Replacement: contextPath and containerPath

Note the use of the <%=contextPath%> and <%=containerPath%> tokens in the URL's href attribute. Since the href in this case needs to refer to an action in another controller, we can't use a simple relative URL, as it would refer to another action in the same controller. Instead, these tokens will be replaced with the server's context path and the current container path respectively.

Token replacement/expansion is applied to html files before they are rendered in the browser. Available tokens include:

  • contextPath - The token "<%=contextPath%>" will expand to the context root of the labkey server (e.g. "/labkey")
  • containerPath - The token "<%=containerPath%>" will expand to the current container (eg. "/MyProject/MyFolder"). Note that the containerPath token always begins with a slash, so you don't need to put a slash between the controller name and this token. If you do, it will still work, as the server automatically ignores double-slashes.
  • webpartContext - The token <%=webpartContext%> is replaced by a JSON object of the form:
wrapperDivId: <String: the unique generated div id for the webpart>,
id: <Number: webpart rowid>,
properties: <JSON: additional properties set on the webpart>

Web resources such as images, javascript, html files can be placed in the /web directory in the root of the module. To reference an image from one of the views pages, use a url such as:

<img src="<%=contextPath%>/my-image.png" />

Define a View Wrapper

This file has the same base-name as the HTML file, "reportdemo", but with an extension of ".view.xml". In this case, the file should be called reportdemo.view.xml, and it should contain the following:

<view xmlns=""
frame="none" title="Report Demo">

Define a Web Part

To allow this view to be visible inside a web part create our final file, the web part definition. Create a file in the views/ directory called reportdemo.webpart.xml and enter the following content:

<webpart xmlns="" title="Report Demo">
<view name="reportdemo"/>

After creating this file, you should now be able to refresh the portal page in your folder and see the "Report Demo" web part in the list of available web parts. Add it to the page, and it should display the contents of the reportdemo.html view, which contains links to take users directly to your module-defined queries and reports.

Your module directory structure and contents should now look like this:

reportDemo │ │ build.gradle └───resources    ├───queries    │ └───ms2    │ │ PeptideCounts.sql    │ │ PeptidesWithCounts.sql    │ │    │ └───Peptides    │ High Prob Matches.qview.xml    │    ├───reports    │ └───schemas    │ └───ms2    │ └───PeptidesWithCounts    │ Histogram.r    │    └───views        reportdemo.html        reportdemo.view.xml        reportdemo.webpart.xml

Set Required Permissions

You might also want to require specific permissions to see this view. That is easily added to the reportdemo.view.xml file like this:

<view xmlns="" title="Report Demo">
<permission name="read"/>

You may add other permission elements, and they will all be combined together, requiring all permissions listed. If all you want to do is require that the user is signed in, you can use the value of "login" in the name attribute.

The XSD for this meta-data file is view.xsd in the schemas/ directory of the project. The LabKey XML Schema Reference provides an easy way to navigate the documentation for view.xsd.


You have completed our tutorial for learning to create and use file-based modules to present customized content to your users.

Related Topics

Previous Step


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all