Modules: Folder Types

 2024-04-18
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 web parts 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, web parts and active modules that are initially enabled in that folder.

Folder Type Options

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 web parts'. These web parts cannot be removed.
  • An ordered list of 'preferred web parts'. The web parts 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 server/modules/ directory.

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

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 - Basic

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 Types</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 Web Part Names

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

<requiredWebParts>
        <webPart>
            <name>Query</name>
Valid values for the name element can be found by looking at the 'Select Web Part' dropdown visible when in page admin mode. Note that you may need to enable additional LabKey modules via the 'customize folder' administrative option to see all available web part 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 - Tabbed Folder

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

<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 name="org.labkey.api.security.permissions.AdminPermission"/> 
            </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:

  1. 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.
  2. 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.
  3. 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:
  1. 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.
  2. 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.
  3. 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.

Related Topics