Dashboard Documentation
- Ethan Freestone
- Owen Stephens
Introduction
These pages introduce the terminology and approach taken to delivering a Dashboard app in Folio that is capable of displaying data from a range of Folio applications and other sources. This documentation covers the upkeep of the front/back end modules that deliver the Dashboard application and how developers can write configurations for new widgets to be available through the dashboard.
This documentation covers the ethos of the project, various workflows both for users and for developers, and how this work is accessible to teams outside of ERM.
This project, and consequently this documentation, relies on a lot of terms which need to be understood correctly. Please refer to the vocabulary section before continuing
Getting Started:
As a Folio user I want to add a widget to my dashboard.
As a Folio developer I want to develop a new widget definition for my app
To understand the difference between a widget definition, a widget type and a widget instance, make sure you have read and understand the vocabulary section first.
In brief, if an appropriate WidgetType already exists, you can write a new WidgetDefinition which can be used to deliver WidgetInstances without any new code.
- Decide on which WidgetType you want to develop a definition for
- Ensure that your environment has mod-service-interaction checked out and running, as well as ui-dashboard in your Stripes workspace.
- Ensure that your backend is set up to expose the dashboard interface.
- Check existing examples and read through the JSON schema for that type
- Write the JSON in the correct shape for your widget definition
- At this point a user should be able to configure and add a WidgetInstance from your definition to their dashboard, without any frontend work necessary.
As a Folio developer my new widget definition is not appearing correctly in the dashboard
There are a few potential problems which could be causing this. For more information see the what went wrong page.
As a Folio developer I want to develop a new widget type
To understand the difference between a widget definition, a widget type and a widget instance, make sure you have read and understand the vocabulary section first.
WidgetTypes are directly controlled and maintained by the ERM team, so if you haven't already, get in contact with the team via the #erm-developers Slack channel to discuss the functionality you wish to see.
- To actually develop on this project, a developer will need mod-service-interaction and ui-dashboard as above.
- A new WidgetType will require first a carefully constructed JSON schema, which contains provisions for all of the configuration possibilities necessary in each definition. That should be added to this folder.
- Following this, a developer will need to create a test definition in that shape, and add it to to this folder.
- From there, display and form components will need to be created in ui-dashboard. Check the existing implementations of SimpleSearch.