Merge pull request #58 from peterbaumert/feature/svg-renderer

feat: add SVG renderer, patch panel device tab support, improved list table

Author: peterbaumert

README.md

@@ -5,7 +5,7 @@
 ![CI](https://github.com/peterbaumert/netbox-device-view/actions/workflows/test.yml/badge.svg)
 ![License](https://img.shields.io/github/license/peterbaumert/netbox-device-view)
 
-Renders a visual CSS grid representation of a device's physical ports and interfaces directly on the NetBox device detail page.
+Renders a visual CSS grid representation of a device's physical ports and interfaces directly on the NetBox device detail page. An SVG renderer is also available for YAML-based layouts.
 
 ![example](https://github.com/peterbaumert/netbox-device-view/blob/main/docs/example_view.png?raw=true)
 
@@ -88,6 +88,17 @@ The plugin derives a `stylename` for each interface and port:
 
 A DeviceView supports two layout formats. **YAML is preferred** — it is easier to write, validate, and maintain. Legacy CSS is still fully supported for backward compatibility.
 
+### Render modes
+
+A DeviceView also has a **Render Mode** field:
+
+| Mode | Description |
+|------|-------------|
+| `css` (default) | CSS Grid renderer — works with both YAML and legacy CSS layouts |
+| `svg` | SVG renderer — requires a YAML layout; produces a scalable `<svg>` element |
+
+SVG mode produces the same port positions as CSS mode (using `canvas.cell_size` for coordinates) and supports front/rear faces, module variants, hover tooltips, and click targets. Virtual Chassis devices always fall back to CSS mode.
+
 ### YAML layout (recommended)
 
 Fill the **YAML Layout** field with a YAML document describing the device layout. The plugin compiles it to CSS at render time.
@@ -113,13 +124,13 @@ views:
           sections:
             - sequence:
                 kind: interface
-                prefix: "gigabitethernet0-"
+                prefix: "gigabitethernet1-"
                 start: 1
                 count: 12
                 pattern: top-odd
             - sequence:
                 kind: interface
-                prefix: "gigabitethernet0-"
+                prefix: "gigabitethernet1-"
                 start: 13
                 count: 12
                 pattern: top-odd
@@ -135,13 +146,13 @@ variants:
           sections:
             - sequence:
                 kind: interface
-                prefix: "gigabitethernet0-"
+                prefix: "gigabitethernet1-"
                 start: 1
                 count: 12
                 pattern: top-odd
             - sequence:
                 kind: interface
-                prefix: "gigabitethernet0-"
+                prefix: "gigabitethernet1-"
                 start: 13
                 count: 12
                 pattern: top-odd
@@ -153,7 +164,7 @@ variants:
                 pattern: top-odd
 ```
 
-See [`docs/yaml-layout-schema.md`](docs/yaml-layout-schema.md) for the full schema reference and [`examples/yaml/`](examples/yaml/) for ready-made YAML files.
+See [`docs/yaml-layout-schema.md`](docs/yaml-layout-schema.md)
 
 ### CSS layout (legacy)
 
@@ -174,6 +185,18 @@ See [`examples/`](examples/) for ready-made CSS files.
 
 > **Precedence:** if a DeviceView has a YAML layout, it is used and the CSS field is ignored.
 
+### Migrating from CSS to YAML
+
+> [!IMPORTANT]
+> If you have existing DeviceViews with CSS `grid_template_area` layouts and want to switch to the SVG renderer, run the bundled management command to convert them automatically:
+>
+> ```bash
+> cd /opt/netbox/netbox
+> python manage.py css_to_yaml
+> ```
+>
+> This converts every DeviceView that has a CSS layout but no YAML layout, writes the result into the **YAML Layout** field, and leaves the original CSS untouched (so you can roll back by clearing the YAML field). After running it, set **Render Mode → SVG** on the DeviceViews you want to upgrade.
+
 ### Module variants
 
 When a device has an installed module, an extra CSS class matching the module model is added to the device div. In YAML, declare a `variants:` block. In CSS, add a `.deviceview.module{ModelName}.area` rule.
@@ -195,3 +218,9 @@ Add a `.deviceview.module{ModelName}.area` rule to your CSS that includes the ne
 
 **Virtual chassis ports missing**
 Ensure your CSS uses `.area.d{vc_position}` scoped selectors. Each VC member needs its own rule.
+
+**SVG mode shows nothing / falls back to CSS**
+SVG mode requires a YAML layout. If the DeviceView has no YAML layout, or the device is part of a Virtual Chassis, it silently falls back to CSS rendering.
+
+**Port status colours not showing in SVG mode**
+Status classes (`bg-success`, `bg-secondary`, `bg-danger`) are applied by JavaScript using the `data-stylename` attribute. Ensure the static file `netbox_device_view/css/device_view_svg.css` is collected (`python manage.py collectstatic`).

docs/yaml-layout-schema.md

@@ -239,6 +239,74 @@ The YAML renderer produces CSS equivalent to the legacy hand-written format:
 
 ---
 
+## SVG renderer
+
+When a DeviceView has `render_mode` set to `svg`, the plugin uses the same `NormalizedLayout` model to emit an `<svg>` element instead of CSS. The `cell_size` canvas field controls the pixel size of each port cell (default: 20 px if set to 0).
+
+### Coordinate formula
+
+```
+x = PADDING + (col - 1) * (cell_size + GAP)
+y = PADDING + (row - 1) * (cell_size + GAP)
+```
+
+Constants: `PADDING = 6 px`, `GAP = 2 px`, `CORNER_RADIUS = 3 px`, `FONT_SIZE = 7 px`.
+
+### SVG output structure
+
+```xml
+<svg class="dv-svg" viewBox="0 0 W H" xmlns="...">
+  <!-- background -->
+  <rect class="dv-bg" .../>
+
+  <!-- base layer (always present; wrapped in <g class="dv-base"> only when variants exist) -->
+  <g class="dv-port dv-kind-interface <stylename>" data-stylename="<stylename>">
+    <rect class="dv-port-rect" .../>
+    <text class="dv-port-label" ...>Gi0/1</text>
+    <title>gigabitethernet0-1</title>
+  </g>
+  ...
+
+  <!-- variant layers (hidden by default; activated by JS) -->
+  <g class="dv-variant dv-variant-C9300-NM-8X" style="display:none">
+    <g class="dv-port dv-kind-interface tengigabitethernet1-1" data-stylename="tengigabitethernet1-1">
+      ...
+    </g>
+  </g>
+</svg>
+```
+
+### Front/rear faces
+
+Patch panels with separate front and rear views produce **two `<svg>` elements**, each with a `data-face` attribute and a `dv-face-front` / `dv-face-rear` class. The JS in the template shows/hides them based on the active tab.
+
+### CSS classes on port groups
+
+| Class | Meaning |
+|-------|---------|
+| `dv-port` | Any clickable port element |
+| `dv-kind-{kind}` | Element kind (`interface`, `port`, `console-port`, etc.) |
+| `{stylename}` | Derived CSS name — same as grid-area name in CSS mode |
+| `dv-spacer` | Spacer element |
+| `dv-blank` | Blank decorative element |
+| `dv-label` | Text label element |
+| `dv-base` | Wrapper `<g>` for base elements when variants are present |
+| `dv-variant` | Wrapper `<g>` for a module variant layer |
+| `dv-variant-{ModelName}` | Identifies which variant this layer belongs to |
+| `dv-face-front` / `dv-face-rear` | Applied to the top-level `<svg>` for patch panels |
+
+### Interactivity
+
+Status coloring, hover tooltips (Bootstrap), and variant switching are handled by JavaScript injected in the template — the SVG renderer itself emits only structural markup. The `data-stylename` attribute on port `<g>` elements is the hook used by JS to apply status classes (e.g. `bg-success`, `bg-secondary`, `bg-danger`).
+
+### Limitations
+
+- **Virtual Chassis** devices fall back to CSS rendering automatically — SVG mode for VC is not yet supported.
+- SVG mode requires a YAML layout; if no YAML is present the DeviceView silently falls back to CSS.
+- `cell_size: 0` (patch-panel auto-sizing) uses `DEFAULT_CELL = 20 px` in SVG mode since CSS `auto` sizing has no SVG equivalent.
+
+---
+
 ## Examples
 
 Ready-made YAML layouts are in [`examples/yaml/`](../examples/yaml/):

netbox_device_view/api/serializers.py

@@ -11,6 +11,7 @@ class Meta:
             "device_type",
             "grid_template_area",
             "yaml_layout",
+            "render_mode",
             "tags",
             "custom_fields",
             "created",

netbox_device_view/forms.py

@@ -8,7 +8,7 @@
 class DeviceViewForm(NetBoxModelForm):
     class Meta:
         model = DeviceView
-        fields = ("device_type", "grid_template_area", "yaml_layout")
+        fields = ("device_type", "grid_template_area", "yaml_layout", "render_mode")
 
 
 class DeviceViewImportForm(NetBoxModelImportForm):
@@ -20,4 +20,4 @@ class DeviceViewImportForm(NetBoxModelImportForm):
 
     class Meta:
         model = DeviceView
-        fields = ("device_type", "grid_template_area", "yaml_layout")
+        fields = ("device_type", "grid_template_area", "yaml_layout", "render_mode")

netbox_device_view/layout/__init__.py

@@ -3,19 +3,25 @@
 
 Public API
 ----------
-  from netbox_device_view.layout import parse_yaml, render_css, validate_yaml
+  from netbox_device_view.layout import parse_yaml, render_css, render_svg, validate_yaml
 
   # Parse a YAML layout string → NormalizedLayout
   layout = parse_yaml(yaml_text)
 
-  # Render a NormalizedLayout → CSS string
+  # Render a NormalizedLayout → CSS string (CSS Grid renderer)
   css = render_css(layout)
 
+  # Render a NormalizedLayout → SVG string (SVG renderer)
+  svg = render_svg(layout)
+
   # Validate YAML and return a list of error strings (empty = valid)
   errors = validate_yaml(yaml_text)
 
   # Get CSS from a DeviceView record (handles both YAML and legacy)
   css = get_css_for_device_view(device_view_obj)
+
+  # Get SVG from a DeviceView record (requires YAML layout)
+  svg = get_svg_for_device_view(device_view_obj)
 """
 
 from .legacy import wrap_legacy_css
@@ -28,7 +34,8 @@
     PlacedElement,
 )
 from .parser import LayoutParseError, parse, validate
-from .renderers.css_grid import render
+from .renderers.css_grid import render as _render_css
+from .renderers.svg import render as _render_svg
 
 __all__ = [
     # Model
@@ -44,18 +51,20 @@
     "LayoutParseError",
     # Legacy adapter
     "wrap_legacy_css",
-    # Renderer
-    "render",
+    # Renderers
+    "render_css",
+    "render_svg",
     # Convenience aliases
     "parse_yaml",
-    "render_css",
     "validate_yaml",
     "get_css_for_device_view",
+    "get_svg_for_device_view",
 ]
 
 # Convenience aliases
 parse_yaml = parse
-render_css = render
+render_css = _render_css
+render_svg = _render_svg
 validate_yaml = validate
 
 
@@ -78,6 +87,33 @@ def get_css_for_device_view(device_view) -> str:
     """
     if device_view.has_yaml_layout:
         layout = parse(device_view.yaml_layout)
-        return render(layout)
+        return _render_css(layout)
     # Legacy path — return as-is
     return device_view.grid_template_area
+
+
+def get_svg_for_device_view(device_view, variant_name=None) -> str:
+    """
+    Return an SVG string for a DeviceView record.
+
+    Only works when the device view has a YAML layout; returns an empty
+    string for legacy CSS-only records (the caller must fall back to CSS
+    rendering in that case).
+
+    Parameters
+    ----------
+    device_view : DeviceView
+        A DeviceView model instance with ``yaml_layout`` field.
+    variant_name : str | None
+        Optional module variant name to render.
+
+    Returns
+    -------
+    str
+        SVG markup ready for ``{% autoescape off %}`` injection, or ``""``
+        if the record has no YAML layout.
+    """
+    if not device_view.has_yaml_layout:
+        return ""
+    layout = parse(device_view.yaml_layout)
+    return _render_svg(layout, variant_name=variant_name)