UI Modules and the FOLIO Platform
What is a UI Module?
A FOLIO UI Module is one piece of several modular pieces within a platform. It represents a vertical slice of the functionality that a Library will require from its ILS. As a software developer, it’s very easy to view your FOLIO App as THE entire app, but that is not the realistic view of things. Your FOLIO module will be served alongside other FOLIO modules and must be created in a way that is considerate of inter-module relationships and its functionality as part of the workflows, part of the platform. Now that we’ve said that, on to more good stuff!
What is Okapi (for frontend developers)
What Stripes Provides
Platform Provided Dependencies
These are dependencies that may or may not be used in your module, but are common within the platform. These are singleton dependencies, so its necessary that they’re only added to the bundle from one primary, dependent source (the platform!) They should be listed as both peerDependencies and devDependencies (for testing) in your ui-module’s package.json
React Router/React Router DOM
Provides our general routing infrastructure.
Form Library
Provides a consistent source of implementation for various form-related concerns such as validation and tracking a form state. As of Quesnelia release, there is still usage of redux-form and react-final-form within the system, but these projects have decreased in maintainer responsibility. react-hook-form is the recommended package for new form development - but it isn’t provided by the platform yet. Stay tuned!!
Date/Time Library
As of Quesnelia release, DayJS (source) is available from @folio/stripes/components as a pre-extended export. See Date/time utilities documentation for more information.
Data Fetching
For API calls, we provide ky, and react-query v3. A global react-query QueryClientProvider wraps the module container; modules must not implement their own. @folio/stripes/core exports useOkapiKy (source) and withOkapiKy (source) which decorate API requests with the options and headers necessary to interact with the API gateway, Okapi. Requests to non-FOLIO APIs should use ky or fetch.
Zustand
Zustand v4 is a global state management solution.
Development setup
Configure yarn to point to the dev repository:
$ yarn config set @folio:registry https://repository.folio.org/repository/npm-folioci/Create a simple yarn workspace.
Clone a platform as well as your ui-module code into the workspace.
Add your ui module to the platform’s
package.jsonandstripes.config.jsSet the okapi URL in
stripes.config.js.In the platform directory, run your project with
yarn stripes serve stripes.config.js
Development Setup Provides a more elaborate description of these steps.
Navigation/Routing
Settings
Fetching Data
What Stripes Provides
OkapiKy
React Query
Caching - Namespacing
Presenting Data
Stripes-components
Common Components
Panes
LayoutGrid
MCL
Form controls
Conditional presentation
IfPermission
IfInterface
Common UI Patterns
3-pane layout
Settings
Plugins
Forms
Feedback
Validation
Callout/ Callout Context
Dates/Times
Styles
CSS-Modules
PostCSS Stack
Handling Changes
Versioning - What constitutes a breaking change?
Contributing
PR Comments
Your PR Comments are a very important part of the contribution process! Good comments will clearly express the intentions of the code and allow reviewers to provide the best direction possible so that we can merge consistent, clean code. Here’s a few items that a good PR comment will have:
A link to the applicable Jira ticket.
Problem statement - what problem does your code resolve? Is there a buggy behavior? Was logic implemented incorrectly before? How so?
Approach - How did you go about resolving the problem? Any uncommon knowledge as to why your solution resolves the issue.
Questions, target areas for review - are there any areas of the code that reviewers should focus on?
Jira ticket association
Your Jira ticket ‘UIEXAMPLE-###’ should be in at least two places.
Your Branch Name - this will associated it with the ‘Development’ fields on the Jira ticket via the JIRA-Github integration. This allows PO’s and maintainers to easily track progress of the work.
A link to the Jira ticket in your PR comment (as mentioned above)