Ryan Malloy
26b80f7a0b
Some checks are pending
Create Examples / build (ubuntu-22.04, 3.7) (push) Waiting to run
Create Examples / build (ubuntu-22.04, 3.8) (push) Waiting to run
Create Examples / build (ubuntu-latest, 3.10) (push) Waiting to run
Create Examples / build (ubuntu-latest, 3.11) (push) Waiting to run
Create Examples / build (ubuntu-latest, 3.12) (push) Waiting to run
Create Examples / build (ubuntu-latest, 3.9) (push) Waiting to run
Documents the merged community features (Jinja2 preprocessor, jumper support) with YAML examples, dependency info, and integration notes.
127 lines
4.4 KiB
Markdown
127 lines
4.4 KiB
Markdown
# WireViz Fork — Web UI Integration Guide
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| From | wireviz-integration-agent |
|
|
| To | web-ui-agent |
|
|
| Date | 2026-02-13 |
|
|
| Re | Community features merged for web UI consumption |
|
|
|
|
---
|
|
|
|
## Repository
|
|
|
|
- **Gitea**: https://git.supported.systems/warehack.ing/WireViz
|
|
- **Upstream**: https://github.com/wireviz/WireViz
|
|
- **Testing branch**: `testing/web-ui-features`
|
|
|
|
## Branch Layout
|
|
|
|
```
|
|
master ← upstream mirror (v0.4.1)
|
|
feature/jinja2-preprocessor ← PR #382 (standalone)
|
|
feature/jumpers ← PR #455 (standalone)
|
|
testing/web-ui-features ← combined: jinja2 + jumpers merged together
|
|
```
|
|
|
|
The web UI should target `testing/web-ui-features` as its WireViz dependency.
|
|
|
|
## Merged Features
|
|
|
|
### 1. Jinja2 Preprocessor (upstream PR #382)
|
|
|
|
YAML harness definitions now pass through a Jinja2 templating stage before parsing. This enables:
|
|
|
|
- **`{% include %}`** — compose harnesses from reusable connector/cable definition files
|
|
- **`{% for %}`** — generate repetitive pin/wire definitions with loops
|
|
- **`{% if %}`** — conditional sections (e.g., optional debug connectors)
|
|
- **Template variables** — parameterize harness definitions
|
|
|
|
**CLI additions:**
|
|
- `-I / --include-path` — specify search path for Jinja2 `{% include %}` templates
|
|
- Outputs a `.rendered.yml` alongside other outputs showing the expanded YAML
|
|
|
|
**Web UI implications:**
|
|
- Users can define reusable connector/cable "libraries" as partial YAML files
|
|
- The web UI could offer a template variable input form
|
|
- `.rendered.yml` is useful for debugging — consider showing it in a "debug" panel
|
|
- The Jinja2 `Environment` uses `FileSystemLoader`, so template includes are path-relative
|
|
|
|
**Example:**
|
|
```yaml
|
|
# connectors.yml (reusable library)
|
|
connectors:
|
|
DB9M:
|
|
type: D-Sub
|
|
subtype: male
|
|
pincount: 9
|
|
|
|
# main_harness.yml
|
|
{% include 'connectors.yml' %}
|
|
cables:
|
|
W1:
|
|
wirecount: 4
|
|
colors: [BK, RD, GN, BU]
|
|
```
|
|
|
|
### 2. Jumper Wire Support (upstream PR #455)
|
|
|
|
Major refactor adding jumpers as a first-class component alongside connectors and cables. This is a significant internal rewrite:
|
|
|
|
**What changed:**
|
|
- New `jumpers:` top-level YAML section for defining jumper wires
|
|
- Module renames: `DataClasses.py` -> `wv_dataclasses.py`, `Harness.py` -> `wv_harness.py`
|
|
- New color system: `SingleColor` / `MultiColor` dataclasses replacing string-based colors
|
|
- New BOM system: `BomEntry` / `BomHash` namedtuples for cleaner bill-of-materials
|
|
- New examples: `ex15` and `ex16` demonstrate jumper usage
|
|
- Version bumped to `0.5-dev+refactor`
|
|
|
|
**Web UI implications:**
|
|
- The YAML schema now has a `jumpers:` section — UI forms/editors need to support this
|
|
- BOM output format may differ from upstream v0.4.x — verify your BOM parser
|
|
- Color handling is now richer (multi-color wires) — UI color pickers could leverage this
|
|
- Example files in `examples/` are all regenerated — good test fixtures
|
|
|
|
**Example:**
|
|
```yaml
|
|
connectors:
|
|
J1:
|
|
type: Header
|
|
pincount: 4
|
|
jumpers:
|
|
JP1:
|
|
from: J1
|
|
to: J1
|
|
connections:
|
|
- [1, 2] # jumper between pins 1 and 2
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
The merged branch requires these Python packages beyond upstream:
|
|
- `jinja2` (for template preprocessor)
|
|
- `pillow` (for image handling, from jumpers PR)
|
|
- `pyyaml` (explicit dep, from jumpers PR)
|
|
- `tabulate` (for BOM formatting, from jumpers PR)
|
|
|
|
Install: `pip install jinja2 pillow pyyaml tabulate`
|
|
|
|
Or from the repo: `pip install -e .` (setup.py includes all deps)
|
|
|
|
## Known Considerations
|
|
|
|
1. **Jinja2 + Jumpers interaction**: Not explicitly tested together yet. The Jinja2 stage runs first (text preprocessing), then YAML parsing handles jumpers. Should work fine since they operate at different layers, but worth verifying with a combined test case.
|
|
|
|
2. **Version string**: Shows `0.5-dev+refactor` — the web UI should not rely on version parsing against upstream releases.
|
|
|
|
3. **Generated outputs**: All example SVG/PNG/HTML files in `examples/` and `tutorial/` are from the jumpers PR. The Jinja2 examples are in `examples/jinja/`.
|
|
|
|
---
|
|
|
|
**Next steps for recipient:**
|
|
- [ ] Point web UI's WireViz dependency at `git+https://git.supported.systems/warehack.ing/WireViz@testing/web-ui-features`
|
|
- [ ] Update YAML schema/editor to support `jumpers:` section
|
|
- [ ] Add Jinja2 template support in the UI (include path, template variables)
|
|
- [ ] Test BOM output parsing against the new format
|
|
- [ ] Create a combined test case using both Jinja2 templates and jumper definitions
|