fix/migration 3p11 (#5370)
This commit is contained in:
Alireza authored and GitHub committed
1 parent
df0593aac9
commit
6a1838bf0d
391 files changed
+2322
-215
No files matched your search
+178
@@ -0,0 +1,178 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
sidebar_label: Toolbar Service
|
||||
summary: Migration guide for OHIF 3.11's toolbar service changes, including the transition from `ViewportActionCornersService` to `ToolbarService`
|
||||
---
|
||||
|
||||
|
||||
**Key Changes:**
|
||||
|
||||
* **`ViewportActionCornersService` Removed:** The `ViewportActionCornersService` and its associated provider (`ViewportActionCornersProvider`) and hook (`useViewportActionCorners`) have been removed. Functionality for viewport corner items is now integrated into the `ToolbarService` and standard toolbar components.
|
||||
* **Viewport Corner Items as Toolbar Buttons:** Items previously managed by `ViewportActionCornersService` are now configured as regular toolbar buttons. They are assigned to specific toolbar sections (e.g., `viewportActionMenu.topLeft`) and rendered using `Toolbar` components within the viewport corners.
|
||||
* **`ToolbarService` API Updates:**
|
||||
* `ToolbarService.addButtons()` has been renamed to `ToolbarService.register()` to better reflect its purpose of registering button definitions rather than just adding them.
|
||||
* `ToolbarService.createButtonSection()` has been renamed to `ToolbarService.updateSection()` to better reflect that it is not about creating new sections but updating existing ones.
|
||||
* `ToolbarService` now has a `sections` property (e.g., `toolbarService.sections.viewportActionMenu.topLeft`) providing predefined section names.
|
||||
* **Enhanced `useToolbar` Hook:**
|
||||
* The `useToolbar` hook now returns additional state management functions for toolbar items:
|
||||
* `openItem`, `closeItem`, `isItemOpen` (for managing dropdown/popover states).
|
||||
* `lockItem`, `unlockItem`, `toggleLock`, `isItemLocked`.
|
||||
* `showItem`, `hideItem`, `toggleVisibility`, `isItemVisible`.
|
||||
* The `onInteraction` callback now receives `itemId` and `viewportId`.
|
||||
* **Toolbar Button Configuration:**
|
||||
* The `groupId` prop in button configurations (e.g., for `ohif.toolButtonList`, `ohif.toolBoxButtonGroup`) is generally replaced by directly using `buttonSection` to define the set of buttons.
|
||||
* Button `evaluate` functions can now leverage `evaluateProps.hideWhenDisabled` to automatically hide a button when it's disabled.
|
||||
* **New UI Components & Hooks for Viewport Corners:**
|
||||
* Specialized components like `ModalityLoadBadge`, `NavigationComponent`, `TrackingStatus`, `ViewportDataOverlayMenuWrapper`, `ViewportOrientationMenuWrapper`, `WindowLevelActionMenuWrapper` are now used as toolbar buttons, typically in viewport action menu sections.
|
||||
* `useViewportHover` hook can be used to determine if a viewport is hovered or active, controlling the visibility of corner toolbars.
|
||||
* **`IconPresentationProvider`:** A new `IconPresentationProvider` and `useIconPresentation` hook have been introduced to standardize icon sizing and styling within toolbars and related components.
|
||||
* **Legacy Toolbar Components Removed:** `ToolbarSplitButtonWithServicesLegacy` and `ToolbarButtonGroupWithServicesLegacy` have been removed.
|
||||
|
||||
**Migration Steps:**
|
||||
|
||||
1. **Update `ToolbarService` Method Calls:**
|
||||
* Although the previous method also works but gives warning in the console when used.
|
||||
* Replace all instances of `toolbarService.addButtons(...)` with `toolbarService.register(...)`.
|
||||
* Replace all instances of `toolbarService.createButtonSection(...)` with `toolbarService.updateSection(...)`.
|
||||
|
||||
```diff
|
||||
// Before
|
||||
- toolbarService.addButtons(toolbarButtons);
|
||||
- toolbarService.createButtonSection('primary', ['Zoom', 'Pan']);
|
||||
|
||||
// After
|
||||
+ toolbarService.register(toolbarButtons);
|
||||
+ toolbarService.updateSection('primary', ['Zoom', 'Pan']);
|
||||
```
|
||||
|
||||
2. **Migrate Viewport Action Corner Items:**
|
||||
* Remove any direct usage of the old `ViewportActionCornersService`, `useViewportActionCorners`, or `ViewportActionCornersProvider`.
|
||||
* Define your viewport corner items (like orientation menu, W/L menu, data overlay menu) as standard toolbar buttons using `toolbarService.register()`.
|
||||
* Assign these buttons to the new dedicated viewport action menu sections. You can access these section names via `toolbarService.sections.viewportActionMenu.<location>`, e.g., `toolbarService.sections.viewportActionMenu.topLeft`.
|
||||
|
||||
```diff
|
||||
// Before: Customization in viewportActionMenuCustomizations.ts (now deleted)
|
||||
// or direct use of ViewportActionCornersService.addComponent
|
||||
- // Example: viewportActionCornersService.addComponent({ viewportId, id: 'orientationMenu', component: MyOrientationMenu, location: 'topLeft' });
|
||||
|
||||
// After: In your mode's onModeEnter or similar setup
|
||||
+ const myViewportCornerButtons = [
|
||||
+ {
|
||||
+ id: 'orientationMenu',
|
||||
+ uiType: 'ohif.orientationMenu', // Or your custom component registered as a UI type
|
||||
+ props: { /* ... props for your component ... */ }
|
||||
+ },
|
||||
+ // ... other corner buttons
|
||||
+ ];
|
||||
+ toolbarService.register(myViewportCornerButtons);
|
||||
+ toolbarService.updateSection(
|
||||
+ toolbarService.sections.viewportActionMenu.topLeft,
|
||||
+ ['orientationMenu', /* other button IDs */]
|
||||
+ );
|
||||
```
|
||||
* The `OHIFViewportActionCorners.tsx` component now internally uses `Toolbar` components for each corner, which are populated by these sections.
|
||||
* For custom components that act as menus (e.g., popovers), use the `onOpen`, `onClose`, `isOpen` props passed down by the `Toolbar` component (which get these from `useToolbar`).
|
||||
|
||||
```diff
|
||||
// Before: Custom component might have managed its own open state
|
||||
- // const [isMenuOpen, setIsMenuOpen] = useState(false);
|
||||
- // const handleOpenChange = (open) => setIsMenuOpen(open);
|
||||
|
||||
// After: Custom component receives isOpen, onOpen, onClose from Toolbar
|
||||
+ function MyCustomMenuButton({ isOpen, onOpen, onClose, ...rest }) {
|
||||
+ const handleOpenChange = (openState: boolean) => {
|
||||
+ if (openState) {
|
||||
+ onOpen?.();
|
||||
+ } else {
|
||||
+ onClose?.();
|
||||
+ }
|
||||
+ };
|
||||
+
|
||||
+ return (
|
||||
+ <Popover open={isOpen} onOpenChange={handleOpenChange}>
|
||||
+ {/* ... PopoverTrigger and PopoverContent ... */}
|
||||
+ </Popover>
|
||||
+ );
|
||||
+ }
|
||||
```
|
||||
|
||||
3. **Adapt Toolbar Button and Component Configurations:**
|
||||
|
||||
The configuration of toolbar buttons, especially how they relate to sections
|
||||
|
||||
* **Button Section Association via `props.buttonSection`:**
|
||||
|
||||
The toolbar service now offers two ways to define this association:
|
||||
|
||||
* **A. Simple Approach: `buttonSection: true` (Implicitly Uses Button's Own ID)**
|
||||
|
||||
If a button definition includes `props: { buttonSection: true }`, the `ToolbarService` automatically sets the effective `buttonSection` ID to be the same as the button's own `id`.
|
||||
|
||||
```javascript
|
||||
// Example: A ToolButtonList component's definition in toolbarButtons.ts
|
||||
// {
|
||||
// id: 'MeasurementTools', // ID of this ToolButtonList component
|
||||
// uiType: 'ohif.toolButtonList',
|
||||
// props: {
|
||||
// buttonSection: true // This ToolButtonList will render the section named 'MeasurementTools'
|
||||
// }
|
||||
// }
|
||||
```
|
||||
|
||||
later you can use it like
|
||||
|
||||
|
||||
```javascript
|
||||
toolbarService.updateSection('MeasurementTools', ['Length', 'Bidirectional', ...]);
|
||||
```
|
||||
|
||||
* **B. Flexible Approach: `buttonSection: 'customSectionName'` (Explicit Section ID)**
|
||||
|
||||
You can explicitly provide a string for `props.buttonSection` if the button should be associated with a section ID that is different from its own `id`, or if you prefer explicit naming.
|
||||
|
||||
```javascript
|
||||
// Example: A ToolButtonList component's definition
|
||||
// {
|
||||
// id: 'MySpecialToolList', // ID of this ToolButtonList component
|
||||
// uiType: 'ohif.toolButtonList',
|
||||
// props: {
|
||||
// buttonSection: 'toolsForAdvancedUsers', // This list renders 'toolsForAdvancedUsers' section
|
||||
// }
|
||||
// }
|
||||
```
|
||||
|
||||
* **`evaluate` Function Enhancement:**
|
||||
* Button `evaluate` functions can now leverage `evaluateProps: { hideWhenDisabled: true }` in your button definition to automatically hide a button when it's disabled.
|
||||
|
||||
* **Wrapper Component `onInteraction` (e.g., `ToolButtonListWrapper`):**
|
||||
* Update wrappers like `ToolBoxButtonGroupWrapper` and `ToolButtonListWrapper`:
|
||||
* The `groupId` prop is replaced by `id` (which is the ID of the wrapper button component itself).
|
||||
* The `onInteraction` callback in these wrappers now provides `id` (the wrapper's ID) instead of `groupId`.
|
||||
|
||||
|
||||
4. **Adopt `IconPresentationProvider` (Optional but Recommended):**
|
||||
* For consistent icon styling across your application's toolbars, wrap a high-level component (like your main `Header` or layout component) with `<IconPresentationProvider size="yourDefaultSize">`.
|
||||
* Custom tool button components can then use the `useIconPresentation` hook to get appropriate class names for icons or a pre-styled `IconContainer`.
|
||||
|
||||
```diff
|
||||
// In your main App.tsx or Header.tsx
|
||||
+ import { IconPresentationProvider, ToolButton } from '@ohif/ui-next';
|
||||
// ...
|
||||
+ <IconPresentationProvider
|
||||
+ size="large" // Or "medium", "small", "tiny", or a number
|
||||
+ IconContainer={ToolButton} // Optional: default is Button
|
||||
+ containerProps={{ variant: 'primary', className: 'custom-container-class' }} // Optional
|
||||
+ >
|
||||
{/* Your Header content including Toolbars */}
|
||||
+ </IconPresentationProvider>
|
||||
|
||||
// In a custom tool button using icons
|
||||
+ import { useIconPresentation, Icons } from '@ohif/ui-next';
|
||||
+ function MyCustomToolButton({ iconName }) {
|
||||
+ const { className: iconClassName } = useIconPresentation();
|
||||
+ return <button><Icons.ByName name={iconName} className={iconClassName} /></button>;
|
||||
+ }
|
||||
```
|
||||
|
||||
5. **Remove Legacy Component Usage:**
|
||||
* Replace any usage of `ToolbarSplitButtonWithServicesLegacy` and `ToolbarButtonGroupWithServicesLegacy` with the newer patterns, typically by configuring individual buttons and using `ToolButtonList` or `ButtonGroup` from `@ohif/ui-next` directly, driven by `useToolbar`.
|
||||
Reference in new issue
Block a user