In a module, the views
directory holds user interface elements, like HTML pages and associated web parts that help your users view your resources.
In this topic, we will provide an HTML view making it easier for our users to see the custom queries and reports created in the tutorial earlier
. Otherwise, users would need to access the query schema to find them. You could provide this in a wiki page created on the server, but our goal is to provide everything in the module itself. Here we will create an HTML view and an associated web part.
Add an HTML Page
Under the views/ directory, create a new file named dashboardDemo.html
, and enter the following HTML:
Dashboard of Consolidated Data</a>
While queries and report names may contain spaces, note that .html view files must not
contain spaces. The view servlet expects that action names do not contain spaces.
View Page via URL
You can directly access module resources using the URL. The pattern to directly access module based resources is as follows:
The action is the combination of your resource name and an action suffix, typically ".view" or ".post". For example, if you installed the example study on a localhost in a "Tutorials/HIV Study" folder, you can directly access the Dashboard Demo HTML page here:
Learn more in this topic: LabKey URLs
Token Replacement: contextPath and containerPath
In the HTML you pasted, notice the use of the <%=contextPath%> and <%=containerPath%> tokens in the URL's href attribute. Since the href in this case needs to be valid in various locations, we don't want to use a fixed path. 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>
<img src="<%=contextPath%>/my-image.png" />
Define a View Wrapper
This file has the same base-name as the HTML file, "dashboardDemo", but with an extension of ".view.xml". In this case, the file should be called dashboard.view.xml
, and it should contain the following:
Frames and Templates for Views
You can also customize how the view will be presented using the frame
The view frame
The view template
- app: Hide the default LabKey header for this view
template = "app">
Learn more in the XML Schema docs
Define a Web Part
To allow this view to be added as a web part, create our final file, the web part definition. Create a file in the views/ directory called dashboardDemo.webpart.xml
and enter the following content, referring to the root name of the file:
<webpart xmlns="http://labkey.org/data/xml/webpart" title="Data Dashboard">
Your directory structure and contents should now look like this:
│ │ BMI.sql
│ │ BMI.query.xml
│ │ MasterDashboard.sql
│ DRV Regimen Results.qview.xml
│ │ LymphCD4.r
After creating these files, you refresh the portal page in your folder, enter > Page Admin Mode
and see the Data Dashboard
web part as an option to add on the left side of the page. Add it to the page, and it will display the contents of the dashboardDemo.html view. In this case, a direct link to your module-defined query.
The user can access the Histogram report via the (Charts/Reports)
menu, or you can make it even easier with another direct link as described in the next section.
Add More Content to the Web Part
Now that you have established the user interface, you can directly modify the HTML file to change what the user can use on existing web parts.
for editing and add this below the existing content:
On the page where you have your Data Dashboard web part, simply refresh the page, and you'll see a new Hemoglobin Histogram
link directly to your R report.
Set Required Permissions
You might also want to require specific permissions to see this view. That is easily added to the dashboardDemo.view.xml
file like this:
<view xmlns="http://labkey.org/data/xml/view" title="Dashboard Demo">
In this case, once you have added this permission element, only admins will be able to see the dashboard.
You may add other permission elements, and they will all be combined together, requiring all permissions listed. Options for the name attribute include but are not limited to "read", "insert", and "admin". 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.
If you are interested in a set of similar module resources for use with LabKey's ms2 module, see this topic: MS2: File-based Module Resources