Improve Documentation Based on User Feedback

[gerdesque]

Based on feedback gathered from our recent user survey, several areas of the Mirador documentation have been identified as needing improvement to enhance the user experience. The following key areas require updates:

1. Improve Documentation for Standalone Setup

• Objective: Make it easier for users to start Mirador as a standalone application.
• Proposed Actions:
  • Provide step-by-step instructions for setting up Mirador standalone.
  • Include common troubleshooting tips for standalone installation.
  • Add examples of typical use cases for standalone deployment.

2. Improve Documentation for Framework Integration

• Objective: Simplify the process of starting Mirador within popular frameworks (e.g., React, Angular, Vue).
• Proposed Actions:
  • Add specific sections or pages detailing integration steps for various frameworks.
  • Provide example code snippets for different frameworks.
  • Highlight potential issues users might face when integrating Mirador within these frameworks and suggest solutions.

3. Enhance Plugin Usage Documentation

• Objective: Ensure it’s easy for users to understand how to use and develop plugins within Mirador.
• Proposed Actions:
  • Expand the documentation on plugin architecture and lifecycle.
  • Provide detailed examples of plugin creation and usage.
  • Include a list of available plugins with brief descriptions and use cases.
  • Ensure that plugin-related documentation is easily accessible from the main documentation pages.

Additional Notes:

• The improvements should focus on clarity, ease of understanding, and practical examples that users can directly apply.
• User feedback indicated that the current documentation is too sparse in these areas, leading to difficulties during setup and usage.

Tasks:

• Update standalone setup documentation.
• Update framework integration documentation.
• Enhance plugin usage documentation.

[gerdesque]

Draft for 'Enhance plugin usage documentation.'

Here's a step-by-step guide to creating and using plugins in Mirador 4, written in Markdown for easy documentation.

---

Mirador 4 Plugin Creation and Usage Guide

This guide provides an overview of how to create, configure, and use plugins in Mirador 4 to customize and extend its functionality. Mirador 4 supports plugins to add new components, modify existing ones, and interact with its Redux-based state.

• Introduction to Mirador Plugins
• Setting Up Your Development Environment
• Creating a Basic Plugin
  • 1. Define the Plugin Structure
  • 2. Create the React Component
  • 3. Export the Plugin
• Configuring the Plugin in Mirador
• Advanced Plugin Capabilities
  • 1. Mapping State and Dispatch to Props
  • 2. Example: Toggling a Plugin Component
• Debugging and Testing
  • Best Practices and Tips
• Conclusion

---

Introduction to Mirador Plugins

Mirador 4’s plugin system allows developers to extend and modify the viewer’s functionality by adding or wrapping existing components, managing the application state, and triggering custom behaviors. The plugins are structured as JavaScript objects that include specific properties to define what and how they interact with the Mirador environment.

Setting Up Your Development Environment

To start developing a plugin, ensure you have the following tools installed:

• Node.js and npm for package management.
• React and Redux basics, as Mirador is built using these frameworks.
• A Mirador development environment. You can clone the Mirador repository or use the existing viewer setup.

# Clone Mirador repository
git clone https://github.com/ProjectMirador/mirador.git
cd mirador
npm install
npm start

Creating a Basic Plugin

A Mirador plugin requires several essential properties to interact with the viewer. Here’s a breakdown of each step in creating a basic plugin.

1. Define the Plugin Structure

A plugin is a JavaScript object with properties like component, target, and mode. Here’s a sample structure:

const MyFirstPlugin = {
  target: 'WindowTopBarPluginArea',
  mode: 'add',
  component: MyPluginComponent,
};

• target: Specifies the Mirador component to modify (e.g., WindowTopBarPluginArea).
• mode: Determines whether the plugin will "add" a new component or "wrap" an existing one.
• component: The React component to be rendered.

2. Create the React Component

Your plugin can include any custom React component. For example:

import React from 'react';

const MyPluginComponent = () => (
  <div>
    <p>This is my first plugin component!</p>
  </div>
);

3. Export the Plugin

Once your plugin object and component are ready, export the plugin so it can be imported into Mirador’s main configuration.

export default MyFirstPlugin;

Configuring the Plugin in Mirador

To use the plugin, add it to Mirador's configuration when initializing the viewer. Here’s how to include the plugin during setup:

import Mirador from 'mirador';
import MyFirstPlugin from './path/to/MyFirstPlugin';

const miradorConfig = {
  id: 'mirador',
  windows: [{
    manifestId: 'https://iiif.harvardartmuseums.org/manifests/object/299843',
  }],
  plugins: [
    MyFirstPlugin,
  ],
};

Mirador.viewer(miradorConfig);

Here:

• plugins: Add your plugin to the plugins array to ensure it’s loaded when Mirador initializes.

Advanced Plugin Capabilities

Mirador plugins support interaction with Redux for state management, enabling you to connect to the viewer's data or dispatch actions.

1. Mapping State and Dispatch to Props

Use mapStateToProps to access the Mirador state and mapDispatchToProps to send actions. For instance:

const MyFirstPlugin = {
  target: 'WindowTopBarPluginArea',
  mode: 'add',
  component: connect(mapStateToProps, mapDispatchToProps)(MyPluginComponent),
};

• mapStateToProps: Retrieves data from Mirador’s Redux store.
• mapDispatchToProps: Dispatches actions to modify state or trigger effects.

2. Example: Toggling a Plugin Component

Suppose we want our plugin to toggle based on a Redux state change:

const mapStateToProps = (state) => ({
  isVisible: state.myPluginState.isVisible,
});

const mapDispatchToProps = (dispatch) => ({
  toggleVisibility: () => dispatch({ type: 'TOGGLE_VISIBILITY' }),
});

const MyPluginComponent = ({ isVisible, toggleVisibility }) => (
  <div>
    {isVisible && <p>Plugin is visible!</p>}
    <button onClick={toggleVisibility}>Toggle Visibility</button>
  </div>
);

Debugging and Testing

While developing plugins, use the following tools and techniques for debugging:

• Redux DevTools: Access and manipulate Mirador's Redux state.
• Console Logging: Track state updates and function executions in your components.
• Hot Module Replacement (HMR): Enable fast reloading for quick testing.

Best Practices and Tips

1. Explore Existing Plugins: Reference mirador-plugin-demos for examples.
2. Reuse Selectors: Leverage Mirador’s Redux selectors where possible to avoid redundancy.
3. Stay Updated: Follow Mirador GitHub Issues for tips and solutions to common challenges.

Conclusion

Mirador plugins are powerful tools for customizing the viewer experience. By following these steps, you can create plugins that seamlessly integrate with the Mirador environment, offering flexibility and control over its functionality.

---

This guide covers the basics of creating and configuring plugins in Mirador 4. For further details and advanced customization, refer to the official Mirador Plugin Documentation.

[fstoe]

Advanced Plugin Capabilities

Mirador plugins support interaction with Redux for state management, enabling you to connect to the viewer's data or dispatch actions.

1. Mapping State and Dispatch to Props

Use mapStateToProps to access the Mirador state and mapDispatchToProps to send actions. For instance:

const MyFirstPlugin = {
  target: 'WindowTopBarPluginArea',
  mode: 'add',
  component: connect(mapStateToProps, mapDispatchToProps)(MyPluginComponent),
};

• mapStateToProps: Retrieves data from Mirador’s Redux store.
• mapDispatchToProps: Dispatches actions to modify state or trigger effects.

2. Example: Toggling a Plugin Component

Suppose we want our plugin to toggle based on a Redux state change:

const mapStateToProps = (state) => ({
  isVisible: state.myPluginState.isVisible,
});

const mapDispatchToProps = (dispatch) => ({
  toggleVisibility: () => dispatch({ type: 'TOGGLE_VISIBILITY' }),
});

const MyPluginComponent = ({ isVisible, toggleVisibility }) => (
  <div>
    {isVisible && <p>Plugin is visible!</p>}
    <button onClick={toggleVisibility}>Toggle Visibility</button>
  </div>
);

Maybe something like this could be added to this section.

3 Reducer Plugin

The plugin system allows for optional adding of actions and reducers.

// define a plugin state
const myPluginDefaultState: {
   id: 'default',
   count: 0
}


// define some actions
const myPluginCountIncrement = createAction('myPluginCounter/increment')
const myPluginCountDecrement = createAction('myPluginCounter/decrement')


// create some plugin reducer
const myPluginReducer = createReducer(myPluginDefaultState) => {
 (builder => {
   builder.addCase(myPluginCountIncrement, (state, action) => {
   	state.count = state.count + 1
   }
   ...
 }
}

// Add the reducer to the Mirador Plugin. Later, the 'myCount' value will be accessible
// as a prop in the MyPlugin component, allowing you to access the current count state.
const myPlugin = {
   component: MyPlugin,
   target: 'Workspace',
   mode: 'add',
   reducers: {
   	myPluginState: myPluginReducer
   },
   mapStateToProps: (state) => ({
   	myCount: state.myPluginState.count
   })
}