Module Properties

 2024-04-19
A module can define "administrator-settable" properties which can be set on a running server at (Admin) > Folder Management > Module Properties tab. Module properties can be scoped at different levels, from site-wide to applying only to a specific subfolder. Site-wide settings are overridden by project or folder settings. If a subfolder container doesn't have a value set for a given property, the module will look to the parent folder, and continue up the container tree until it finds a value or hits the root.

Define Module Properties

These "administrator-settable" properties are defined in your module at /resources/module.xml. When deployed, this file is copied to MODULE_ROOT/module.xml. Note: This module.xml file is not be confused with the identically-named file generated from the module.properties file, described here and deployed to MODULE_ROOT/config/module.xml.

Module properties support various input types:

  • Text field (Width can be specified.)
  • Checkboxes
  • Dropdowns (Either select from a set list, or a combination that allows either user input or a selection.)
    • Options can either be a static list set at startup, or dynamic at module properties page load.
    • The dynamic list can be container dependent.
    • Other than dynamic dropdowns, all functionality is available to file based modules.
  • Settings can be applied site-wide or scoped to the current project or folder.
  • Supports permissions to have different values for a given property in different folders.
  • Supports hover tooltips: the description can be set to display on the tab and in a hover-over tooltip.
  • Defines module-level dependencies on libraries and other resources.
  • Reference link | Example link
Note that module properties apply across the container, to all users. If you want to scope properties to specific users or groups, you'll need to use PropertyManager, which is the server-side way to store app, folder or folder-user specific properties. It should handle caching, querying the database once a day, and reloading the cache when the properties are updated. There is no API to query those values so you have to build that yourself.

Example module.xml

<module xmlns="http://labkey.org/moduleProperties/xml/">
    <properties>
        <propertyDescriptor name="TestProp1">
            <canSetPerContainer>false</canSetPerContainer>
        </propertyDescriptor>
        <propertyDescriptor name="TestProp2">
            <canSetPerContainer>true</canSetPerContainer>
            <defaultValue>DefaultValue</defaultValue>
            <editPermissions>
                <permission>UPDATE</permission>
            </editPermissions>
        </propertyDescriptor>
        <propertyDescriptor name="TestCheckbox">
            <inputType>checkbox</inputType>
        </propertyDescriptor>
        <propertyDescriptor name="TestSelect">
            <inputType>select</inputType>
            <options>
                <option display="display1" value="value1"/>
                <option display="display2" value="value2"/>
            </options>
        </propertyDescriptor>
        <propertyDescriptor name="TestCombo">
            <inputType>combo</inputType>
            <options>
                <option display="comboDisplay1" value="comboValue1"/>
                <option display="comboDisplay2" value="comboValue2"/>
            </options>
        </propertyDescriptor>
    </properties>
    <clientDependencies>
        <dependency path="/simpletest/testfile.js" />
    </clientDependencies>
    <requiredModuleContext>
        <requiredModule name="Core" />
    </requiredModuleContext>
</module>

Control Settings

A folder or project administrator can see and set module properties by opening the (Admin) > Folder > Management > Module Properties tab. This page shows all properties you can view or set.

If the property can have a separate value per folder, there will be a field for the current folder and each parent folder up to the site-level. If you do not have permission to edit the property in the other containers, the value will be shown as read-only. To see more detail about each property, hover over the question mark in the property name bar.

Get Properties in Module Code

To use the properties in your module code, use the following:

var somePropFoo = LABKEY.moduleContext.myModule.somePropFoo

If you want a defensive check that the module exists, use the following:

var getModuleProperty = function(moduleName, property) {
    var ctx = getModuleContext(moduleName);
    if (!ctx) {
        return null;
    }
    return ctx[property];
};

Related Topics