The LabKey Server source code includes a
'demo' module (the Demo Module) for getting started on building your own LabKey Server module using Java. The Demo module demonstrates all the basic concepts you need to understand to extend LabKey Server with your own module. You can use the Demo module as a template for building your own module from scratch. Or, to create your own module from scratch, see the help topic on
creating a new module.
Set Up
Before you get started, you need to set up your development environment to build the source code. Learn how in this topic:
Set Up a Development Machine.
Next, clone the 'tutorialModules' into your enlistment. In the $LABKEY_HOME/server/modules folder:
In your IDE, you may need to
Reload gradle projects. Then rebuild your server with the additional module(s).
About the Demo Module
The Demo module is a simple sample module that displays names and ages for some number of individuals. Its purpose is to demonstrate some of the basic data display and manipulation functionality available in LabKey Server.
You can enable the Demo module in a project or folder to try it out:
- Select (Admin) > Folder > Management.
- Click the Folder Type tab.
- Enable the Demo module using the checkbox.
- Add the Demo Summary web part to your project or folder. A web part is an optional component that can provide a summary of the data contained in your module.
Click the
Add Person button to add names and ages. Once you have a list of individuals, you can click on a column heading to sort the list by that column, in ascending or descending order. You can click the
Filter icon next to any column heading to filter the list on the criteria you specify. Click
Bulk Update to update multiple records at once, and
Delete to delete a record.
A Tour of the Demo Module
In the following sections, we'll examine the different files and classes that make up the Demo module.
Take a look at the source code at: <labkey-home>\server\modules. The modules\ directory contains the source code for all of the modules, each sub-directory is an individual module.
The LabKey Server web application uses a model-view-controller (MVC) architecture based on Spring.
You may also want to look at the database component of the Demo module. The Person table stores data for the Demo module.
The Object Model (Person Class)
The Person class comprises the object model for the Demo module. The Person class can be found in the org.labkey.demo.model package (and, correspondingly, in the <labkey-home>\server\modules\demo\src\org\labkey\demo\model directory). It provides methods for setting and retrieving Person data from the Person table. Note that the Person class does not retrieve or save data to the database itself, but only stores in memory data that is to be saved or has been retrieved. The Person class extends the Entity class, which contains general methods for working with objects that are stored as rows in a table in the database.
The Controller File (DemoController Class)
Modules have one or more controller classes, which handle the flow of navigation through the UI for the module. A controller class manages the logic behind rendering the HTML on a page within the module, submitting form data via both GET and POST methods, handling input errors, and navigating from one action to the next.
A Controller class is a Java class that defines individual action classes, all of which are auto-registered with the controller's ActionResolver. Action classes can also be defined outside the controller, in which case they must be registered with the ActionResolver. Action classes are annotated to declare permissions requirements.
The controller for the Demo module, DemoController.java, is located in the org.labkey.demo package (that is, in <labkey-home>\server\modules\demo\src\org\labkey\demo). If you take a look at some of the action classes in the DemoController class, you can see how the controller manages the user interface actions for the module. For example, the BeginAction in the DemoController displays data in a grid format. It doesn't write out the HTML directly, but instead calls other methods that handle that task. The InsertAction class displays a form for inserting new Person data when GET is used and calls the code that handles the database insert operation when POST is used.
A module's controller class should extend the SpringActionController class, Labkey's implementation of the Spring Controller class.
The primary controller for a module is typically named
<module-name>Controller.
The Module View
The module controller renders the module user interface and also handles input from that user interface. Although you can write all of the necessary HTML from within the controller, we recommend that you separate out the user interface from the controller in most cases and use the LabKey Server rendering code to display blocks of HTML. LabKey Server primarily uses JSP files templates to render the module interface.
The bulkUpdate.jsp FileThe bulkUpdate.jsp file displays an HTML form that users can use to update more than one row of the Person table at a time.
BulkUpdateAction renders the bulkUpdate.jsp file and accepts posts from that HTML form. The data submitted by the user is passed to handlePost() as values on an object of type BulkUpdateForm. The form values are accessible via getters and setters on the BulkUpdateForm class that are named to correspond to the inputs on the HTML form.
The bulkUpdate.jsp file provides one example of how you can create a user interface to your data within your module. Keep in mind that you can take advantage of a lot of the basic data functionality that is already built into LabKey Server, described elsewhere in this section, to make it easier to build your module. For example, the DataRegion class provides an easy-to-use data grid with built-in sorting and filtering.
The DemoWebPart ClassThe DemoWebPart class is located in the org.labkey.demo.view package. It comprises a simple web part for the demo module. This web part can be displayed only on the Portal page. It provides a summary of the data that's in the Demo module by rendering the demoWebPart.jsp file. An object of type ViewContext stores in-memory values that are also accessible to the JSP page as it is rendering.
The web part class is optional, although most modules have a corresponding web part.
The demoWebPart.jsp FileThe demoWebPart.jsp file displays Person data on an HTML page. The JSP retrieves data from the ViewContext object in order to render that data in HTML.
The Data Manager Class (DemoManager Class)
The data manager class contains the logic for operations that a module performs against the database, including retrieving, inserting, updating, and deleting data. It handles persistence and caching of objects stored in the database. Although database operations can be called from the controller, as a design principle we recommend separating this layer of implementation from the navigation-handling code.
The data manager class for the Demo module, the DemoManager class, is located in the org.labkey.demo package. Note that the DemoManager class makes calls to the LabKey Server table layer, rather than making direct calls to the database itself.
The Module Class (DemoModule Class)
The DemoModule class is located in the org.labkey.demo package. It extends the DefaultModule class, which is an implementation of the Module interface. The Module interface provides generic functionality for all modules in LabKey Server and manages how the module plugs into the LabKey Server framework and how it is versioned.
The only requirement for a module is that it implement the Module interface. However, most modules have additional classes like those seen in the Demo module.
The Schema Class (DemoSchema Class)
The DemoSchema class is located in the org.labkey.demo package. It provides methods for accessing the schema of the Person table associated with the Demo module. This class abstracts schema information for this table, so that the schema can be changed in just one place in the code.
Database Scripts
The <labkey-home>\server\modules\demo\webapp\demo\scripts directory contains two subdirectories, one for PostgreSQL and one for Microsoft SQL Server. These directories contain functionally equivalent scripts for creating the Person table on the respective database server.
Note that there are a set of standard columns that all database tables in LabKey Server must include. These are:
- _ts: the timestamp column
- RowId: an autogenerated integer field that serves as the primary key
- CreatedBy: a user id
- Created: a date/time column
- ModifiedBy: a user id
- Modified: a date/time column
- Owner: a user id
Additionally, the CREATE TABLE call also creates columns which are unique to the Person table, and adds the constraint which enforces the primary key.
