From 922ba8cc421330a5ced85a2894dd5a16fb139d83 Mon Sep 17 00:00:00 2001 From: dannyrb Date: Mon, 9 Dec 2019 00:44:04 -0500 Subject: [PATCH] docs: toolbar docs for three different kinds of definitions --- docs/latest/extensions/modules/toolbar.md | 150 +++++++++++++++++----- 1 file changed, 116 insertions(+), 34 deletions(-) diff --git a/docs/latest/extensions/modules/toolbar.md b/docs/latest/extensions/modules/toolbar.md index 92508cc76..00435ff1b 100644 --- a/docs/latest/extensions/modules/toolbar.md +++ b/docs/latest/extensions/modules/toolbar.md @@ -1,48 +1,130 @@ # Module: Toolbar -An extension can register a Toolbar Module by providing a `getToolbarModule()` -method that returns a React Component. The component does not receive any props. -If you want to modify or react to state, you will need to connect to the redux -store. The given toolbar must determine its set of elements and the context of -them. The set of elements will be listed on toolbar `definitions`. +An extension can register a Toolbar Module by defining a `getToolbarModule` +method. This module is commonly used to define: -![Toolbar Extension](../assets/img/extensions-toolbar.gif) +- [Toolbar buttons](#button-definitions) +- [Nested toolbar menus](#nested-toolbar-menus) +- [Custom components](#custom-components) -
A toolbar extension example
+![Toolbar Extension](../../assets/img/extensions-toolbar.gif) -Toolbar components are rendered in the `ToolbarRow` component. +
Example toolbar button using the Dialog Service to show CINE controls.
-For a complete example implementation, -[check out the OHIFCornerstoneViewport's Toolbar Module](https://github.com/OHIF/Viewers/blob/master/extensions/cornerstone/src/toolbarModule.js). +## Example Toolbar Module -## Toolbar Custom Component - -Toolbar elements can define its own custom react component to be consumed when -rendering it. So far, it accepts `Functional` and `Class` Components. For that, -you just need to expose your `CustomToolbarComponent` as the value of key -`CustomComponent`. In case the property `CustomComponent` is not present, a -default toolbar component will be used to render it. See bellow +The Toolbar Module should return an array of `definitions` and a +`defaultContext`. There are currently a few different variations of definitions, +each one is detailed further down. ```js -definitions: [ -... +export default { + id: 'example-toolbar-module', + + /** + * @param {object} params + * @param {ServicesManager} params.servicesManager + * @param {CommandsManager} params.commandsManager + */ + getToolbarModule({ servicesManager, commandsManager }) { + return { + definitions: [ + /* Array of definitions */ + ], + defaultContext: ['ROUTE:VIEWER'], + }; + }, +}; +``` + +## Button Definitions + +The simplest definition has the following properties: + +```js +{ + id: 'StackScroll', + label: 'Stack Scroll', + icon: 'bars', + type: 'setToolActive', + commandName: 'setToolActive', + commandOptions: { toolName: 'StackScroll' }, +}, +``` + +| property | description | values | +| ---------------- | ----------------------------------------------------------------- | ----------------------------------------- | +| `id` | Unique string identifier for the definition | \* | +| `label` | User/display friendly to show in UI | \* | +| `icon` | A string name for an icon supported by the consuming application. | \* | +| `type` | Used to determine the button's component and behavior | `"setToolActive"`, `"command"` | +| `commandName` | (optional) The command to run when the button is used. | Any command registed by a `CommandModule` | +| `commandOptions` | (optional) Options to pass the target `commandName` | \* | +| `context` | (optional) Overrides module's `defaultContext` | Array of string context names | + +Where a button with a `type` of `setToolActive` has an "active" styling applied +when clicked; removing the active styling from all other buttons. + +## Nested Toolbar Menus + +You can indicate that buttons should be grouped and nested in a submenu by +including `buttons` property in a definition: + +```js +{ + id: 'More', + label: 'More', + icon: 'ellipse-circle', + buttons: [ { - id: 'Custom', - label: 'Custom', - icon: 'custom-icon', - CustomComponent: CustomToolbarComponent, - } -... -] + id: 'cstInvert', + label: 'Invert', + icon: 'circle', + type: 'command', + commandName: 'invertViewport', + }, + ], +}, +``` + +![Toolbar Extension](../../assets/img/extensions-toolbar-nested.gif) + +
Example toolbar button demonstrating nested buttons.
+ +## Custom Components + +The Toolbar Modules supports rendering custom components in place of the +application's default. In place of the `type`, `commandName`, and +`commandOptions` properties, we instead specify a `CustomComponent`. + +```js +{ + id: 'Custom', + label: 'Custom', + icon: 'custom-icon', + CustomComponent: CustomToolbarComponent, +} ``` -`CustomComponent` components will receive the following props: +The `CustomComponent` components will receive the following props: -- parentContext: parent context. (In most of the cases it will be a ToolbarRow - instance) -- toolbarClickCallback: callback method when clicking on toolbar -- button: its own definition object -- key: react key prop -- activeButtons: list of active elements -- isActive: if current +```html + +``` + +| Property | Type | Description | +| ---------------------- | -------- | ------------------------------- | +| `activeButtons` | string[] | list of active buttons | +| `button` | object | its own definition object | +| `key` | string | React key prop | +| `isActive` | boolean | If current button is active | +| `parentContext` | ? | The parent component's context? | +| `toolbarClickCallback` | func | Callback method for clicks |