mattcasters opened a new issue, #8346:
URL: https://github.com/apache/hop/issues/8346
## Problem
In Apache Hop today, visual diagram export is tightly coupled and limited in
several ways:
1. **GUI Export is hard-coded to Pipelines and Workflows**:
`HopGuiFileDelegate.exportToSvg()` only inspects
`HopGui.getActivePipelineGraph()` and `HopGui.getActiveWorkflowGraph()`. Custom
file type handlers (`IHopFileTypeHandler`) and perspective editors—such as data
models, architecture graphs, execution maps, or custom plugin canvases—cannot
participate in export, even when declaring `CAPABILITY_EXPORT_TO_SVG`.
2. **Hard-coded to SVG only**:
There is no mechanism to export diagrams to other popular and modern
documentation/diagram formats such as **Mermaid** (`.mmd` / markdown fenced
blocks), **PDF** (vector documents), **PlantUML** (`.puml`), or **Draw.io**
(`.drawio`).
3. **No generic CLI export command**:
Exporting diagrams from CI/CD or scripts requires one-off commands or
plugins (such as `hop svg`), rather than a unified, extensible CLI export tool
(`hop export`).
4. **No plugin extension point for exporters**:
Plugins cannot contribute new export targets or format converters without
modifying Hop core.
## Proposal
Introduce an extensible **Diagram Exporter** plugin architecture in Apache
Hop, separating the **Subject** (what is exported), the **Format** (the target
representation), and the **Context** (GUI dialog, CLI command, workflow action,
or batch export).
### 1. Plugin Annotation & Type (`hop-core`)
```java
@PluginMainClassType(IDiagramExporter.class)
@PluginAnnotationType(DiagramExporter.class)
public class DiagramExporterPluginType extends
BasePluginType<DiagramExporter> {
...
}
```
```java
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface DiagramExporter {
String id();
String name();
String description() default "";
String format(); // e.g. SVG, PDF, MERMAID, PLANTUML, DRAWIO
String fileExtension(); // default extension without dot, e.g. "svg", "mmd"
String[] fileFilterNames() default {};
Class<?>[] supportedSubjectTypes() default {};
}
```
### 2. Core Interface & Context (`hop-core`)
```java
public interface IDiagramExporter<T> {
String getId();
String getName();
DiagramExportFormat getFormat();
/** Checks if this exporter can handle the specified subject instance. */
boolean supportsSubject(Object subject);
/** Performs the export to the specified target. */
DiagramExportResult export(T subject, DiagramExportOptions options,
IExportContext context)
throws HopException;
/** Optional options bean class for GuiCompositeWidgets dialog
presentation. */
default Class<? extends DiagramExportOptions> getOptionsClass() {
return DiagramExportOptions.class;
}
}
```
`IExportContext` provides variables (`IVariables`), metadata provider
(`IHopMetadataProvider`), logging (`ILogChannel`), execution environment
(`GUI`, `CLI`, `WORKFLOW`, `BATCH`), and cancellation / progress handles.
`DiagramExportService` acts as the discovery and execution facade:
- `List<IPlugin> findExportersForSubject(Object subject)`
- `DiagramExportResult export(Object subject, DiagramExportOptions options,
IExportContext context)`
- `DiagramExportResult exportFile(String filename, DiagramExportOptions
options, IExportContext context)`
### 3. Built-in Hop Core Exporters
Provide initial built-in exporters in Apache Hop:
- **Pipeline to SVG**: delegates to `PipelineSvgPainter`.
- **Workflow to SVG**: delegates to `WorkflowSvgPainter`.
- **Pipeline to Mermaid (`.mmd`)**: generates `flowchart LR` of transforms
and hops (with hop types / conditional labels).
- **Workflow to Mermaid (`.mmd`)**: generates `flowchart TD` of actions and
hops (success, failure, unconditional).
- (Extensible for community plugins): PDF vector exporter, PlantUML,
Draw.io, etc.
### 4. Generic Hop GUI Export Dialog (`hop-ui`)
- `DiagramExportDialog`: built strictly using
`GuiCompositeWidgets.addScrolledComposite(...)` with pinned OK/Cancel button
bar and `@GuiPlugin` annotated options bean.
- When invoked, inspects the active editor / `IHopFileTypeHandler`,
discovers all registered `DiagramExporter` plugins that support that subject,
and presents a format selector, target filename picker (resolving through
`HopVfs`), and format-specific options (magnification, include notes, style).
- Integrated into:
- `HopGuiFileDelegate`: File -> "Export..." (or enhanced "Export to SVG /
Other formats...")
- Graph context menus and toolbars.
### 5. Unified CLI Tool (`hop export`)
A new `@HopCommand(id = "export")` command in Hop CLI:
```bash
# Export single pipeline to Mermaid:
hop export -f pipelines/process-orders.hpl --format mermaid -o
diagrams/process-orders.mmd -e my-project
# Export single workflow to SVG:
hop export -f workflows/run-all.hwf --format svg -o diagrams/run-all.svg -e
my-project
# Batch export an entire folder:
hop export -s pipelines/ -t diagrams/ --format mermaid --recursive -e
my-project
# List available exporters and supported subjects:
hop export --list-exporters
```
## Community & Plugin Benefits
- Third-party plugins (such as `hopper-edw` for Data Vault, Dimensional
Models, Source Models, and Architecture Maps) can seamlessly register their own
diagram exporter plugins.
- CI/CD pipelines can generate living documentation (Mermaid in
GitHub/GitLab READMEs, PDFs for architecture reviews, SVGs for websites).
## Tasks / Acceptance Criteria for Hop 2.20
- [ ] Add `DiagramExporter` annotation, `IDiagramExporter` interface,
`DiagramExportFormat`, `DiagramExportOptions`, `DiagramExportResult`, and
`IExportContext` in `hop-core`.
- [ ] Add `DiagramExporterPluginType` in `hop-core` and register in
`PluginRegistry`.
- [ ] Implement `DiagramExportService` for exporter discovery and dispatch.
- [ ] Add built-in exporters: `PipelineSvgDiagramExporter`,
`WorkflowSvgDiagramExporter`, `PipelineMermaidDiagramExporter`,
`WorkflowMermaidDiagramExporter`.
- [ ] Create `DiagramExportDialog` and `DiagramExportDialogModel` in
`hop-ui` using `GuiCompositeWidgets`.
- [ ] Hook `DiagramExportDialog` into `HopGuiFileDelegate` for active file
handlers.
- [ ] Implement `DiagramExportCommand` (`hop export`) in `hop-cmd` / plugins.
- [ ] Add unit tests for plugin registration, format lookup, and SVG/Mermaid
exports.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
