From 891eca4a23c2507b79e283dd3f9fde32c7fdfaf5 Mon Sep 17 00:00:00 2001 From: Braks <78412429+bcakmakoglu@users.noreply.github.com> Date: Mon, 4 Apr 2022 18:07:37 +0200 Subject: [PATCH] docs: Add edge page --- docs/src/.vuepress/config.ts | 10 +- docs/src/guide/edge.md | 309 +++++++++++++++++++++++++++++++++++ docs/src/guide/node.md | 2 +- 3 files changed, 319 insertions(+), 2 deletions(-) diff --git a/docs/src/.vuepress/config.ts b/docs/src/.vuepress/config.ts index 95f6b594..d3d3f69a 100644 --- a/docs/src/.vuepress/config.ts +++ b/docs/src/.vuepress/config.ts @@ -68,7 +68,15 @@ export default defineUserConfig({ '/guide/': [ { text: 'Guide', - children: ['/guide/', '/guide/getting-started', '/guide/theming', '/guide/config', '/guide/state', '/guide/node.md'], + children: [ + '/guide/', + '/guide/getting-started', + '/guide/theming', + '/guide/config', + '/guide/state', + '/guide/node', + '/guide/edge', + ], }, ], '/examples/': [ diff --git a/docs/src/guide/edge.md b/docs/src/guide/edge.md index e69de29b..323300bd 100644 --- a/docs/src/guide/edge.md +++ b/docs/src/guide/edge.md @@ -0,0 +1,309 @@ +# Edges + +Edges are what connects your nodes into a map. + +They cannot exist on their own and need nodes to which they are connected. + +Each edge requires a unique id, a source node and a target node id. +Anything else is optional. + +You can check the full options for an edge element in the TypeDocs [here](https://types.vueflow.dev/interfaces/Edge.html). + +## Usage + +Generally you create edges by adding them to the model-value or the edges prop of the Vue Flow component. + +```vue:no-line-numbers + + +``` + +For more +advanced graphs that require more state access you will want to use the useVueFlow composable. UseVueFlow will provide +you with an +`addNodes` utility function, which you can use to add nodes directly to the state. + +```vue:no-line-numbers + + +``` + +You can also apply changes (like removing elements safely) using the `applyEdgeChanges` utility function, which expects an array of changes to be +applied to the currently stored edges. + +## Default Edge-Types + +Vue Flow comes with built-in nodes that you can use right out of the box. +These node types include `default`, `input` and `output`. + +You can set a label on each of these types. + +### Default Edge (Bezier) + +A bezier edge has a curved path. + +```js:no-line-numbers +const edges = [ + { + id: 'e1-2', + source: '1', + target: '2', + } +] +``` + +### Step Edge + +A step edge has a straight path with a step towards the target. + +```js:no-line-numbers{4} +const edges = [ + { + id: 'e1-2', + type: 'step', + source: '1', + target: '2', + } +] +``` + +### Smoothstep Edge + +The same as the step edge though with a border radius on the step (rounded step). + +```js:no-line-numbers{4} +const edges = [ + { + id: 'e1-2', + type: 'smoothstep', + source: '1', + target: '2', + } +] +``` + +### Straight Edge + +A simple straight path. + +```js:no-line-numbers{4} +const edges = [ + { + id: 'e1-2', + type: 'straight', + source: '1', + target: '2', + } +] +``` + +## Custom Edges + +In addition to the default edge types from the previous chapter, you can define any amount of custom edge-types. +Edge-types are inferred from your edge's definition. + +```js:no-line-numbers{5,11} +const edges = [ + { + id: 'e1-2', + type: 'special', + source: '1', + target: '2', + }, +] +``` + +Vue Flow will now try to resolve this edge-type to a component. +First and foremost we will look for a definition in the `edgeTypes` object of the state. +After that we will try to resolve the component to a globally registered one that matches the exact name. +Finally, we will check if a template slot has been provided to fill the edge-type. + +If none of these methods succeed in resolving the component the default (bezier) edge-type will be used as a fallback. + +### Template slots + +The easiest way to define custom edges is, by passing them as template slots. +Your custom edge-types are dynamically resolved to slot-names, meaning an edge with the type `custom` +will expect a slot to have the name `edge-custom`. + +```vue:no-line-numbers{18,26} + + +``` + +### Edge-types object + +You can also define edge-types by passing an object as a prop to the VueFlow component (or as an option to the composable). + +::: warning +When doing this, mark your components as raw (using the designated function from the vue library) to avoid them being turned into reactive objects. +Otherwise, vue will throw a warning in the console. +::: + +```vue:no-line-numbers{5-7,28} + + +``` + +### Custom Edge Props + +Your custom edges are wrapped so that the basic functions like selecting work. +But you might want to extend on that functionality or implement your own business logic inside of edges, therefore +your edges receive the following props: + +| Name | Definition | Type | Optional | +|---------------------|-----------------------------|-------------------|----------| +| id | Edge id | string | false | +| source | The source node id | string | false | +| target | The target node id | string | false | +| sourceNode | The source node | GraphNode | false | +| targetNode | The target node | GraphNode | false | +| sourceX | X position of source handle | number | false | +| sourceY | Y position of source handle | number | false | +| targetX | X position of target handle | number | false | +| targetY | Y position of target handle | number | false | +| type | Edge type | string | true | +| targetPosition | Target handle position | Position | true | +| sourcePosition | Source handle position | Position | true | +| sourceHandleId | Source handle id | string | true | +| targetHandleId | Target handle id | string | true | +| data | Custom data object | Any object | true | +| label | Edge label | string, Component | true | +| labelStyle | Additional label styles | CSSProperties | true | +| labelShowBg | Enable/Disable label bg | boolean | true | +| labelBgPadding | Edge label bg padding | number | true | +| labelBgBorderRadius | Edge label bg border radius | number | true | +| selected | Is edge selected | boolean | true | +| animated | Is edge animated | boolean | true | +| updatable | Is edge updatable | boolean | true | +| markerStart | Edge marker | string | true | +| markerEnd | Edge marker | string | true | +| curvature | Edge path curvature | number | true | + +You can find the TypeDocs [here](https://types.vueflow.dev/interfaces/EdgeProps.html). diff --git a/docs/src/guide/node.md b/docs/src/guide/node.md index 06854757..ad2e186b 100644 --- a/docs/src/guide/node.md +++ b/docs/src/guide/node.md @@ -186,7 +186,7 @@ const nodes = [ ] ``` -Vue Flow will now try to resolve this node type to a component. +Vue Flow will now try to resolve this node-type to a component. First and foremost we will look for a definition in the `nodeTypes` object of the state. After that we will try to resolve the component to a globally registered one that matches the exact name. Finally, we will check if a template slot has been provided to fill the node-type.