Modules: Folder Types: /home/

Modules: Folder Types

LabKey Server includes a number of built-in folder types, which define the enabled modules and the location of web parts in the folder. Built-in folder types include study, assay, flow, and others, each of which combine different default tools and webparts for different workflows and analyses.

Advanced users can define custom folder types in an XML format for easy reuse. This document explains how to define a custom folder type in your LabKey Server module. A folder type can be thought of as a template for the layout of the folder. The folder type specifies the tabs, webparts and active modules that are initially enabled in that folder.

Each folder type can provide the following:

The name of the folder type.
Description of the folder type.
A list of tabs (provide a single tab for a non-tabbed folder).
A list of the modules enabled by default for this folder.
Whether the menu bar is enabled by default. If this is true, when the folderType is activated in a project (but not a subfolder), the menu bar will be enabled.

Per tab, the following can be set:

The name and caption for the tab.
An ordered list of 'required webparts'. These webparts cannot be removed.
An ordered list of 'preferred webparts'. The webparts can be removed.
A list of permissions required for this tab to be visible (ie. READ, INSERT, UPDATE, DELETE, ADMIN)
A list of selectors. These selectors are used to test whether this tab should be highlighted as the active tab or not. Selectors are described in greater detail below.

Define a Custom Folder Type

Module Location

The easiest way to define a custom folder type is via a module, which is just a directory containing various kinds of resource files. Modules can be placed in the standard modules/ directory, or in the externalModules/ directory. By default, the externalModules/ directory is a peer to the modules/ directory.

To tell LabKey Server to look for external modules in a different directory, simply add the following to your VM parameters:

-Dlabkey.externalModulesDir="C:/externalModules"

This will cause the server to look in C:/externalModules for module files in addition to the normal modules/ directory under the web application.

Module Directory Structure

Create a directory structure like the following, replacing 'MyModule' with the name of your module. Within the folderTypes directory, any number of XML files defining new folder types can be provided.

MyModule
  └───resources
       └───folderTypes

Definition file name and location

Custom folder types are defined via XML files in the folderTypes directory. Folder type definition files can have any name, but must end with a ".foldertype.xml" extension. For example, the following file structure is valid:

MyModule
  └───resources
        └───folderTypes
               myType1.foldertype.xml
               myType2.foldertype.xml
               myType3.foldertype.xml

Example #1

The full XML schema (XSD) for folder type XML is documented and available for download. However, the complexity of XML schema files means it is often simpler to start from an example. The following XML defines a simple folder type:

<folderType xmlns="http://labkey.org/data/xml/folderType">
    <name>My XML-defined Folder Type</name>
    <description>A demonstration of defining a folder type in an XML file</description>
    <requiredWebParts>
        <webPart>
            <name>Query</name>
            <location>body</location>
            <property name="title" value="A customized web part" />
            <property name="schemaName" value="study" />
            <property name="queryName" value="SpecimenDetail" />
        </webPart>
        <webPart>
            <name>Data Pipeline</name>
            <location>body</location>
        </webPart>
        <webPart>
            <name>Experiment Runs</name>
            <location>body</location>
        </webPart>
    </requiredWebParts>
    <preferredWebParts>
        <webPart>
            <name>Sample Sets</name>
            <location>body</location>
        </webPart>
        <webPart>
            <name>Run Groups</name>
            <location>right</location>
        </webPart>
    </preferredWebParts>
    <modules>
        <moduleName>Experiment</moduleName>
        <moduleName>Pipeline</moduleName>
    </modules>
    <defaultModule>Experiment</defaultModule>
</folderType>

Valid webpart names

Each <webPart> element must contain a <name> element. The example above specified that a query webpart is required via the following XML:

<requiredWebParts>
        <webPart>
            <name>Query</name>

Valid values for the name element can be found by looking at the 'Add Webpart' dropdown in any LabKey Server portal page. Note that you may need to enable additional LabKey modules via the 'customize folder' administrative option to see all available webpart names.

Valid module names

The modules and defaultModules sections define which modules are active in the custom folder type. From the example above:

<modules>
        <moduleName>Experiment</moduleName>
        <moduleName>Pipeline</moduleName>
    </modules>
    <defaultModule>Experiment</defaultModule>

Valid module names can be found by navigating through the administrative user interface to create a new LabKey Server folder, or by selecting 'customize folder' for any existing folder. The 'customize folder' user interface includes a list of valid module names on the right-hand side.

Example #2 - Tabs

This is another example of an XML file defining a folder type:

<folderType xmlns="http://labkey.org/data/xml/folderType" xmlns:mp="http://labkey.org/moduleProperties/xml/">
    <name>Laboratory Folder</name>
    <description>The default folder layout for basic lab management</description>
    <folderTabs>
        <folderTab>
            <name>overview</name>
            <caption>Overview</caption>
            <selectors>
            </selectors>
            <requiredWebParts>
            </requiredWebParts>
            <preferredWebParts>
                <webPart>
                    <name>Laboratory Home</name>
                    <location>body</location>
                </webPart>
                <webPart>
                    <name>Lab Tools</name>
                    <location>right</location>
                </webPart>
            </preferredWebParts>
        </folderTab>
        <folderTab>
            <name>workbooks</name>
            <caption>Workbooks</caption>
            <selectors>

            </selectors>
            <requiredWebParts>
            </requiredWebParts>
            <preferredWebParts>
                <webPart>
                    <name>Workbooks</name>
                    <location>body</location>
                </webPart>
                <webPart>
                    <name>Lab Tools</name>
                    <location>right</location>
                </webPart>
            </preferredWebParts>
        </folderTab>
        <folderTab>
            <name>data</name>
            <caption>Data</caption>
            <selectors>
                <selector>
                    <controller>assay</controller>
                </selector>
                <selector>
                    <view>importData</view>
                </selector>
                <selector>
                    <view>executeQuery</view>
                </selector>
            </selectors>
            <requiredWebParts>
            </requiredWebParts>
            <preferredWebParts>
                <webPart>
                    <name>Data Views</name>
                    <location>body</location>
                </webPart>
                <webPart>
                    <name>Lab Tools</name>
                    <location>right</location>
                </webPart>
            </preferredWebParts>
        </folderTab>
        <folderTab>
            <name>settings</name>
            <caption>Settings</caption>
            <selectors>
                <selector>
                    <view>labSettings</view>
                </selector>
            </selectors>
            <requiredWebParts>
            </requiredWebParts>
            <preferredWebParts>
                <webPart>
                    <name>Lab Settings</name>
                    <location>body</location>
                </webPart>
                <webPart>
                    <name>Lab Tools</name>
                    <location>right</location>
                </webPart>
            </preferredWebParts>
	    <permissions>
                <permission>org.labkey.api.security.permissions.AdminPermission</permission> 
            </permissions>
        </folderTab>
    </folderTabs>
    <modules>
        <moduleName>Laboratory</moduleName>
    </modules>
    <menubarEnabled>true</menubarEnabled>
</folderType>

Tabbed Folders - The Active Tab

When creating a tabbed folder type, it is important to understand how the active tab is determined. The active tab is determined by the following checks, in order:

If there is 'pageId' param on the URL that matches a tab's name, this tab is selected. This most commonly occurs after directly clicking a tab.
If no URL param is present, the tabs are iterated from left to right, checking the selectors provided by each tab. If any one of the selectors from a tab matches, that tab is selected. The first tab with a matching selector is used, even if more than 1 tab would have a match.
If none of the above are true, the left-most tab is selected

Each tab is able to provide any number of 'selectors'. These selectors are used to determine whether this tab should be marked active (ie. highlighted) or not. The currently supported selector types are:

View: This string will be matched against the viewName from the current URL (ie. 'page', from the current URL). If they are equal, the tab will be selected.
Controller: This string will be matched against the controller from the current URL (ie. 'wiki', from the current URL). If they are equal, the tab will be selected.
Regex: This is a regular expression that must match against the full URL. If it matches against the entire URL, the tab will be selected.

If a tab provides multiple selectors, only 1 of these selectors needs to match. If multiple tabs would have matched to the URL, the left-most tab (ie. the first matching tab encountered) will be selected.

LabKey Support

LabKey Support