From 0968b3abb1d38c6f0a66d2a75bbc52b7d8f6be17 Mon Sep 17 00:00:00 2001
From: Ibrahim <93064150+IbrahimCSAE@users.noreply.github.com>
Date: Wed, 10 Jul 2024 11:28:35 -0400
Subject: [PATCH] docs(tools): add listener helpful tip for migration (#4285)

---
 .../docs/migration-guide/from-3p7-to-3p8.md   | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/platform/docs/docs/migration-guide/from-3p7-to-3p8.md b/platform/docs/docs/migration-guide/from-3p7-to-3p8.md
index e35493efa..b07d8ffe0 100644
--- a/platform/docs/docs/migration-guide/from-3p7-to-3p8.md
+++ b/platform/docs/docs/migration-guide/from-3p7-to-3p8.md
@@ -132,6 +132,46 @@ Additional Resources
   - For more information on the new toolbar module and its usage, refer to the [Toolbar documentation](../platform/extensions/modules/toolbar.md).
   - Consult the updated button definitions in `modes/longitudinal/src/toolbarButtons.ts` for examples of the new object-based button definition format and the usage of evaluators.
 
+### Tool listeners
+
+Some tools can be configured to listen to events to trigger, for example
+
+```ts
+createButton({
+  id: 'ReferenceLines',
+  icon: 'tool-referenceLines',
+  label: 'Reference Lines',
+  tooltip: 'Show Reference Lines',
+  commands: 'toggleEnabledDisabledToolbar',
+  listeners: {
+      [ViewportGridService.EVENTS.ACTIVE_VIEWPORT_ID_CHANGED]:
+          ReferenceLinesListeners,
+      [ViewportGridService.EVENTS.VIEWPORTS_READY]:
+          ReferenceLinesListeners,
+  },
+  evaluate: 'evaluate.cornerstoneTool.toggle',
+  }),
+```
+
+If you have a custom viewport component, and you are overriding the ```onElementEnabled``` handler, than ensure to call ```viewportGridService.setViewportIsReady(viewportId, true)``` in your own handler so that eventually the ```VIEWPORTS_READY``` event fires as expected, if you are not modifying the handler, then an existing handler that is automatically passed down via the props will call that for you, it is passed down from ```ViewportGrid.tsx```
+
+```ts
+<ViewportComponent
+   displaySets={displaySets}
+   viewportLabel={viewports.size > 1 ? viewportLabel : ''}
+   viewportId={viewportId}
+   dataSource={dataSource}
+   viewportOptions={viewportOptions}
+   displaySetOptions={displaySetOptions}
+   needsRerendering={displaySetsNeedsRerendering}
+   isHangingProtocolLayout={isHangingProtocolLayout}
+   onElementEnabled={() => {
+          viewportGridService.setViewportIsReady(viewportId, true);
+   }}
+/>
+
+```
+
 ## Toolbar Service
 
 toolbarService.init is not a function.