SND Module: UI Development Environment
For developing client-side code for the SND module, using ReactJS, Redux and TypeScript, it is recommended to set up the npm development environment. This allows the UI source files to be automatically rebuilt by Webpack when changes are detected and the updated ReactJS components to be hot swapped into the running web application. This makes it possible to see your changes applied without having to rebuild and refresh, preserving the context of your application.
Steps to set up:
- Install Node.js and npm. You will want this to match the versions in gradle.properties at the top level of your LabKey project. See the npmVersion and nodeVersion fields in the property file. These are the versions the deployed application will be built and packaged with so it is important to use those versions locally while developing.
- If the install doesn't add npm to your PATH, add it. Verify npm is installed and is the correct version by running 'npm -v' in your command line.
- Start your development machine in IntelliJ in debug mode.
- In the command line on your dev machine, go to the source directory of the SND module.
- Execute the command, npm start. This will run the webpack build then start monitoring for any changes in the source code.
- In your web browser navigate to the development web address for the SND module,
- <labkey context>/<folder>/snd-appDev.view#/
Technology Stack
npm: Package manager for JavaScript. Allows for easier installation and maintenance of JavaScript libraries, frameworks and tools like React.js. Uses package.json to manage dependencies and define commands. Chosen for its broad industry usage and large package registry (477,000).
Webpack: Module bundler and processor. Organizes, bundles and processes client-side code. Generally making fewer and smaller bundles to be loaded from the server. Creates a dependency graph to control the order of loading dependencies. Loaders allow different types of files to be bundled (.js, .html, .css, .jsx, .tsx). Good for single page apps and works well with ReactJS and TypeScript.
Babel: Compiler for next generation JavaScript. Converts next generation JavaScript to the target version of choice. Allows for usage of more modern syntax and paradigms, while maintaining backward compatibility. For our case, we're transpiling es6 features like arrow functions, JS classes, this scoping and promises back to es5.
TypeScript: Superset of JS that allows static typing. Supports interfaces and strong type checking similar to Java, but allows dynamic types like normal JS as well. Helps produce more readable and maintainable code. Transpiles to ES6 and JSX.
ReactJS: Create responsive, stateful UIs. Modular components that will update only their own html when their state changes without having to reload the page.
Redux: Global state storage. A data store we use for things like storing rows in a grid which we can then filter, sort, etc. A single store, but has tree of objects that must be updated through defined actions. Works well with ReactJS.
Query Backed Snapshots (Experimental Feature)
This feature is experimental and needs to be enabled:
- Go to > Site > Admin Console > Experimental Features
- Check the box for "Allow query based dataset snapshots"
Source Query
The Snapshot feature is only available within the study schema, so the source query for the snapshot must be created in this schema.
- Go to > Developer Links > Schema Browser
- In the study schema, choose any table or query then click Create New Query at the top of the schema browser.
- Enter a name for the source query. This should not be the name of the dataset you're going to create but maybe something related to that name, ex. weightSource.
- Next, write, test and save the source query that will be the basis for the query backed snapshot.
- This source query is an opportunity to customize the data being supplied for the dataset.
- You can use the recently created SND.Categories schema or any other schema for the query.
Required Columns
In order to fit into the study schema as a dataset the query does have some required columns.
- _key: this is the pk of the dataset. If using the SND.Categories or SND.Packages schema this will likely be the lsid column, but this must be specifically defined in the query. See example below.
- participantid: Id of the animal. May need to define this in the query from SubjectId.
- date: All datasets require a date column.
- qcstate: SND qcstate can be used here. Can be pulled directly from SND.Categories or SND.Packages tables.
- lsid: This can be pulled directly from SND.Categories or SND.Packages tables.
Example:
SELECT
LSID as _key,
SubjectId as participantid,
*
FROM SND.Categories.Weight
Create Snapshot
The next step is to create the snapshot which creates the query backed dataset that will fit into the study and EHR.
- After you've saved your source query, navigate to the results grid of the query.
- Select > Create Query Snapshot.
- Name the snapshot, the name of the dataset that will be integrated into the study and EHR. Ex. weight or vitals
- Check Query Backed Dataset (only available if experimental feature is turned on)
- Click Create Snapshot
If there are missing required columns, you will be informed at this point. You will need to update the source query and try to make the query based snapshot again following the steps in this section.
Testing and Performance
At this point the dataset is created. This is essentially a mock dataset that just passes through the results of the source query. If the source query is not performant, then the dataset will have the same issues. Queries or reports of varying use cases and complexity could result in different performance, so it's important to test across the usages of that dataset and if necessary optimize the source query.
Related Topics
