From 532d52232d854f5efdb960f8034d72fe5864f0d4 Mon Sep 17 00:00:00 2001 From: braks <78412429+bcakmakoglu@users.noreply.github.com> Date: Thu, 13 Jun 2024 19:29:46 +0200 Subject: [PATCH] docs: update handle docs --- docs/src/guide/handle.md | 128 +++++++++++++++++++++++++++++++++++---- docs/src/guide/node.md | 41 ------------- 2 files changed, 117 insertions(+), 52 deletions(-) diff --git a/docs/src/guide/handle.md b/docs/src/guide/handle.md index 5741bce5..d1fd8fbf 100644 --- a/docs/src/guide/handle.md +++ b/docs/src/guide/handle.md @@ -8,18 +8,67 @@ Handles are the small circles that are usually placed on the borders of a node. together by dragging a connection-line from one handle to another, resulting in a connection ([Edge](/guide/edge)) between the nodes. -Handles are a crucial part of the VueFlow library, as they are the main interaction point for the user to create -connections between nodes. +Handles are a crucial part of VueFlow, as they are the main interaction point for a user to create edges between nodes. -Without handles, it is basically impossible to create edges between nodes, as the `` components are used -to calculate the points for the edges. +Without handles, it is basically impossible to create edges between nodes, as the handles are used +to calculate the source and target points for edges. -## Handle Component +## `` Component -The `` component is a simple component that is used to create a handle for a node. It is a wrapper around a -`
` element that provides the necessary event handlers to create edges between nodes. +The `` component is a component exported by `@vue-flow/core` that you can use to create a handle for a node. +It is a wrapper around a `
` element that provides the necessary event handler bindings to start connections. -The `` component is used in the `` component to create handles for the node. +The `` component can be used in a (custom) node component to create handles for the node. +Using `` components outside a node component context will not work as expected, so try to avoid this. + +```vue + + + +``` + +## Handle Positions + +Handles can be placed on the following positions: + +- `Top` +- `Right` +- `Bottom` +- `Left` + +Each position corresponds to a side of the node. +The position of the handle also determines which direction an edge will bend towards when drawn from and to a handle. + +For example a handle with `position="Position.Top"` will result in an edge that bends to the *top* when drawn *from* that handle. +A handle with `position="Position.Right"` will result in an edge that bends to the *left* when drawn *to* that handle. + +### Adjusting Handle Positions + +Handles are positioned on their respective side using CSS with an `absolute` position. +That means you can adjust what element a handle aligns itself with by wrapping it in a container that has a `relative` position. + +```vue +
+ {{ data.label }} + +
+ + + + +
+
+``` ## Multiple Handles @@ -28,8 +77,12 @@ When using multiple handles of the same type (`source` or `target`), each handle ```vue - - + + + + + + ``` The `id` prop is used to identify the handle when creating edges between nodes. If no `id` is provided, the first handle @@ -48,7 +101,19 @@ onConnect(({ source, target, sourceHandle, targetHandle }) => { }) ``` -## Hide Handles +### Positioning with Multiple Handles + +Sometimes you want to add multiple handles to the same side. In that case you often end up having two handles on top of each other instead of next to each other. +Handles will not layout themselves automatically, so you need to manually adjust their position. + +You can do so using CSS styles. +For example, you can set the `top` and `bottom` properties to position the handles on the top and bottom of the right side of the node. +```vue + + +``` + +## Hidden Handles In some cases you might not want to display a handle at all. You can hide a handle by setting `opacity: 0` as the styles for that handle. @@ -57,3 +122,44 @@ You cannot hide a handle by removing it from the DOM (for example using `v-if` o ```vue ``` + +## Dynamic Handle Positions & Adding/Removing Handles Dynamically + +::: tip +In Vue Flow 1.x, there's no need to manually invoke `updateNodeInternals` when dynamically adding handles. +Upon mounting, handles will automatically attempt to attach to the node. +However, if for any reason this isn't happening as expected, you can stick to the guideline provided below to enforce Vue Flow to update the node internals. +::: + +At times, you may need to modify handle positions dynamically or programmatically add new handles to a node. In this scenario, the [`updateNodeInternals`](/typedocs/types/UpdateNodeInternals) method found in Vue Flow's API comes in handy. + +Invoking this method is vital when dealing with dynamic handles. If not, the node might fail to recognize these new handles, resulting in misaligned edges. + +The `updateNodeInternals` function can be deployed in one of two ways: + +- **Using the store action:** This approach allows you to update several nodes at once by passing their IDs into the method. +- **Emitting the `updateNodeInternals` event from your customized node component:** This doesn't require any parameters to be passed. + +::: code-group + +```js [store action] +import { useVueFlow } from '@vue-flow/core' + +const { updateNodeInternals } = useVueFlow() + +const onSomeEvent = () => { + updateNodeInternals(['1']) +} +``` + +```vue [emit event] + +``` + +::: diff --git a/docs/src/guide/node.md b/docs/src/guide/node.md index ddc5a3b4..03e23c0f 100644 --- a/docs/src/guide/node.md +++ b/docs/src/guide/node.md @@ -946,44 +946,3 @@ const inputValue = ref('') @apply bg-primary rounded p-4; } - -## Working with Dynamic Handle Positions / Adding Handles Dynamically - -::: tip -In Vue Flow 1.x, there's no need to manually invoke `updateNodeInternals` when dynamically adding handles. -Upon mounting, handles will automatically attempt to attach to the node. -However, if for any reason this isn't happening as expected, you can stick to the guideline provided below to enforce Vue Flow to update the node internals. -::: - -At times, you may need to modify handle positions dynamically or programmatically add new handles to a node. In this scenario, the [`updateNodeInternals`](/typedocs/types/UpdateNodeInternals) method found in Vue Flow's API comes in handy. - -Invoking this method is vital when dealing with dynamic handles. If not, the node might fail to recognize these new handles, resulting in misaligned edges. - -The `updateNodeInternals` function can be deployed in one of two ways: - -- **Using the store action:** This approach allows you to update several nodes at once by passing their IDs into the method. -- **Emitting the `updateNodeInternals` event from your customized node component:** This doesn't require any parameters to be passed. - -::: code-group - -```js [store action] -import { useVueFlow } from '@vue-flow/core' - -const { updateNodeInternals } = useVueFlow() - -const onSomeEvent = () => { - updateNodeInternals(['1']) -} -``` - -```vue [emit event] - -``` - -:::