README

AICS LabKey React Components

This repo hosts React components created by AICS that are used in multiple LabKey modules.

Components

AicsBlockUi
AicsGrid
LabKeyOptionSelector

Usage

Install:

npm install @aics/aics-react-labkey --save

Import into JavaScript file (must have tooling such as Webpack/Babel set up):

import '@aics/aics-react-labkey/dist/styles.css';
import { AicsGrid, AicsBlockUi, LabKeyOptionSelector } from '@aics/aics-react-labkey';

LabKeyOptionSelector props

LabKeyOptionSelector wraps react-select, and renames the following props:

old name -> new name
name -> id
value -> selected
labelKey -> optionNameKey
valueKey -> optionIdKey
onChange -> onOptionSelection
multi -> multiSelect

LabKeyOptionSelector adds some additional props related to the Bootstrap Form Group that surrounds it, which can be seen in the Selector demo.

It will also forward any props you pass to it to the underlying react-select component, which means you can pass any of the possible props, keeping in mind the renamed ones above.

LabKeyOptionSelector Async Mode

LabKeyOptionSelector can be configured to run in "async" mode if the async prop is set to true. Look at LabKeyOptionSelectorDemo.jsx for an example of how this works.

In "async" mode, LabKeyOptionSelector will also use the following props:

loadOptions (required)
autoload
cache

These props get forwarded to the underlying react-select component. Look at the documentation for more information.

Additionally, the options prop is not used in "async" mode.

LabKeyOptionSelector Creatable Mode

LabKeyOptionSelector can also be configured to run in "creatable" mode if the creatable prop is set to true. "Creatable" mode can only be used if not in "async" mode, and vice versa.

You can find more information about "creatable" mode and additional props in the react-select documentation.

View Examples

Install dependencies:

npm install

Start up Webpack Dev Server:

npm run dev

Changes will be live-reloaded.

Examples of how to use these components can be found in the examples/ directory.

Test Local Changes

While developing this library, it is common to want to test your changes in other repos that use this library without publishing your changes. This can easily be accomplished with npm link.

In this repo, run:

npm link

In the repo that you want to test your changes in, run:

npm link @aics/aics-react-labkey

This will create an entry in node_modules in the second repo that is symlinked to your copy of this repo.

To remove the link, run:

npm unlink @aics/aics-react-labkey

You may need to update the css loader to resolve to this path ('../labkey-aics-react-components/dist/styles.css') as opposed to just /node_modules/

 {
     test: /\.css$/,
     include: [/node_modules/, path.resolve(__dirname, '../labkey-aics-react-components/dist/styles.css')],
     use: [
         'style-loader',
         'css-loader'
     ]
 }

You may need to add aliases for react and react-dom to the Webpack config in the project you are testing in, as these libraries are only peer dependencies in aics-react-labkey.

resolve: {
    alias: {
        react: path.resolve('./node_modules/react'),
        'react-dom': path.resolve('./node_modules/react-dom')
    }
}

Publishing Changes

Publishing can be accomplished via the master branch on Jenkins:

https://jenkins.corp.alleninstitute.org/job/node-packages/job/aics-react-labkey/.

Once changes are in master, click "Build with Parameters". Check PUBLISH to true and set VERSION_TO_INCREMENT to one of the three drop down values: "patch", "minor", "major". Look up npm semantic versioning for more information. Additionally, this will also create a version commit and tag in git, and will push these to origin.

Finally, click Build to initiate process.

Usage no npm install needed!