diff --git a/README.md b/README.md index 16135791..8659c431 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,74 @@ -# @patternfly/react-topology +# PatternFly Topology -This package provides Topology View components based on [PatternFly 4][patternfly-4] +This package provides the resources necessary to use PatternFly Topology, an open source utility that you can use to create a visual representation of all the applications within your project, their build status, and the components and services associated with them. -Based from https://github.com/patternfly/patternfly-react version 4.91.40 +Topology utilizes some of PatternFly's React components https://github.com/patternfly/patternfly-react. -### Prerequisites +Documentation for Topology and its features is available on [the PatternFly website.](www.patternfly.org/topology/about-topology) -#### Node Environment +## Table of contents +- [Prerequisites](#prerequisites) +- [Installing Topology](#installing-topology) +- [Initial setup and usage](#initial-setup-and-usage) +- [Example](#example) +- [Demo app](#demo-app) -This project currently supports Node [Active LTS](https://github.com/nodejs/Release#release-schedule) releases. Please stay current with Node Active LTS when developing patternfly-react. +## Prerequisites -For example, to develop with Node 8, use the following: +To use Topology, you will need to have both [Node Active LTS](https://github.com/nodejs/Release#release-schedule) and [Yarn](https://yarnpkg.com/) installed. -``` -nvm install 8 -nvm use 8 -``` +1. Install and develop with the most up-to-date version of Node Active LTS. For example, to develop with Node 8, you would use the following commands: -This project also requires a Yarn version of >=1.6.0. The latest version can be installed [here](https://yarnpkg.com/). + ``` + nvm install 8 + nvm use 8 + ``` +1. Install and use version 1.6.0 or later of Yarn. -### Installing +## Installing Topology -``` -yarn add @patternfly/react-topology -``` +Once you have all of the prequisites, you can install the Topology package with Yarn or npm: -or +1. Using Yarn: -``` -npm install @patternfly/react-topology --save -``` + ``` + yarn add @patternfly/react-topology + ``` +1. Using npm: -## Basic Usage + ``` + npm install @patternfly/react-topology --save + ``` -To use React Topology out-of-the-box, you will first need to transform your back-end data into a [Model](https://github.com/patternfly/patternfly-react/blob/main/packages/react-topology/src/types.ts#L16-L20). These model objects contain the information needed to display the nodes and edges. Each node and edge has a set of properties used by PF Topology as well as a data field which can be used to customize the nodes and edges by the application. +## Initial setup and usage -You will then need to declare a controller, which can be initialized via the `useVisualizationController()` method. +To use Topology out of the box, follow these steps: -The `fromModel` method must be called on the controller to create the nodes. `fromModel` will take your data model as a parameter. Your data model should include a `graph` object, on which you will need to set `id` , `type` and `layout`. +1. First transform your back-end data into a [Model](https://github.com/patternfly/react-topology/blob/main/packages/module/src/types.ts) object. This will contain the information needed to display the nodes and edges in your Topology view. Each node and edge contains a set of properties used by Topology, as well as a data field, which Topology can be used to customize the nodes and edges. -To create your topology view component, you can use `TopologyView` to Wrap `` which can accept `state` as a parameter. The state is application specific. It can be any data the application wants to store/retrieve from the controller. Adding state to the surface allows hooks to update when state changes. The state is useful to keep graph state such as selected elements. +1. Declare a controller, which can be initialized via the `useVisualizationController()` method. -Use a controller to wrap your topology view component. In the example below, this is done via the `VisualizationProvider` which consumes the `Controller` via context. +1. Create nodes by calling the `fromModel` method on the controller you initialized. `fromModel` will take the `Model` that you created as a parameter. Your data model should include a `graph` object, on which you will need to set `id` , `type`, and `layout`. -Three `register` methods are accessed by the controller. +1. To create your Topology view component, wrap `TopologyView` around ``, which can accept a `state` parameter. + - The value of state is application specific and should include any data the application wants to store/retrieve from the controller. + - Adding state to `` allows hooks to update when state changes. + - State can also be used to keep track of your graph state, such as selected elements. -The following two must be declared explicitly\: +1. Wrap your `TopologyView` with your controller. In the example below, this is done via the `VisualizationProvider` which consumes the `Controller` via context. -- `registerLayoutFactory`\: This method sets the layout of your topology view (e.g. Force, Dagre, Cola, etc.). You can use `defaultLayoutFactory` as a parameter if your application supports all layouts. You can also update `defaultLayout` to a custom implementation if you only want to support a subset of the available layout options. +1. There are 3 `register` methods that the controller accesses. -- `registerComponentFactory`\: This method lets you customize the components in your topology view (e.g. nodes, groups, and edges). You can use `defaultComponentFactory` as a parameter. + These 2 must be declared explicitly: -The register method below is initialized in `Visualization.ts`, therefore it doesn't need to be declared unless you want to support a custom implementation which modifies the types. + 1. **`registerLayoutFactory`:** Sets the layout of your topology view (e.g. Force, Dagre, Cola, etc.). You can use `defaultLayoutFactory` as a parameter if your application supports all layouts. You can also update `defaultLayout` to a custom implementation if you only want to support a subset of the available layout options. + 1. **`registerComponentFactory`:** Lets you customize the components in your topology view (e.g. nodes, groups, and edges). You can use `defaultComponentFactory` as a parameter. + + The remaining method is initialized in `Visualization.ts`, so it doesn't need to be declared unless you want to support a custom implementation that modifies the types: -- `registerElementFactory`\: This method sets the types of the elements being used (e.g. graphs, nodes, edges). `defaultElementFactory` uses types from `ModelKind` and is exported in `index.ts`. + 3. **`registerElementFactory`:** Sets the types of the elements being used (e.g. graphs, nodes, edges). `defaultElementFactory` uses types from `ModelKind` and is exported in `index.ts`. -#### Example Component Usage +## Example ```ts import * as React from 'react'; @@ -185,3 +198,42 @@ export const TopologyBaselineDemo = React.memo(() => { }); ``` +## Demo app + +To help you better understand and visualize the different Topology components, we have created an interactive demo, [which is contained here.](https://github.com/patternfly/react-topology/tree/main/packages/demo-app-ts) + +Continue reading for instructions on how to build and run the demo app. + +### Prerequisites + +In order to run the demo app, you need to make sure the following prerequisites are met. + +1. Make sure that you have yarn installed, as outlined in [the general Topology prerequisites.](#prerequisites) +1. If you haven’t already, [fork the Topology project.](https://github.com/patternfly/react-topology) + +### Running the demo app + +Once you’ve set up the prerequisites, you can follow these steps to run the docs workspace or the demo app on your local machine + +1. In a terminal, type the following commands to start the docs workspace: + +``` +yarn install +yarn start +``` + +2. In a terminal, type the following commands to navigate to demo-app-ts and launch the demo app: + +``` +cd packages/demo-app-ts +yarn start:demo-app:hot +``` + +3. You will receive a message confirming that the app is running. To view the locally running workspace, visit http://localhost:8008/. + +4. Explore the demo app in your browser: + +![Demo app landing page.](packages/module/patternfly-docs/content/examples/img/topology-demo-app.png) + +## Need help? +If you find a bug, have a request, or have any questions about Topology that aren't answered in our documentation, please [reach out to us on Slack.](https://patternfly.slack.com/archives/CK7URGJ2W) diff --git a/packages/demo-app-ts/README.md b/packages/demo-app-ts/README.md new file mode 100644 index 00000000..c1fc125e --- /dev/null +++ b/packages/demo-app-ts/README.md @@ -0,0 +1,50 @@ +# Topology demo app + +To help you better understand and visualize the different Topology components, we have created an interactive demo, [which is contained here.](https://github.com/patternfly/react-topology/tree/main/packages/demo-app-ts) + +Continue reading for instructions on how to build and run the demo app. + +### Prerequisites + +In order to run the demo app, you need to make sure the following prerequisites are met. + +1. Make sure that you have yarn installed, as outlined in [the general Topology prerequisites.](#prerequisites) +1. Make sure that you have the PatternFly React library installed. [Follow these instructions if you need to install this package.](https://github.com/patternfly/patternfly-react?tab=readme-ov-file#install-and-configure-patternfly-react) +1. If you haven’t already, clone [the Topology project](https://github.com/patternfly/react-topology) and navigate to your local directory: + +``` +git clone https://github.com/patternfly/react-topology.git +cd react-topology +``` + +### Running the demo app + +Once you’ve set up the prerequisites, you can follow these steps to run the demo app on your local machine + +1. In a terminal, type the following commands to start the docs workspace: + +``` +yarn install +yarn start +``` + +2. In a separate terminal window, type the following commands to navigate to demo-app-ts and launch the demo app: + +``` +cd packages/demo-app-ts +yarn start:demo-app:hot +``` + +3. You will receive a message confirming that the app is running, as well the URL that you can enter in your browser to load the app: + +``` + [webpack-dev-server] Project is running at: + [webpack-dev-server] Loopback: http://localhost:3000/ +``` + +4. Explore the demo app in your browser: + +![Demo app landing page.](packages/module/patternfly-docs/content/examples/img/topology-demo-app.png) + +## Need help? +If you find a bug, have a request, or have any questions about Topology that aren't answered in our documentation, please [reach out to us on Slack.](https://patternfly.slack.com/archives/CK7URGJ2W) diff --git a/packages/module/patternfly-docs/content/examples/AboutTopology.md b/packages/module/patternfly-docs/content/examples/AboutTopology.md new file mode 100644 index 00000000..dc9692d4 --- /dev/null +++ b/packages/module/patternfly-docs/content/examples/AboutTopology.md @@ -0,0 +1,106 @@ +--- +id: About Topology +section: topology +sortValue: 1 +sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyGettingStartedDemo.tsx +propComponents: ['VisualizationProvider', 'VisualizationSurface'] +--- + +import { + ColaLayout, + DefaultEdge, + DefaultGroup, + DefaultNode, + EdgeStyle, + GraphComponent, + ModelKind, + NodeShape, + SELECTION_EVENT, + Visualization, + VisualizationProvider, + VisualizationSurface +} from '@patternfly/react-topology'; +import Icon1 from '@patternfly/react-icons/dist/esm/icons/regions-icon'; +import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; + +import './topology-example.css'; + +# Introduction + +**Note:** Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology). + +PatternFly's **Topology** is an open source utility built off of [@patternfly/react-core](https://www.npmjs.com/package/@patternfly/react-core) that you can use to create a visual representation of all the applications within your project, their build status, and the components and services associated with them. Creating these visuals can help document and communicate the intricacies of the processes behind your product. + +To create a Topology view for your application, you can create a simple layout of nodes, which represents your data points, and connecting edges, which represent the relationships between nodes. Beyond this basis, you can continue to customize and enhance your Topology view to fit the specific needs of your application. + +## Prerequisites + +To use Topology, you will need to have both [Node Active LTS](https://github.com/nodejs/Release#release-schedule) and [Yarn](https://yarnpkg.com/) installed. + +1. Install and develop with the most up-to-date version of Node Active LTS. For example, to develop with Node 8, you would use the following commands: + + ``` + nvm install 8 + nvm use 8 + ``` +2. Install and use version 1.6.0 or later of Yarn. + +## Installing Topology + +Once you have all of the prequisites, you can install the Topology package with Yarn or npm: + +1. Using Yarn: + + ``` + yarn add @patternfly/react-topology + ``` +2. Using npm: + + ``` + npm install @patternfly/react-topology --save + ``` + +## Initial setup and usage + +To use Topology out of the box, follow these steps: + +1. First transform your back-end data into a [Model](https://github.com/patternfly/react-topology/blob/main/packages/module/src/types.ts) object. This will contain the information needed to display the nodes and edges in your Topology view. Each node and edge contains a set of properties used by Topology, as well as a data field, which Topology can be used to customize the nodes and edges. + +1. Declare a controller, which can be initialized via the `useVisualizationController()` method. + +1. Create nodes by calling the `fromModel` method on the controller you initialized. `fromModel` will take the `Model` that you created as a parameter. Your data model should include a `graph` object, on which you will need to set `id` , `type`, and `layout`. + +1. To create your Topology view component, wrap `TopologyView` around ``, which can accept a `state` parameter. + - The value of state is application specific and should include any data the application wants to store/retrieve from the controller. + - Adding state to `` allows hooks to update when state changes. + - State cam also be used to keep track of your graph state, such as selected elements. + +1. Wrap your `TopologyView` with your controller. In the example below, this is done via the `VisualizationProvider` which consumes the `Controller` via context. + +1. There are 3 `register` methods that the controller accesses. + + These 2 must be declared explicitly: + + 1. **`registerLayoutFactory`:** Sets the layout of your topology view (e.g. Force, Dagre, Cola, etc.). You can use `defaultLayoutFactory` as a parameter if your application supports all layouts. You can also update `defaultLayout` to a custom implementation if you only want to support a subset of the available layout options. + 1. **`registerComponentFactory`:** Lets you customize the components in your topology view (e.g. nodes, groups, and edges). You can use `defaultComponentFactory` as a parameter. + + The remaining method is initialized in `Visualization.ts`, so it doesn't need to be declared unless you want to support a custom implementation that modifies the types: + + 3. **`registerElementFactory`:** Sets the types of the elements being used (e.g. graphs, nodes, edges). `defaultElementFactory` uses types from `ModelKind` and is exported in `index.ts`. + +1. Create nodes by calling the `fromModel` method on the controller. `fromModel` will take your data model as a parameter. Your data model should include a `graph` object, on which you will need to set `id` , `type`, and `layout`. + +1. To create your topology view component, add a ``, which is a useful context provider. It allows access to the created controller and is required when using the `` component. + +1. Use `` to provide the SVG component required for your topology components. `` can take a state parameter, which enables you to pass your state settings to the controller. + +## Demo app + +To help you better understand and visualize the different Topology components, we have created an interactive demo, [which is contained in the react-topology repository.](https://github.com/patternfly/react-topology/tree/main/packages/demo-app-ts) + +You can run the demo app [by following these instructions.](https://github.com/patternfly/react-topology?tab=readme-ov-file#demo-app) + +### Example + +```ts file='./TopologyGettingStartedDemo.tsx' +``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyAnchors.md b/packages/module/patternfly-docs/content/examples/TopologyAnchors.md index 778d3d23..00112501 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyAnchors.md +++ b/packages/module/patternfly-docs/content/examples/TopologyAnchors.md @@ -5,8 +5,6 @@ sortValue: 13 sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyAnchorsDemo.tsx --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { AbstractAnchor, AnchorEnd, @@ -28,26 +26,34 @@ import { import './topology-example.css'; -### Using custom anchors +# Introduction + +An **anchor** is the point at which an edge connects to a node. + +By default, nodes use a `CenterAnchor`, which refers to the center of the bounds of the node. You can use different anchors for different node shapes. + +## Using custom anchors + +You can customize the start and end points for a node edge by specifying the anchors. -By default, Nodes use a default anchor `CenterAnchor` which use the center of the bounds of the node. A variety of anchors are provided for different node shapes that will set the anchor locations to the edge of the node. +You can specify the SVG element that determines edge locations by using the provided hooks: +- **`usePolygonAnchor`** +- **`useSvgAnchor`** +- **`useAnchor`:** Allows you to specify your own custom anchor or provide a function that returns a specific anchor. + - This is useful for adjusting the anchor based on the node being displayed. -You can customize the start and end locations for edges on a node by specifying the anchors to use on the node. +These hooks accept the following parameters, allowing you to customize the anchor: -Hooks are provided to enable you to specify the SVG element you wish to use for determining the edge locations: `usePolygonAnchor`, and `useSvgAnchor` -These hooks accept parameters allowing you to customize when to use the anchor: -- `points` (usePolygonAnchor only) to specify the points for the polygon -- `AnchorEnd` to specify use for start, end or both -- `type` to specify which edge types to use the anchor for (optional) +- **`points` (for `usePolygonAnchor` only):** The points for the polygon. +- **`AnchorEnd`:** Use for start, end, or both. +- **`type` (optional):** Which edge types to use the anchor for. -The `useAnchor` hook allows you to specify your own custom anchor or provide a function to return a specific anchor (useful for adjusting the anchor based on the node being displayed). +A custom anchor must extend the `AbstractAnchor` class. There are 2 methods used for anchors: -A custom anchor must extend the `AbstractAnchor` class. There are two methods used for anchors: +- **`getLocation(reference: Point): Point`:** Return the location of the anchor, based on the incoming reference point. Default anchors use the point on the node border closest to the reference point. +- **`getReferencePoint(): Point`:** Return the location where outgoing edges initiate from. -- `getLocation(reference: Point): Point` - - Should return the location of the anchor based on the incoming reference point. Default anchors use the point on the node border closest to the reference point. -- `getReferencePoint(): Point` - - Should return the location where outgoing edges would initiate from +### Example ```ts file="./TopologyAnchorsDemo.tsx" ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyContextMenu.md b/packages/module/patternfly-docs/content/examples/TopologyContextMenu.md index a1159210..438bc73b 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyContextMenu.md +++ b/packages/module/patternfly-docs/content/examples/TopologyContextMenu.md @@ -1,12 +1,10 @@ --- -id: Context Menu +id: Context menu section: topology sortValue: 23 sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyContextMenuDemo.tsx --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { ColaLayout, ContextMenuItem, @@ -28,18 +26,21 @@ import { import Icon1 from '@patternfly/react-icons/dist/esm/icons/regions-icon'; import './topology-example.css'; -### Topology with context menus +# Introduction + +A **context menu** displays a list of actions or links related to a graph element. Nodes, edges, and the graph itself can have context menus, which are shown when you select the menu toggle or right-click on a graph element. Context menus are useful to allow users to trigger a process or navigate to a new location. + +## Using context menus -Context menus can be used to show a menu of actions or links related to a graph element that will trigger a process or navigate to a new location. The menus are shown when right clicking on elements in the graph. Nodes, edges, and the graph itself can have context menus. +To add a context menu to a Topology element, you can simply extend `WithContextMenuProps` and use the `withContextMenu` utility when the context menu component is returned in the `componentFactory`. For example, `withContextMenu(() => contextMenu)(MyCustomNode)`. The component should accept 2 parameters: -To add context menus to an element, you can use the `withContextMenu` utility when returning the component in the componentFactory, e.g.: `withContextMenu(() => contextMenu)(MyCustomNode)`. +- **`onContextMenu`:** The function to call upon node selection. Typically the outer container for the component would call `onContextMenu` when clicked. +- **`contextMenuOpen`:** Indicates if the menu is currently open and applies styling to the respective component. -The component should accept two parameters, `onContextMenu` and `contextMenuOpen` (you can simply extend `WithContextMenuProps`). +If you are using `DefaultNode`, these properties can be passed along and will be handled appropriately. -- `onContextMenu`: function to call upon node selection. Typically the outer container for the component would call onContextMenu when clicked. -- `contextMenuOpen`: indicates if the menu is currently open. Updates the drawing of the component to indicate its toggle status. -If you are using `DefaultNode`, these props can be passed along and will be handled appropriately. +### Example ```ts file='./TopologyContextMenuDemo.tsx' ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyControlBar.md b/packages/module/patternfly-docs/content/examples/TopologyControlBar.md index 009f9e9a..f69958e0 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyControlBar.md +++ b/packages/module/patternfly-docs/content/examples/TopologyControlBar.md @@ -1,5 +1,5 @@ --- -id: Control Bar +id: Control bar section: topology sortValue: 31 sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyControlBarDemo.tsx @@ -7,8 +7,6 @@ propComponents: ['TopologyControlBar', 'TopologyView'] --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { action, ColaLayout, @@ -35,65 +33,75 @@ import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; import './topology-example.css'; -### Topology with a control bar +# Introduction -To add a control bar to the topology view, wrap your `VisualizationProvider` with the `TopologyView` component, which accepts `controlBar` as a prop. +A **control bar** adds visualization controls to a Topology view, so that users can more easily explore the graph layout. -Pass the `TopologyControlBar` component to the `controlBar` prop, and pass the `controlButtons` prop into `TopologyControlBar`. Then call the function `createTopologyControlButtons`, which will create the common control buttons via several parameters listed below: +## Using a control bar -1. To render the default control buttons, pass in `defaultControlButtonsOptions`. These default options include: - - Zoom In - - Zoom Out - - Fit to Screen - - Reset View - - Legend +To add a control bar to the Topology view: - You can override these defaults by passing in any of the `defaultControlButtonsOptions` as a parameter, with your updated boolean value of the default option. +1. Wrap your `VisualizationProvider` with the `` component, which accepts `controlBar` as a property. -2. For each button, pass in each action callback method as parameter: +1. Pass the `` component to the `controlBar` property, and pass the `controlButtons` property into ``. - - zoomInCallback: Handle the click on the zoom in button. Eg: - ```noLive - action(() => { - // Zoom in by desired amount - controller.getGraph().scaleBy(4 / 3); - }) - ``` - - zoomOutCallback: Handle the click on the zoom out button. Eg: - ```noLive - action(() => { - // Zoom in out desired amount - controller.getGraph().scaleBy(0.75); - }) +1. Call the `createTopologyControlButtons` function, which will create common control buttons via several parameters: + + To render the default control buttons, pass in `defaultControlButtonsOptions`, which includes: + - Zoom In. + - Zoom Out. + - Fit to Screen. + - Reset View. + - Legend. + + You can override these defaults by passing in any of the `defaultControlButtonsOptions` as a parameter, with your updated boolean value to replace the default option. + + For each control button, pass in each of the following action callback methods as a parameter: + + - **`zoomInCallback`:** Handle clicks on the Zoom In button. For example: + ```noLive + action(() => { + // Zoom in by desired amount + controller.getGraph().scaleBy(4 / 3); + }) ``` - - fitToScreenCallback: Handle click on fit to screen button. Eg: - ```noLive - action(() => { - // Note: The default BaseGraph's fit implementation will not scale to greater - // than 1 so it will not zoom in to enlarge the graph to take up the entire - // viewable area. - - // Fit entire graph in the viewable area with an 80px margin - controller.getGraph().fit(80); - }) + - **`zoomOutCallback`:** Handle clicks on the Zoom Out button. For example: + ```noLive + action(() => { + // Zoom in out desired amount + controller.getGraph().scaleBy(0.75); + }) ``` - - resetViewCallback: Handle the click on the reset view button. Eg: - ```noLive - action(() => { - // BaseGraph's reset implementation will scale back to 1, and re-center - // the graph - controller.getGraph().reset(); + - **`fitToScreenCallback`:** Handle clicks on the Fit to Screen button. For example: + ```noLive + action(() => { + // Note: The default BaseGraph's fit implementation will not scale to greater + // than 1 so it will not zoom in to enlarge the graph to take up the entire + // viewable area. + + // Fit entire graph in the viewable area with an 80px margin + controller.getGraph().fit(80); + }) + ``` + - **`resetViewCallback`:** Handle clicks on the Reset View button. For example: + ```noLive + action(() => { + // BaseGraph's reset implementation will scale back to 1, and re-center + // the graph + controller.getGraph().reset(); // re-run the layout - controller.getGraph().layout(); - }) - ``` - - legendCallback: Handle the click on the legend. Eg: - ```noLive - action(() => { - // application specific code to show a legend (no default support) - }) - ``` + controller.getGraph().layout(); + }) + ``` + - **`legendCallback`:** Handle clicks on the Legend. For example: + ```noLive + action(() => { + // application specific code to show a legend (no default support) + }) + ``` + +### Example ```ts file="./TopologyControlBarDemo.tsx" ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyCustomEdges.md b/packages/module/patternfly-docs/content/examples/TopologyCustomEdges.md index 46a13bcf..73b79af9 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyCustomEdges.md +++ b/packages/module/patternfly-docs/content/examples/TopologyCustomEdges.md @@ -1,13 +1,11 @@ --- -id: Custom Edges +id: Custom edges section: topology sortValue: 12 sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyCustomEdgesDemo.tsx propComponents: ['DefaultEdge'] --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { ColaLayout, CREATE_CONNECTOR_DROP_TYPE, @@ -36,13 +34,21 @@ import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; import './topology-example.css'; -### Using custom edges +# Introduction + +An **edge** is used to indicate a relationship between nodes. Using arrow endpoints can show directional (or bi-directional) relationships. + +## Edge styles + +To customize the style of edges in a Topology view, you can use the following `` properties: +- **`edgeStyle`:** Choose from the `EdgeStyle` enumeration, providing "solid", "dashed", or "dotted". +- **`animationSpeed`:** Choose from the `` enumeration, providing various speeds. + +## Using custom edges -Edges can be styled using properties on `EdgeModel`: -- edgeStyle: choose from the `EdgeStyle` enumeration providing solid, dashed, or dotted -- animationSpeed: choose from the `EdgeAnimationSpeed` enumeration providing various speeds +You can further customize your edges by creating a custom edge component. In your custom component, you can specify a variety of parameters to pass to ``, or you can create an SVG element that will be used to depict edges. -You can also customize your edges further by providing a custom Edge component. In the component you can specify a variety of parameters to pass to `DefaultEdge` or you can create the SVG elements to depict the edge. +### Example ```ts file='./TopologyCustomEdgesDemo.tsx' ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyCustomNodes.md b/packages/module/patternfly-docs/content/examples/TopologyCustomNodes.md index 046566c9..a6c09636 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyCustomNodes.md +++ b/packages/module/patternfly-docs/content/examples/TopologyCustomNodes.md @@ -1,13 +1,11 @@ --- -id: Custom Nodes +id: Custom nodes section: topology sortValue: 11 sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyCustomNodesDemo.tsx propComponents: ['DefaultNode', 'DefaultEdge', 'DefaultGroup'] --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { ColaLayout, DefaultEdge, @@ -28,15 +26,19 @@ import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; import './topology-example.css'; -### Using custom nodes +# Introduction -To create nodes with custom styling, you will need to create a custom node component, which your `customComponentFactory` will return. +A **node** is an element within a Topology view that represents your data point, including processes or services. -To do this, you will need: +## Using custom nodes -- A `CustomNode` component, with `CustomNodeProps` as the generic type, and the destructured `element` as the parameter. The code in the example shows how you can get data from `element` and apply it to the attributes of `DefaultNode`. +To create nodes with custom styling, you will need to create a custom node component, which your `customComponentFactory` will return. + +To do this, you will need a `` component, with `CustomNodeProps` as the generic type and the destructured `element` as the parameter. The code in the following example shows how you can retrieve data from `element` and apply it to the attributes of ``. Within each node in your `NODES` array, you can set `data` to include additional custom attributes. +### Example + ```ts file='./TopologyCustomNodesDemo.tsx' ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyDragDropDemo.md b/packages/module/patternfly-docs/content/examples/TopologyDragDropDemo.md index f3442dbe..2287f0ee 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyDragDropDemo.md +++ b/packages/module/patternfly-docs/content/examples/TopologyDragDropDemo.md @@ -1,11 +1,10 @@ --- -id: Drag and Drop +id: Drag and drop section: topology sortValue: 24 sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyDragDropDemo.tsx propComponents: ['DefaultNode', 'DefaultEdge', 'withDndDrop'] --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) import { ColaLayout, @@ -36,24 +35,32 @@ import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; import './topology-example.css'; -### Drag and Drop +# Introduction -To add drag and drop functionality, in your component factory: +**Drag and drop** functionality allows users to move Topology view elements as needed. -Nodes can be dragged about the canvas by using the `useDragNode` hook or by wrapping the node component with `withDragNode`. -These utilities will provide a `dragNodeRef`. This ref should be added to outer element of the Node where the user can click and drag the node. -`DefaultNode` accepts the `dragNodeRef` and adds it appropriately. +## Drag and drop -Edges can be dragged in order to change the source and/or target of the edge using the `withSourceDrag` and/or `withTargetDrag`. These utilities -will provide a `sourceDragRef` and a `targetDragRef` which should be added to the respective terminals for the edge. `DefaultEdge` -accepts these refs and adds them to the appropriate terminals. +To add drag and drop functionality to your Topology view, add the following in your `ComponentFactory`: +- Nodes can be dragged about the canvas by using the `useDragNode` hook, or by wrapping the `` component with `withDragNode`. + + - These utilities will provide a `dragNodeRef`, which should be added to the outer element of the node, where users can click and drag. + - `DefaultNode` accepts `dragNodeRef` and adds it appropriately. + +- Edges can be dragged in order to change the source and/or target of the edge by using either `withSourceDrag` and/or `withTargetDrag`. + - These utilities will provide a `sourceDragRef` and a `targetDragRef`, which should be added to the respective terminals for the edge. + - `DefaultEdge` accepts these utilities and adds them to the appropriate terminals. + +### Example ```ts file='./TopologyDragDropDemo.tsx' ``` -## Functions -### withDragNode +### Functions + +#### withDragNode + ```noLive /** * Parameters: @@ -65,7 +72,9 @@ accepts these refs and adds them to the appropriate terminals. export const withDragNode = (spec?: DragSourceSpec) => (wrappedComponent: React.FunctionComponent) => React.ComponentType); ``` -### withSourceDrag + +#### withSourceDrag + ```noLive /** * Parameters: @@ -78,7 +87,9 @@ export const withSourceDrag = (spec: DragSourceSpec) => (wrappedComponent: React.FunctionComponent) => React.ComponentType); ``` -### withTargetDrag + +#### withTargetDrag + ```noLive /** * Parameters: @@ -90,7 +101,9 @@ export const withSourceDrag = (spec: DragSourceSpec) => export const withTargetDrag = (spec: DragSourceSpec) => (wrappedComponent: React.FunctionComponent) => React.ComponentType); ``` -### withDndDrop + +#### withDndDrop + ```noLive /** * Parameters: diff --git a/packages/module/patternfly-docs/content/examples/TopologyGettingStarted.md b/packages/module/patternfly-docs/content/examples/TopologyGettingStarted.md deleted file mode 100644 index 2fe8a3d2..00000000 --- a/packages/module/patternfly-docs/content/examples/TopologyGettingStarted.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -id: Getting started -section: topology -sortValue: 1 -sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyGettingStartedDemo.tsx -propComponents: ['VisualizationProvider', 'VisualizationSurface'] ---- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - -To use React Topology out-of-the-box, you will first need to transform your back-end data into a [Model](https://github.com/patternfly/react-topology/blob/main/packages/module/src/types.ts#L16-L20). These model objects contain the information needed to display the nodes and edges. Each node and edge has a set of properties used by PF Topology as well as a data field which can be used to customize the nodes and edges by the application. - -import { - ColaLayout, - DefaultEdge, - DefaultGroup, - DefaultNode, - EdgeStyle, - GraphComponent, - ModelKind, - NodeShape, - SELECTION_EVENT, - Visualization, - VisualizationProvider, - VisualizationSurface -} from '@patternfly/react-topology'; -import Icon1 from '@patternfly/react-icons/dist/esm/icons/regions-icon'; -import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; - -import './topology-example.css'; - -### Getting started with react-topology - -1. Create a new Controller which can be done using the default `Visualization` class. - - It is important to note that three `register` methods are accessed by the controller. - - The following two must be declared explicitly: - - - `registerLayoutFactory`: This method sets the layout of your topology view (e.g. Force, Dagre, Cola, etc.). If your application supports all layouts, use `defaultLayoutFactory` as a parameter. If you only want to support a subset of the available layout options, update `defaultLayout` to a custom implementation . - - - `registerComponentFactory`: This method lets you customize the components in your topology view (e.g. nodes, groups, and edges). You can use `defaultComponentFactory` as a parameter. - - The register method below is initialized in `Visualization.ts`. It doesn't need to be declared unless you support a custom implementation which modifies the types. - - - `registerElementFactory`: This method sets the types of the elements being used (e.g. graphs, nodes, edges). `defaultElementFactory` uses types from `ModelKind` and is exported in `index.ts`. - - -2. The `fromModel` method must be called on the controller to create the nodes. `fromModel` will take your data model as a parameter. Your data model should include a `graph` object, on which you will need to set `id` , `type` and `layout`. - -3. To create your topology view component, add a `VisualizationProvider`, which is a useful context provider. It allows access to the created Controller and is required when using the `VisualizationSurface` component. - -4. You can use the provided `VisualizationSurface` to provide the SVG component required for the topology components. The `VisualizationSurface` can take a state parameter that will allow you to pass your state settings along to the Controller. - -```ts file='./TopologyGettingStartedDemo.tsx' -``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyLayouts.md b/packages/module/patternfly-docs/content/examples/TopologyLayouts.md index 5149fae1..ccca4f6b 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyLayouts.md +++ b/packages/module/patternfly-docs/content/examples/TopologyLayouts.md @@ -4,8 +4,6 @@ section: topology sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyLayoutsDemo.tsx --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { action, createTopologyControlButtons, @@ -45,47 +43,26 @@ import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; import './topology-example.css'; -### Layouts - -Layouts will help to position the nodes on the graph in some manner as defined by the chosen layout. There are many algorithms -for positioning nodes based on many factors (side of nodes, distance between nodes, edges, etc). Patternfy react-topology provides -some layouts that you can choose to customize your topology graph with: - -##### Force - -This layout is built on top of the d3-force layout provided by [d3/d3-force](https://github.com/d3/d3-force). - -##### Dagre - -This layout is built on top of the dagrejs dagre layout provided by [dagrejs/dagre](https://github.com/dagrejs/dagre). - -##### Cola - -This layout is built on top of the WebCola layout provided by [tgdwyer/WebCola](://github.com/tgdwyer/WebCola). This layout uses `force simulation` -by default, but can be turned off by setting the options `layoutOnDrag` flag to false. - -##### ColaGroups - -This layout uses the Cola layout recursively on each group such that the group's children locations are set before setting the group's location -relative to other groups/nodes at its level. - -##### Grid - -This is a basic grid layout. It orders the nodes in a grid making the grid as `square` as possible. -Grid layout works well to distribute nodes without taking into consideration edges - -##### Concentric - -Concentric layouts have better results focused on high connectivity. It places the nodes in a circular pattern. +# Introduction -##### BreadthFirst +A **layout** helps position the nodes in a Topology view, according to different visualization structures. -This layout uses a breadth first algorithm to place the nodes. A BreadthFirst layout may help in these cases, providing -a natural "levels" approach that can be combined with other algorithms to help users to identify the dependencies between elements. +There are many algorithms available for positioning nodes, based on factors like the side of nodes, distance between nodes, edges, and so on. The following layouts are available for you to use in your Topology views. -Note: this first version currently doesn't manage the overflow of a row +- **Force:** Built on top of the d3-force layout provided by [d3/d3-force](https://github.com/d3/d3-force). +- **Dagre:** Built on top of the dagrejs dagre layout provided by [dagrejs/dagre](https://github.com/dagrejs/dagre). +- **Cola:** Built on top of the WebCola layout provided by [tgdwyer/WebCola](://github.com/tgdwyer/WebCola). + - This layout uses `force simulation` by default, but can be turned off by setting the options `layoutOnDrag` flag to "false". +- **ColaGroups:** Uses the cola layout recursively on each group, so that the group's children locations are set before the group's location is set relative to other groups or nodes at its level. +- **Grid:** Orders nodes in a grid, making the grid as `square` as possible. + - This layout works well to distribute nodes without taking edges into consideration. +- **Concentric:** Places nodes in a circular pattern. + - This layout has better results focused on high connectivity. +- **BreadthFirst:** Uses a breadth-first algorithm to place the nodes. + - This layout helps when you need to provide a natural "levels" approach that can be combined with other algorithms, in order to help users to identify the dependencies between elements. + - Note: The current version doesn't manage the overflow of a row. -### Examples +### Example ```ts file='./TopologyLayoutsDemo.tsx' ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyPanZoom.md b/packages/module/patternfly-docs/content/examples/TopologyPanZoom.md index 6aafce80..e541b077 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyPanZoom.md +++ b/packages/module/patternfly-docs/content/examples/TopologyPanZoom.md @@ -1,12 +1,10 @@ --- -id: Pan/Zoom +id: Pan and zoom section: topology sortValue: 22 sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyPanZoomDemo.tsx --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { ColaLayout, DefaultEdge, @@ -28,15 +26,20 @@ import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; import './topology-example.css'; -### Providing pan and zoom on the graph +# Introduction + +**Pan and zoom** functionality provides users with additional methods of navigating in a Topology view. + +## Using pan and zoom -To allow the user to pan and zoom on the graph, you can use the `withPanZoom` utility when returning the graph component in the componentFactory: `withPanZoom(GraphComponent)` +To allow users to pan and zoom in a Topology view, use the `withPanZoom` utility when you return the graph component in the `ComponentFactory` + - For example: `withPanZoom(GraphComponent)` -The component should accept a `panZoomRef` property. This should be the ref on the surface element for the group, the element that will accept the drag or mouse wheel events. +The component should accept a `panZoomRef` property, which should be the ref on the surface element for the group. This is the element that will accept the drag or mouse-wheel events. -Alternatively, you can use the `usePanZoom` hook within the component to retrieve the `panZoomRef` property. +Alternatively, you can use the `usePanZoom` hook within the component to retrieve the `panZoomRef` property. If you are using the provided `GraphComponent`, this property is accepted and will be handled appropriately. -If you are using the provided `GraphComponent`, this property is accepted and will be handled appropriately. +### Example ```ts file='./TopologyPanZoomDemo.tsx' ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyPipelinesGettingStarted.md b/packages/module/patternfly-docs/content/examples/TopologyPipelinesGettingStarted.md index 8cf9b06a..ec4a315d 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyPipelinesGettingStarted.md +++ b/packages/module/patternfly-docs/content/examples/TopologyPipelinesGettingStarted.md @@ -7,8 +7,6 @@ propComponents: ['TaskNode', 'TaskEdge', 'WhenDecorator'] functions: { 'packages/module/src/pipelines/utils/utils.ts': ['getSpacerNodes', 'getEdgesFromNodes'] } --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { TopologyView, Visualization, @@ -36,34 +34,42 @@ import { import './topology-pipelines-example.css'; -### Getting Started with Topology Pipelines +# Introduction + +A **pipeline** displays a series of connected tasks, shown in the order that they occur. -1. Create a new Controller which can be done using the default `Visualization` class. +## Using pipelines - It is important to note that three `register` methods are accessed by the controller. +To create a pipeline: - The following two must be declared explicitly: +1. Create a new controller, using the default `Visualization` class. + - It is important to note that 3 `register` methods are accessed by the controller. - - `registerLayoutFactory`: This method sets the layout of your topology view. For topology pipelines, this shouls use the `PipleineDagreLayout` layout or an extension of it. + The following 2 must be declared explicitly: - - `registerComponentFactory`: This method lets you customize the components in your topology view (e.g. nodes, groups, and edges). - For topology pipelines, nodes and edges should use the elements with a `PipelineNodeModel`, which adds the model field `runAfterTasks`. + - `registerLayoutFactory`: Sets the layout of your Topology view. For pipelines, this should use the `PipelineDagreLayout` layout, or an extension of it. + - `registerComponentFactory`: Lets you customize Topology view elements, such as nodes, groups, and edges. + - Nodes and edges should use a `PipelineNodeModel`, which adds the model field `runAfterTasks`. - The register method below is initialized in `Visualization.ts`. It doesn't need to be declared unless you support a custom implementation which modifies the types. + The remaining method is initialized in `Visualization.ts`. It is optional and only needs to be declared if you support a custom implementation that modifies the types. - - `registerElementFactory`: This method sets the types of the elements being used (e.g. graphs, nodes, edges). `defaultElementFactory` uses types from `ModelKind` and is exported in `index.ts`. + - `registerElementFactory`: Sets the types of the elements being used, such as graphs, nodes, edges. + - `defaultElementFactory` uses types from `ModelKind` and is exported in `index.ts`. 1. Set the task nodes and their relationships using the `runAfterTasks` field. -1. Use the `getSpacerNodes` function to determine the necessary spacer nodes. Spacer nodes are used to aggregate edges to/from multiple task nodes. +1. Use the `getSpacerNodes` function to determine the necessary spacer nodes. Spacer nodes are used to aggregate edges to and from multiple task nodes. + +1. Determine the edges in your model by calling the `getEdgesFromNodes` function, passing in all nodes, including spacer nodes. -1. Determine the edges in your model by calling the `getEdgesFromNodes` function, passing it all the nodes including the spacer nodes. +1. Call the `fromModel` method, passing along all nodes and determined edges. + - Your data model should include a `graph` object, on which you will need to set `id` , `type`, and `layout`. -1. The `fromModel` method can then be called, passing along all nodes and determined edges. Your data model should include a `graph` object, on which you will need to set `id` , `type` and `layout`. +1. To create your Topology view component, add a `VisualizationProvider`, which is a useful context provider that enables access to your controller. It is required when using the `VisualizationSurface` component. -1. To create your topology view component, add a `VisualizationProvider`, which is a useful context provider. It allows access to the created Controller and is required when using the `VisualizationSurface` component. +1. Use `VisualizationSurface` to provide the SVG component required for the Topology components. `VisualizationSurface` can take a "state" parameter, which will allow you to pass your state settings to the controller. -1. You can use the provided `VisualizationSurface` to provide the SVG component required for the topology components. The `VisualizationSurface` can take a state parameter that will allow you to pass your state settings along to the Controller. +### Example ```ts file='./TopologyPipelinesGettingStartedDemo.tsx' ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologySelectable.md b/packages/module/patternfly-docs/content/examples/TopologySelectable.md index 7be9e57a..411e3752 100644 --- a/packages/module/patternfly-docs/content/examples/TopologySelectable.md +++ b/packages/module/patternfly-docs/content/examples/TopologySelectable.md @@ -5,8 +5,6 @@ sortValue: 21 sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologySelectableDemo.tsx --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { ColaLayout, DefaultEdge, @@ -28,21 +26,28 @@ import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; import './topology-example.css'; -### Using selection +# Introduction + +**Selection** functionality enables users to select nodes and edges in a Topology view. -To allow nodes/edges to be selectable, you can use the `withSelection` utility when returning the component in the componentFactory, e.g.: `withSelection()(MyCustomNode)`. +## Using selection -The component should accept two parameters, `onSelect` and `selected` (you can simply extend `WithSelectionProps`). +To allow nodes and edges to be selectable, use the `withSelection` utility when you return the node/edge component in the `ComponentFactory`. + - For example: `withSelection()(MyCustomNode)` -- `onSelect`: function to call upon node selection. Typically the outer container for the component would call onSelect when clicked. -- `selected`: indicates if the element is currently selected. Updates the drawing of the component to indicate its selection status. -Alternatively, you can use the `useSelection` hook within the component to retrieve the same two properties. +The component should accept 2 parameters, `onSelect` and `selected` (you can simply extend `WithSelectionProps`). +- **`onSelect`:** Function to call upon node selection. Typically, the outer container for the component would call `onSelect` when clicked. +- **`selected`:** Indicates if the element is currently selected. Updates the drawing of the component to indicate its selection status. -If you are using `DefaultNode`, these props can be passed along and will be handled appropriately. +Alternatively, you can use the `useSelection` hook within the component to retrieve the same 2 properties. -By default, the application must control selection state. This can be done by adding a listener to the controller for a `SELECTION_EVENT`. The listener would then keep track of the selectedIds and maintain the ids in state and pass that state along to the `VisualizationSurface`. +If you are using `DefaultNode`, these properties can be passed along and will be handled appropriately. + +By default, the application must control the selection state. This can be done by adding a listener to the controller for a `SELECTION_EVENT`. The listener would then keep track of the `selectedIds` and maintain the ids in `state`, which should be passed to the `VisualizationSurface`. Alternatively, you can pass `{ controlled: true }` to the `withSelection` utility or to the `useSelection` hook. +### Example + ```ts file='./TopologySelectableDemo.tsx' ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologySidebar.md b/packages/module/patternfly-docs/content/examples/TopologySidebar.md index 4ac8c538..abe59a76 100644 --- a/packages/module/patternfly-docs/content/examples/TopologySidebar.md +++ b/packages/module/patternfly-docs/content/examples/TopologySidebar.md @@ -29,14 +29,23 @@ import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; import './topology-example.css'; -### Topology with a side bar +# Introduction -To add a sidebar, wrap your `VisualizationProvider` with the `TopologyView` component, which accepts `sideBar` as a prop. +A **side bar** is a menu that is displayed in a side drawer within a Topology view. -Pass the `TopologySideBar` component to the `sideBar` prop. `TopologySideBar` should accept the following props: +## Using a side bar -- `show`: logic to show the sidebar, e.g. if a node is selected -- `onClose`: handle the user closing the window, e.g. unselect the current selection +To add a sidebar to a Topology view: + +1. Wrap your `VisualizationProvider` with the `` component, which accepts `sideBar` as a property. + +1. Pass the `` component to the `sideBar` property. `` should accept the following properties: + - **`show`:** Logic to show the sidebar. + - For example, you may display the side bar when a node is selected. + - **`onClose`:** Handles the behavior that should be triggered when users close the side bar. + - For example, you may deselect the current selection. + +### Example ```ts file='./TopologySidebarDemo.tsx' ``` diff --git a/packages/module/patternfly-docs/content/examples/TopologyToolbar.md b/packages/module/patternfly-docs/content/examples/TopologyToolbar.md index 3bb87155..bcf4393c 100644 --- a/packages/module/patternfly-docs/content/examples/TopologyToolbar.md +++ b/packages/module/patternfly-docs/content/examples/TopologyToolbar.md @@ -6,8 +6,6 @@ sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/modu propComponents: ['TopologyView'] --- -Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology) - import { BadgeLocation, ColaLayout, @@ -39,20 +37,25 @@ import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon'; import './topology-example.css'; -### Topology with a toolbar +# Introduction + +A **toolbar** places controls within a panel at the top of a Topology view. -To add a toolbar to the topology view, wrap your `VisualizationProvider` with the `TopologyView` component, which will accept `viewToolbar` and/or `contextToolbar` as props. +## Using a toolbar -- `contextToolbar`: displayed at the top of the view, should contain components for changing context -- `viewToolbar`: displayed below the context toolbar, should contain components for changing view contents +To add a toolbar to a Topology view, wrap your `VisualizationProvider` with the `` component, which will accept `viewToolbar` and/or `contextToolbar` as properties. + - **`contextToolbar`:** Displayed at the top of the view, containing components for changing context. + - **`viewToolbar`:** Displayed below the context toolbar, containing components for changing view contents. -**Note**: You can set the state on the controller to track values such as the `viewOptions`. +**Note**: You can set the "state" on the controller to track values such as the `viewOptions`. -The GraphElement components can retrieve state from the controller via: +`GraphElement` components can retrieve state from the controller via: `element.getController().getState();` and react to that state accordingly. -You will need to pass in the corresponding props and the related `viewOptions` state values into your custom `DefaultNode` component for all the view options you want to track. +You will need to pass in the corresponding properties and the related `viewOptions` state values to your custom `` component for all view options you want to track. + +### Example ```ts file='./TopologyToolbarDemo.tsx' ``` diff --git a/packages/module/patternfly-docs/content/examples/img/topology-demo-app.png b/packages/module/patternfly-docs/content/examples/img/topology-demo-app.png new file mode 100644 index 00000000..5f3d17f1 Binary files /dev/null and b/packages/module/patternfly-docs/content/examples/img/topology-demo-app.png differ diff --git a/packages/module/patternfly-docs/content/examples/topology-example.css b/packages/module/patternfly-docs/content/examples/topology-example.css index 861fd112..a490d751 100644 --- a/packages/module/patternfly-docs/content/examples/topology-example.css +++ b/packages/module/patternfly-docs/content/examples/topology-example.css @@ -1,12 +1,12 @@ +.ws-extensions-t-about-topology, .ws-extensions-t-anchors, .ws-extensions-t-control-bar, .ws-extensions-t-context-menu, .ws-extensions-t-custom-edges, .ws-extensions-t-custom-nodes, .ws-extensions-t-drag-and-drop, -.ws-extensions-t-getting-started, .ws-extensions-t-layouts, -.ws-extensions-t-panzoom, +.ws-extensions-t-pan-and-zoom, .ws-extensions-t-selection, .ws-extensions-t-sidebar, .ws-extensions-t-toolbar { @@ -22,14 +22,14 @@ } } +.pf-theme-dark .ws-extensions-t-about-topology, .pf-theme-dark .ws-extensions-t-anchors, .pf-theme-dark .ws-extensions-t-control-bar, .pf-theme-dark .ws-extensions-t-context-menu, .pf-theme-dark .ws-extensions-t-custom-edges, .pf-theme-dark .ws-extensions-t-custom-nodes, -.pf-theme-dark .ws-extensions-t-getting-started, .pf-theme-dark .ws-extensions-t-layouts, -.pf-theme-dark .ws-extensions-t-panzoom, +.pf-theme-dark .ws-extensions-t-pan-and-zoom, .pf-theme-dark .ws-extensions-t-selection, .pf-theme-dark .ws-extensions-t-sidebar, .pf-theme-dark .ws-extensions-t-toolbar { diff --git a/packages/module/patternfly-docs/generated/index.js b/packages/module/patternfly-docs/generated/index.js index 6423ff5f..d1292d7a 100644 --- a/packages/module/patternfly-docs/generated/index.js +++ b/packages/module/patternfly-docs/generated/index.js @@ -1,9 +1,21 @@ module.exports = { + '/topology/about-topology/extensions': { + id: "About Topology", + title: "About Topology", + toc: [{"text":"Prerequisites"},{"text":"Installing Topology"},{"text":"Initial setup and usage"},{"text":"Demo app"},[{"text":"Example"}]], + examples: ["Example"], + section: "topology", + subsection: "", + source: "extensions", + tabName: null, + sortValue: 1, + Component: () => import(/* webpackChunkName: "topology/about-topology/extensions/index" */ './topology/about-topology/extensions') + }, '/topology/anchors/extensions': { id: "Anchors", title: "Anchors", - toc: [[{"text":"Using custom anchors"}]], - examples: ["Using custom anchors"], + toc: [{"text":"Using custom anchors"},[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", @@ -12,10 +24,10 @@ module.exports = { Component: () => import(/* webpackChunkName: "topology/anchors/extensions/index" */ './topology/anchors/extensions') }, '/topology/context-menu/extensions': { - id: "Context Menu", - title: "Context Menu", - toc: [[{"text":"Topology with context menus"}]], - examples: ["Topology with context menus"], + id: "Context menu", + title: "Context menu", + toc: [{"text":"Using context menus"},[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", @@ -24,10 +36,10 @@ module.exports = { Component: () => import(/* webpackChunkName: "topology/context-menu/extensions/index" */ './topology/context-menu/extensions') }, '/topology/control-bar/extensions': { - id: "Control Bar", - title: "Control Bar", - toc: [[{"text":"Topology with a control bar"}]], - examples: ["Topology with a control bar"], + id: "Control bar", + title: "Control bar", + toc: [{"text":"Using a control bar"},[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", @@ -36,10 +48,10 @@ module.exports = { Component: () => import(/* webpackChunkName: "topology/control-bar/extensions/index" */ './topology/control-bar/extensions') }, '/topology/custom-edges/extensions': { - id: "Custom Edges", - title: "Custom Edges", - toc: [[{"text":"Using custom edges"}]], - examples: ["Using custom edges"], + id: "Custom edges", + title: "Custom edges", + toc: [{"text":"Edge styles"},{"text":"Using custom edges"},[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", @@ -48,10 +60,10 @@ module.exports = { Component: () => import(/* webpackChunkName: "topology/custom-edges/extensions/index" */ './topology/custom-edges/extensions') }, '/topology/custom-nodes/extensions': { - id: "Custom Nodes", - title: "Custom Nodes", - toc: [[{"text":"Using custom nodes"}]], - examples: ["Using custom nodes"], + id: "Custom nodes", + title: "Custom nodes", + toc: [{"text":"Using custom nodes"},[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", @@ -60,10 +72,10 @@ module.exports = { Component: () => import(/* webpackChunkName: "topology/custom-nodes/extensions/index" */ './topology/custom-nodes/extensions') }, '/topology/drag-and-drop/extensions': { - id: "Drag and Drop", - title: "Drag and Drop", - toc: [[{"text":"Drag and Drop"}],{"text":"Functions"},[{"text":"withDragNode"},{"text":"withSourceDrag"},{"text":"withTargetDrag"},{"text":"withDndDrop"}]], - examples: ["Drag and Drop"], + id: "Drag and drop", + title: "Drag and drop", + toc: [{"text":"Drag and drop"},[{"text":"Example"},{"text":"Functions"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", @@ -71,46 +83,34 @@ module.exports = { sortValue: 24, Component: () => import(/* webpackChunkName: "topology/drag-and-drop/extensions/index" */ './topology/drag-and-drop/extensions') }, - '/topology/getting-started/extensions': { - id: "Getting started", - title: "Getting started", - toc: [[{"text":"Getting started with react-topology"}]], - examples: ["Getting started with react-topology"], - section: "topology", - subsection: "", - source: "extensions", - tabName: null, - sortValue: 1, - Component: () => import(/* webpackChunkName: "topology/getting-started/extensions/index" */ './topology/getting-started/extensions') - }, '/topology/layouts/extensions': { id: "Layouts", title: "Layouts", - toc: [[{"text":"Layouts"},{"text":"Examples"}]], - examples: ["Examples"], + toc: [[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", tabName: null, Component: () => import(/* webpackChunkName: "topology/layouts/extensions/index" */ './topology/layouts/extensions') }, - '/topology/panzoom/extensions': { - id: "Pan/Zoom", - title: "Pan/Zoom", - toc: [[{"text":"Providing pan and zoom on the graph"}]], - examples: ["Providing pan and zoom on the graph"], + '/topology/pan-and-zoom/extensions': { + id: "Pan and zoom", + title: "Pan and zoom", + toc: [{"text":"Using pan and zoom"},[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", tabName: null, sortValue: 22, - Component: () => import(/* webpackChunkName: "topology/panzoom/extensions/index" */ './topology/panzoom/extensions') + Component: () => import(/* webpackChunkName: "topology/pan-and-zoom/extensions/index" */ './topology/pan-and-zoom/extensions') }, '/topology/pipelines/extensions': { id: "Pipelines", title: "Pipelines", - toc: [[{"text":"Getting Started with Topology Pipelines"}],{"text":"Functions"},[{"text":"getSpacerNodes"},{"text":"getEdgesFromNodes"}]], - examples: ["Getting Started with Topology Pipelines"], + toc: [{"text":"Using pipelines"},[{"text":"Example"}],{"text":"Functions"},[{"text":"getSpacerNodes"},{"text":"getEdgesFromNodes"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", @@ -121,8 +121,8 @@ module.exports = { '/topology/selection/extensions': { id: "Selection", title: "Selection", - toc: [[{"text":"Using selection"}]], - examples: ["Using selection"], + toc: [{"text":"Using selection"},[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", @@ -133,8 +133,8 @@ module.exports = { '/topology/sidebar/extensions': { id: "Sidebar", title: "Sidebar", - toc: [[{"text":"Topology with a side bar"}]], - examples: ["Topology with a side bar"], + toc: [{"text":"Using a side bar"},[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions", @@ -145,8 +145,8 @@ module.exports = { '/topology/toolbar/extensions': { id: "Toolbar", title: "Toolbar", - toc: [[{"text":"Topology with a toolbar"}]], - examples: ["Topology with a toolbar"], + toc: [{"text":"Using a toolbar"},[{"text":"Example"}]], + examples: ["Example"], section: "topology", subsection: "", source: "extensions",