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:

<p>
<a id="dash-report-link"
href="<%=contextPath%><%=containerPath%>/query-executeQuery.view?schemaName=study&query.queryName=MasterDashboard">
Dashboard of Consolidated Data</a>
</p>

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:

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

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:

http://localhost:8080/labkey/Tutorials/HIV%20Study/filebaseddemo-dashboardDemo.view?

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>
    }
Web resources such as images, javascript, and other 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, "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:

<view xmlns="http://labkey.org/data/xml/view"
title="Data Dashboard">
</view>

Frames and Templates for Views

You can also customize how the view will be presented using the frame and template attributes. The view frame can be:

  • portal
  • title
  • dialog
  • div
  • left_navigation
  • none
The view template can be:
  • body
  • home
  • none
  • print
  • dialog
  • wizard
  • app: Hide the default LabKey header for this view
For example:
<view xmlns="http://labkey.org/data/xml/view"
title="Data Dashboard"
frame="none"
template = "app">
</view>

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">
<view name="dashboardDemo"/>
</webpart>

Your directory structure and contents should now look like this:

fileBasedDemo │ module.properties └───resources    ├───queries    │ └───study    │ │ BMI.sql    │ │ BMI.query.xml    │ │ MasterDashboard.sql    │ │    │ └───LabResults    │ DRV Regimen Results.qview.xml    │    ├───reports    │ └───schemas    │ └───study    │ └───LabResults    │ │ LymphCD4.r    │ └───MasterDashboard    │ HgbHistogram.r    │    └───views        dashboardDemo.html        dashboardDemo.view.xml        dashboardDemo.webpart.xml

View Results

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.

Reopen dashboardDemo.html for editing and add this below the existing content:

<p>
<a id="dash-report-link"
href="<%=contextPath%><%=containerPath%>/query-executeQuery.view?schemaName=study&query.queryName=MasterDashboard&query.reportId=module%3Afilebaseddemo%2Freports%2Fschemas%2Fstudy%2FMaster%20Dashboard%2FHgbHistogram.r">
Hemoglobin Histogram</a>
</p>

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">
<permissions>
<permission name="admin"/>
</permissions>
</view>

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.

Congratulations

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

Related Topics

Tutorial Steps

Previous Step

Discussion

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand all collapse all