Merge pull request #228 from FlutterFlow/pinkesh/on-dispose

Added On Dispose Info

Author: pinkeshmars

docs/resources/ui/components/component-lifecycle.md

@@ -71,6 +71,15 @@ created.
 Your component can also respond to certain keypress events. For more details on setting this up, see [this section on 
 keyboard shortcuts](/resources/ui/pages/page-lifecycle#on-shortcut-press-action-trigger).
 
+### On Dispose [Action Trigger]
+The **On Dispose** action trigger for components allows you to define actions that execute when the page containing the component is navigated away or removed from memory. It is particularly useful for stopping ongoing operations.
+
+Imagine a scenario where a [periodic action](../../../resources/control-flow/time-based-logic/periodic-action.md), such as fetching live weather updates, is started in a component when it is loaded (i.e, [On Initialization](#on-initialization-action-trigger)). The action runs periodically, providing real-time data updates as long as the component is active. However, when the page containing the component is navigated away, you need to stop the periodic action to conserve resources and prevent unnecessary processing. By using the On Dispose action trigger, you can safely stop the periodic updates and clean up any associated resources.
+
+:::info
+The **On Dispose** action trigger is always executed before the [**parent page’s On Dispose**](../pages/page-lifecycle.md#on-dispose-action-trigger). This ensures that the component cleans up its resources first, allowing the parent to finalize its disposal without dependencies on the child.
+:::
+
 ## Component state
 
 :::note[STATE VARIABLES]

docs/resources/ui/pages/imgs/page-on-dispose.avif

@@ -150,6 +150,22 @@ For instance, if you have a shortcut assigned to the letter "C" and a user tries
 To handle this, you can enable the option on the `TextField` widget to bypass keyboard shortcuts. However, it’s generally better to assign more unique combinations, like Cmd + C, which are less likely to conflict with normal typing in a text field.
 :::
 
+### On Dispose [Action Trigger]
+
+The **On Dispose** action trigger allows you to define actions that execute when a page is navigated away from or removed from memory. It is particularly useful for stopping ongoing operations.
+
+Imagine a scenario where [audio recording](../../../ff-concepts/file-handling/audio/audio-recroding.md) is started when the page loads using the [On Page Load](#on-page-load-action-trigger) action trigger. The recording process runs as long as the user remains on the page. However, when the user navigates away, you need to stop the recording to save resources and ensure the recorded audio is finalized. By using the On Dispose action trigger, you can safely stop the recording and save the file.
+
+Additionally, if you are using a third-party package that relies on persistent connections or listeners, you can leverage [Custom Actions](../../../ff-concepts/adding-customization/custom-actions.md) with the On Dispose action trigger to close streams or cancel subscriptions.
+
+:::tip[Possible Use Cases]
+- **Cleaning Up Resources:** Use this action trigger to cancel timers, close database connections, or unsubscribe from streams to prevent memory leaks and unnecessary processing.
+    - For example, real-time applications, such as stock trading platforms, rely on WebSocket connections to fetch live updates. A homepage displaying a live ticker of stock prices would require opening the WebSocket connection on page load and closing it on On Dispose. Without an On Dispose trigger, the WebSocket connection could remain open unnecessarily, leading to wasted resources and app instability.
+- **Finalizing Database Transactions**: Commit or roll back database transactions if the user leaves the page before completing the process.
+- **Logging or Analytics:** Track user behavior or log events (e.g., page exit or time spent on a page) to monitor user engagement and improve the application experience.
+:::
+![page-on-dispose.avif](imgs/page-on-dispose.avif)
+
 ## Page state
 
 :::note[State Variables]