Minimap Evaluation
The purpose of this evaluation is to determine the best approach for implementing all minimap features as designed for FluxNotes full version.
Below is a list of minimap features required as of 2017-11-03:
- Ability to synchronize the minimap with another component’s scroll position (basic minimap functionality)
- Ability to label each section of the minimap
- Ability for each section of the minimap to have configured heights or have their heights based on the length of the associated components scrolling area for the section
- Ability to have collapsed (names only) and expanded (preview of content) modes
- Ability of minimap to automatically provide thumbnail pictures of the content it’s scrolling within the minimap in expanded mode
- Ability to support dynamic reconfiguration of sections and ordering of sections
- Ability to drag displayed section “window” to somewhere else in minimap and notify affected component of its new scroll position
- Ability to click on a section to jump to it by putting it at the top or as close as it can get if it’s near the end of the document
- Ability to show annotations (formatted text or icons) on sections for search results or missing data indicators or other indications
- Ability to highlight parts of each minimap section to correspond to specified sections of the component
The following minimap libraries were evaluated:
| Library Name | Demo | Usability | Notes |
|---|---|---|---|
| demux/react-minimap | 🔗 | low | Contained option looks viable. Documentation lacking. Last commit 9/16. Open issue not addressed. |
| jeremy-carbonne/react-minimap | 🔗 | high | Well supported. Documentation ok, not great. Allows for render customization. Recent commits. No issues. |
| UpForce-Tech/minimap-react | 🔗 | low | Demo is buggy. No support for render customization. Per documentation, cannot be used in production. |
| reminyborg/dom-minimap | 🔗 | medium | React demo is broken. Recent commits but open issue not addressed. Used DOM elements, which would work well. |
Initial evaluation of the four libraries researched ranked each by usability based on code quality, documentation quality, recent commits, open issues, customization options, and usage feasibility and complexity. None of the 4 libraries evaluated had out-of-the-box capability to handle all of the 10 feature requirements needed for the full app version of FluxNotes.
Removing those libraries with a low usability ranking, leaves us with the following libraries:
Secondary evaluation of the dom-minimap and react-minimap libraries involved a more thorough dive into the code for each.
dom-minimap 🔗
This library is a simple JavaScript library that supports vertical-only minimap functionality. It uses IDs and classes to tag DOM elements to be used in the minimap. Functionality includes basic minimap features (Req #1), labeling minimap sections (Req #2), tooltips, and styling.
Requirements met: #1, #2
react-minimap 🔗
This library is a React library that is based on the jquery plugin jquery-minimap. It uses up-to-date React v16 and was created using create-react-app, which is the current standard practice. The code is well-organized and written. Functionality includes basic minimap features (Req #1), minimap custom rendering (Req's #2, #9, #10-partial), custom height (Req #3), and custom width (Req #4 - partial).
Requirements met: #1, #2, #3, #4-partial, #9, #10-partial
❌ - Failed to meet requirement ❓ - Partially meets requirement ✅ - Meets requirement
| dom-minimap | react-minimap | |
|---|---|---|
| 1. Ability to synchronize the minimap with another component’s scroll position (basic minimap functionality) | ✅ | ✅ |
| 2. Ability to label each section of the minimap | ✅ | ✅ |
| 3. Ability for each section of the minimap to have configured heights or have their heights based on the length of the associated components scrolling area for the section | ❌ | ✅ |
| 4. Ability to have collapsed (names only) and expanded (preview of content) modes | ❌ | ❓ |
| 5. Ability of minimap to automatically provide thumbnail pictures of the content it’s scrolling within the minimap in expanded mode | ❌ | ❌ |
| 6. Ability to support dynamic reconfiguration of sections and ordering of sections | ❌ | ❌ |
| 7. Ability to drag displayed section “window” to somewhere else in minimap and notify affected component of its new scroll position | ❌ | ❌ |
| 8. Ability to click on a section to jump to it by putting it at the top or as close as it can get if it’s near the end of the document | ❌ | ❌ |
| 9. Ability to show annotations (formatted text or icons) on sections for search results or missing data indicators or other indications | ❌ | ✅ |
| 10. Ability to highlight parts of each minimap section to correspond to specified sections of the component | ❌ | ❓ |
Given the findings above, I recommend we fork a copy of react-minimap and build in the rest of the features we need. We can then include this new library in FluxNotes to use for the minimap.
- This approach allows us to have complete control over the code base of the library
- Features can be added or edited at any time
- The library, which may end up being relatively large, will remain separate from the main FluxNotes app
- It will take a considerable amount of initial work to get all the features working in the forked library, however this will be the case regardless of the approach we take
- The library will need to be maintained