— This feature is available with the Professional and Enterprise Editions of LabKey Server. It requires the addition of the moduleEditor
module to your distribution. Learn more
or contact LabKey
Edit module-based resources directly within the user interface of a LabKey Server running in development mode
. With the moduleEditor
module enabled, you can edit many module-based resources without stopping and starting your server.
Using this feature on a shared development server lets developers iterate on a module in an environment that may not be convenient to configure on an individual developer's machine, and is well-suited for a shared pre-production testing deployment. It requires that the module's source root is available to the server, in addition to having its built .module deployed. It streamlines the development and maintenance of module-based resources by bypassing the need to edit offline and reload to see each change.
With Module Editing enabled, two new capabilities are unlocked:
- A graphical Module Editor interface makes it easy to find and edit many module-based resources.
- Developers can edit some module-based resources in the same way as they would edit them if they had been defined in the user interface. For instance, both SQL Queries and R Reports become editable regardless of where they were defined.
Set Up for Module Editing
1. Prerequisites: To be able to edit module-based resources "live":
- LabKey Server must be running in Development mode.
- The ModuleEditor module must be deployed on your server.
- You must have the necessary permissions to edit the same resources if they were not module-based. For example:
- SQL Queries: "Editor" or higher
- R Reports: "Platform Developer" or "Trusted Analyst"
2. Create the module's source root by copying it to the server, checking out from source control, or building it manually, as you would on a developer machine
. You cannot
edit it if you load it through the UI
If you would like an example module to help you get started, you can use this one:
Rename the archive to end in .zip, unzip it, then place the "aloadingdemo" folder in your development machine enlistment's "server/modules". If this were not a purely file-based module, you would need to build it as usual
3. Deploy it on the server by running:
4. Navigate to the folder where you want to be able to use your module-based resources. If you are using our example "aloadingdemo.module" which contains a few simple queries and reports, first install the example study you can download from this page:
5. In your working folder, enable your module:
- Select (Admin) > Folder > Management.
- Click the Folder Type tab.
- Check the box for your module, and make sure the ModuleEditor module is also enabled in the folder.
- Click Update Folder.
Open the module editor by selecting (Admin) > Developer Links > Module Editor
. You'll see the list of modules in the left hand tree panel, each represented by a folder.
Expand the module folders to see the module directory structure and resources inside. You can use the Show Module
dropdown to focus on a single module.
Click any folder or resource to open it for editing in the right hand panel. Your selection is shown in darker type.
In the case of resources like the SQL query shown above, you can directly edit the query text in the window and click Save Changes
. You could also Move File
or Delete File
Edit Module Structure/Add Content
If you select a folder within the module tree, you have options like creating new subfolders, adding files, and moving or deleting the entire directory.
In the above example, we've selected the queries folder. Adding a new subfolder would give us a place to define queries on other schemas (so far there are only queries on the study schema in this module).
Editing Scope and Limitations
You can edit a wide variety of module based resources, including but not limited to:
- SQL Queries
- Wikis and other HTML pages
- XML resources like views, web parts, query metadata
However, you can only edit content that can be dynamically loaded. Files like the module.properties for a module cannot be editing in this interface.
You cannot delete, edit, rename, or upload content directly within the top level of a module.
Edit SQL Queries
SQL queries contained in your module can be edited directly in the module editor above, or also via the query browser, as long as the server has access to the module's source. To be able to edit, you need "Editor" or "Trusted Analyst" permissions. You must also first enable both the ModuleEditor
module and the module containing the resources via the (Admin) > Folder > Management > Folder Type
- Select (Admin) > Go To Module > Query.
- Click the schema where your query is defined.
- Click the name of the module-defined query. If you are using our example, you can use the study > Master Dashboard query.
- In the upper right, you will see a note about where the module is defined, plus options for editing:
Click Edit Source
to see the SQL source for your query in the same query editor as when you create a new query. A note will remind you where the query is defined and that changing a module-based query in this folder will also change it in any other folder that uses the same module.
From this page you can:
- Save & Finish: Save changes and exit the edit interface
- Save: Save, but keep editing
- Execute Query: See your work in progress
- Edit Properties
- Edit Metadata
- Help: See keyboard shortcuts and a link to the SQL Reference.
Changes to will be saved to the module.
Click Edit Properties
to adjust the name, description, availability in child folders, and whether the query is hidden. As with editing of source, be aware that your changes made to the module-resource here will impact all users on the site.
Click Edit Metadata
to adjust the fields and properties that comprise your query using the field editor
. You cannot change the names of fields via this interface, but can set properties, adjust lookups, etc.
Edit R Reports
R reports created in the UI using the R report builder
can already be edited. With the ModuleEditor module and the module containing the reports enabled, you can now also edit module-based R reports.
Open your R report for editing. If you are using our example module, open the "LymphCD4" report on the Clinical and Assay Data tab. The R Report Builder
allows you to edit the report on the Source
tab. A message in the UI will alert you that you are editing a module based resource and any changes you make here will be reflected in all other folders where this module is in use.
When saved, your report changes will be stored in the original module resources.
Moving Edited Resources to Production
The changes you make to module-based queries and reports via the UI are stored in the root of the module so that you can move the final module to production when ready.
Package the module from the development deployment and redeploy on your production server. Learn how in this topic: Deploy Modules to a Production Server