DOCSEARCHbyAlgolia
Submit Docs

Z.Blazor.Diagrams Documentation

repository·develop·Indexed 23 days ago

https://github.com/blazor-diagrams/blazor.diagrams

A highly customizable and extensible diagramming library for Blazor Server-side and WASM. It features a strict separation between data models (nodes, links, groups) and UI widgets, allowing for advanced customization of appearance and behavior. The library is distributed via NuGet through Z.Blazor.Diagrams.Core, Z.Blazor.Diagrams, and Z.Blazor.Diagrams.Algorithms packages.

Tokens
5.1K
Snippets
21
Records
32
Agent score
80%

What's inside Z.Blazor.Diagrams

  2. Key features of Z.Blazor.Diagrams

    develop

    Z.Blazor.Diagrams provides a comprehensive set of features for building advanced diagrams:

    • Interaction: Touch support, panning, zooming (including zoom-to-fit), and multi-selection (including region selection).
    • Connectivity: Links between nodes, ports, and even other links, supported by link routers, path generators, markers, and labels.
    • Organization: Groups are first-class citizens with the same features as nodes. Supports Snap to Grid.
    • Customization: Fully customizable nodes, links, and groups. Behaviors (like link dragging or model deletion) are replaceable ('hackable').
    • Performance: Includes virtualization (only drawing visible nodes) and is optimized for WebAssembly.
    • Advanced Tools: Diagram overview/navigator for large diagrams, locking mechanisms (read-only mode), and specialized algorithms.

  3. Understand the Z.Blazor.Diagrams architecture

    develop

    Z.Blazor.Diagrams is designed with a strict separation between the Data Layer (Models) and the UI Layer (Widgets).

    • Models: Represent the diagram structure (nodes, links, groups). This separation allows you to save snapshots, mutate models, or perform logic independently of how the diagram is rendered.
    • Widgets: Handle the visual representation and user interaction.

    This architecture enables high customizability: you can replace default UI by providing your own Blazor components or using CSS, and you can change library behavior by replacing default behaviors with custom ones. The library uses an SVG layer for links/nodes and an HTML layer for nodes to maximize customizability.

  5. Important constraints and behaviors of stickyfilljs

    develop

    When using stickyfilljs, keep the following behaviors and limitations in mind:

    Capabilities

    • Supports top-positioned stickies only.
    • Works in IE9+.
    • Mimics native behavior: uses the parent node as a boundary box and respects top and margin-bottom values.

    Limitations

    • No side stickies: Does not support left, right, or bottom positioning.
    • No overflowed blocks: Does not work inside elements with overflow settings that create a new scrolling context.
    • No CSS parsing: You must manually call the API on elements.

    Layout & Overflow Tips

    • Overflow Ancestors: Any ancestor with an overflow value other than visible (e.g., auto, scroll, hidden) will act as the boundary for the sticky element. Scrolling that ancestor will cause the element to stick, rather than scrolling the window.
    • Margin-bottom: You can adjust the bottom limit of the sticky area by setting a positive or negative margin-bottom on the sticky element.

  6. Integrate Z.Blazor.Diagrams into a Blazor App

    develop

    To set up Z.Blazor.Diagrams, you must include the library's CSS and JavaScript assets in your host page (e.g., _Host.cshtml).

    1. Add the core library stylesheet to the <head> section.
    2. Add the default styling stylesheet to the <head> section if you want to use the library's default look.
    3. Add the library's JavaScript file to the <body> section.
    <!-- in the head element -->
<link href="_content/Z.Blazor.Diagrams/style.min.css" rel="stylesheet"/>

<!-- if you want the default styling -->
<link href="_content/Z.Blazor.Diagrams/default.styles.min.css" rel="stylesheet"/>

<!-- in the body element -->
<script src="_content/Z.Blazor.Diagrams/script.min.js"></script>

  8. Use Open Iconic Icon Fonts

    develop

    Open Iconic provides webfont stylesheets for standalone use, Bootstrap, and Foundation.

    Standalone

    Link the default stylesheet and use the oi class with a data-glyph attribute.

    Bootstrap

    Link the Bootstrap-specific stylesheet and use the oi oi-icon-name pattern.

    Foundation

    Link the Foundation-specific stylesheet and use the fi-icon-name pattern.

    <!-- Standalone -->
<link href="/open-iconic/font/css/open-iconic.css" rel="stylesheet">
<span class="oi" data-glyph="icon-name" title="icon name" aria-hidden="true"></span>

<!-- Bootstrap -->
<link href="/open-iconic/font/css/open-iconic-bootstrap.css" rel="stylesheet">
<span class="oi oi-icon-name" title="icon name" aria-hidden="true"></span>

<!-- Foundation -->
<link href="/open-iconic/font/css/open-iconic-foundation.css" rel="stylesheet">
<span class="fi-icon-name" title="icon name" aria-hidden="true"></span>

  9. Use Open Iconic SVG Sprites

    develop

    The SVG sprite allows you to load all icons in a single request. To use it, place a <use> tag inside an <svg> element, referencing the icon ID from the sprite file.

    Styling Tips:

    • Sizing: Set equal width and height on the <svg> tag. All icons are square.
    • Coloring: Use the CSS fill property on the <use> tag to change the icon color.
    • Best Practice: Add a general class to the <svg> tag for shared styles and a unique class to the <use> tag for specific icon styling.
    <svg class="icon">
  <use xlink:href="open-iconic.svg#account-login" class="icon-account-login"></use>
</svg>

  11. How to integrate a graph layout algorithm

    develop

    To implement custom graph layout logic in Blazor.Diagrams, you should follow a three-step methodology that involves converting the diagram data to a compatible graph structure, running a layout algorithm, and then applying the results back to the diagram nodes.

    Integration Methodology

    1. Convert Data: Convert your Z.Blazor.Diagram models into a format compatible with a graph library (e.g., QuikGraph).
    2. Run Algorithm: Execute the desired layout algorithm (e.g., using GraphShape) to calculate the new coordinates.
    3. Update Positions: Iterate through your NodeModel instances and update their positions based on the algorithm's output.

  12. Configure DiagramCanvas container sizing

    develop

    The DiagramCanvas component requires its parent container to have a fixed width and height to render correctly. If the parent has no defined dimensions, the diagram will not be visible.

    Common practice is to use viewport units (like 100vw and 100vh) or a CSS class that ensures the container occupies the available space.

    <div style="width:100vw; height: 100vh">
  <CascadingValue Value="Diagram">
    <DiagramCanvas></DiagramCanvas>
  </CascadingValue>
</div>