From 38995ea9e969854eefbff990bac1d609bcb06400 Mon Sep 17 00:00:00 2001 From: KV Date: Sun, 26 May 2024 17:28:09 +0200 Subject: [PATCH 1/6] Add HTML template placeholders for filename This will e.g. enable users to replace the SVG diagram with PNG, that is needed as a work-around when the SVG output from Graphviz is not looking good. Suggested as work-around for Graphviz bug in https://github.com/wireviz/WireViz/issues/175#issuecomment-2132206026 --- src/wireviz/wv_html.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/wireviz/wv_html.py b/src/wireviz/wv_html.py index 763da9d7..6fde7cdd 100644 --- a/src/wireviz/wv_html.py +++ b/src/wireviz/wv_html.py @@ -81,6 +81,9 @@ def generate_html_output( "": options.fontname, "": wv_colors.translate_color(options.bgcolor, "hex"), "": svgdata, + # TODO: "": base64 of png file + "": str(filename), + "": Path(filename).stem, "": bom_html, "": bom_html_reversed, "": "1", # TODO: handle multi-page documents From 957bb22fbb33fb194bf7472aec48db58856a2924 Mon Sep 17 00:00:00 2001 From: KV Date: Fri, 31 May 2024 22:24:45 +0200 Subject: [PATCH 2/6] Add HTML template placeholder for diagram_png_base64 This will enable users to replace the SVG diagram with an embedded PNG, that is an improved work-around when the SVG output from Graphviz is not looking good. Suggested as work-around for Graphviz bug in https://github.com/wireviz/WireViz/issues/175#issuecomment-2132206026 --- src/wireviz/svgembed.py | 14 ++++++++++++++ src/wireviz/wv_html.py | 3 ++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/src/wireviz/svgembed.py b/src/wireviz/svgembed.py index ab6b9f1e..c8d637c8 100644 --- a/src/wireviz/svgembed.py +++ b/src/wireviz/svgembed.py @@ -8,6 +8,20 @@ mime_subtype_replacements = {"jpg": "jpeg", "tif": "tiff"} +# TODO: Share cache and code between data_URI_base64() and embed_svg_images() +def data_URI_base64(file: Union[str, Path], media: str = "image") -> str: + """Return Base64-encoded data URI of input file.""" + file = Path(file) + b64 = base64.b64encode(file.read_bytes()).decode("utf-8") + uri = f"data:{media}/{get_mime_subtype(file)};base64, {b64}" + # print(f"data_URI_base64('{file}', '{media}') -> {len(uri)}-character URI") + if len(uri) > 65535: + print( + "data_URI_base64(): Warning: Browsers might have different URI length limitations" + ) + return uri + + def embed_svg_images(svg_in: str, base_path: Union[str, Path] = Path.cwd()) -> str: images_b64 = {} # cache of base64-encoded images diff --git a/src/wireviz/wv_html.py b/src/wireviz/wv_html.py index 6fde7cdd..e939c6f2 100644 --- a/src/wireviz/wv_html.py +++ b/src/wireviz/wv_html.py @@ -6,6 +6,7 @@ from wireviz import APP_NAME, APP_URL, __version__, wv_colors from wireviz.DataClasses import Metadata, Options +from wireviz.svgembed import data_URI_base64 from wireviz.wv_gv_html import html_line_breaks from wireviz.wv_helper import ( flatten2d, @@ -81,7 +82,7 @@ def generate_html_output( "": options.fontname, "": wv_colors.translate_color(options.bgcolor, "hex"), "": svgdata, - # TODO: "": base64 of png file + "": data_URI_base64(f"{filename}.png"), "": str(filename), "": Path(filename).stem, "": bom_html, From 7b0b89396bd3e65594b599a423ee4b82cd71e7b2 Mon Sep 17 00:00:00 2001 From: KV Date: Fri, 31 May 2024 23:03:42 +0200 Subject: [PATCH 3/6] Avoid reading diagram file to embed unless used Add local replacement_if_used() that call function to read the file only when needed and append the return value as replacement. --- src/wireviz/wv_html.py | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/src/wireviz/wv_html.py b/src/wireviz/wv_html.py index e939c6f2..176d2303 100644 --- a/src/wireviz/wv_html.py +++ b/src/wireviz/wv_html.py @@ -2,7 +2,7 @@ import re from pathlib import Path -from typing import Dict, List, Union +from typing import Callable, Dict, List, Union from wireviz import APP_NAME, APP_URL, __version__, wv_colors from wireviz.DataClasses import Metadata, Options @@ -37,12 +37,12 @@ def generate_html_output( html = open_file_read(templatefile).read() - # embed SVG diagram - with open_file_read(f"{filename}.tmp.svg") as file: - svgdata = re.sub( + # embed SVG diagram (only if used) + def svgdata() -> str: + return re.sub( "^<[?]xml [^?>]*[?]>[^<]*]*>", "", - file.read(), + open_file_read(f"{filename}.tmp.svg").read(), 1, ) @@ -81,8 +81,6 @@ def generate_html_output( "": f"{APP_NAME} {__version__} - {APP_URL}", "": options.fontname, "": wv_colors.translate_color(options.bgcolor, "hex"), - "": svgdata, - "": data_URI_base64(f"{filename}.png"), "": str(filename), "": Path(filename).stem, "": bom_html, @@ -91,6 +89,16 @@ def generate_html_output( "": "1", # TODO: handle multi-page documents } + def replacement_if_used(key: str, func: Callable[[], str]) -> None: + """Append replacement only if used in html.""" + if key in html: + replacements[key] = func() + + replacement_if_used("", svgdata) + replacement_if_used( + "", lambda: data_URI_base64(f"{filename}.png") + ) + # prepare metadata replacements if metadata: for item, contents in metadata.items(): From 41af41bdb2264cb3dbe1e301624f4d8327dfd35c Mon Sep 17 00:00:00 2001 From: KV Date: Wed, 5 Jun 2024 21:56:42 +0200 Subject: [PATCH 4/6] Add templates README Describe the HTML Output Templates, how they are specified, and placeholder usage within these templates. --- src/wireviz/templates/README.md | 51 +++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 src/wireviz/templates/README.md diff --git a/src/wireviz/templates/README.md b/src/wireviz/templates/README.md new file mode 100644 index 00000000..41f9e0ac --- /dev/null +++ b/src/wireviz/templates/README.md @@ -0,0 +1,51 @@ +# HTML Output Templates + +This is the standard folder where WireViz looks for an HTML output template file. + +## Which HTML Output Template File is Used? + +A named HTML output template can optionally be specified as +`metadata.template.name` in the YAML input: +```yaml +metadata: + template: + name: din-6771 +``` +In the case above, WireViz will search for a template file named +`din-6771.html` in these folders: +1. In the same folder as the YAML input file. +2. In this standard template folder. + +If no HTML output template is specified, the `simple` template is assumed +(i.e. filename `simple.html`, and in this case, +only the standard template folder is searched). + +## Placeholders in HTML Output Templates + +HTML output template files might contain placeholders that will be replaced by +generated text by WireViz when producing HTML output based on such a template. +A placeholder starts with ``. +Note that there must be one single space between `--` and `%` at both ends. + +| Placeholder | Replaced by | +| --- | --- | +| `` | The application name, version, and URL | +| `` | The value of `options.fontname` | +| `` | The HEX color translation of `options.bgcolor` | +| `` | The output path and filename without extension | +| `` | The output filename without path nor extension | +| `` | BOM as HTML table with headers at top | +| `` | Reversed BOM as HTML table with headers at bottom | +| `` | `1` (multi-page documents not yet supported) | +| `` | `1` (multi-page documents not yet supported) | +| `` | Embedded SVG diagram as valid HTML | +| `` | Embedded base64 encoded PNG diagram as URI | +| `` | String or numeric value of `metadata.{item}` | +| `` | Category number `{i}` within dict value of `metadata.{item}` | +| `` | Value of `metadata.{item}.{category}.{key}` | + +Note that `{item}`, `{category}` and `{key}` in the description above can be +any valid YAML key, and `{i}` is an integer representing the 1-based index of +category entries in a dict `metadata.{item}` entry. +The `{` and `}` characters are not literally part of the syntax, just used in +this documentation to enclose the variable parts of the keywords. From 0378d1feab0bffd16ae4e653130671dec54a507c Mon Sep 17 00:00:00 2001 From: KV Date: Wed, 5 Jun 2024 22:21:40 +0200 Subject: [PATCH 5/6] Rename diagram_png_base64 to diagram_png_b64 --- src/wireviz/templates/README.md | 8 ++++---- src/wireviz/wv_html.py | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/wireviz/templates/README.md b/src/wireviz/templates/README.md index 41f9e0ac..a172aa4a 100644 --- a/src/wireviz/templates/README.md +++ b/src/wireviz/templates/README.md @@ -39,10 +39,10 @@ Note that there must be one single space between `--` and `%` at both ends. | `` | `1` (multi-page documents not yet supported) | | `` | `1` (multi-page documents not yet supported) | | `` | Embedded SVG diagram as valid HTML | -| `` | Embedded base64 encoded PNG diagram as URI | -| `` | String or numeric value of `metadata.{item}` | -| `` | Category number `{i}` within dict value of `metadata.{item}` | -| `` | Value of `metadata.{item}.{category}.{key}` | +| `` | Embedded base64 encoded PNG diagram as URI | +| `` | String or numeric value of `metadata.{item}` | +| `` | Category number `{i}` within dict value of `metadata.{item}` | +| `` | Value of `metadata.{item}.{category}.{key}` | Note that `{item}`, `{category}` and `{key}` in the description above can be any valid YAML key, and `{i}` is an integer representing the 1-based index of diff --git a/src/wireviz/wv_html.py b/src/wireviz/wv_html.py index 176d2303..4941e94a 100644 --- a/src/wireviz/wv_html.py +++ b/src/wireviz/wv_html.py @@ -96,7 +96,7 @@ def replacement_if_used(key: str, func: Callable[[], str]) -> None: replacement_if_used("", svgdata) replacement_if_used( - "", lambda: data_URI_base64(f"{filename}.png") + "", lambda: data_URI_base64(f"{filename}.png") ) # prepare metadata replacements From f6423c4f6e0ad2248b8d8c5f7be83d6d32fafc86 Mon Sep 17 00:00:00 2001 From: KV Date: Mon, 10 Jun 2024 00:05:19 +0200 Subject: [PATCH 6/6] Add link from syntax.md to HTML output templates --- docs/syntax.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/syntax.md b/docs/syntax.md index de672847..265427d2 100644 --- a/docs/syntax.md +++ b/docs/syntax.md @@ -353,6 +353,7 @@ If any component is defined in the `connectors` or `cables` sections but not ref # If no value is specified for 'title', then the # output filename without extension is used. ``` +See [HTML Output Templates](../src/wireviz/templates/) for how metadata entries can be inserted into the HTML output. ## Options