Add option for images written at render time (#29)

jkrumbiegel · web-flow · commit 2f01ecf834a4 · 2025-02-28T11:52:42.000+01:00
* Refactor so `Image` can be used to pass objects that are only written to file at render time

* add tests

* add reference
diff --git a/src/WriteDocx.jl b/src/WriteDocx.jl
@@ -480,57 +480,119 @@ Base.@kwdef struct TableLevelCellMargins
     stop::Maybe{Twip} = nothing
 end
 
+struct Path
+    path::String
+end
+
+"""
+    Image(m::MIME, object)
+
+Represents an image of MIME type `m` that can be written to an appropriate file
+when writing out a docx document. The `object` needs to have a `show` method
+for `m` defined for the default behavior to work.
+"""
+struct Image{MIME,T}
+    m::MIME
+    object::T
+end
+
+"""
+    Image(path::String)
+
+Create an `Image` pointing to the file at `path`. The MIME type is determined by file extension.
+"""
+Image(path::String) = Image(Path(path))
+Image(i::Image) = i
+
+function Image(path::Path)
+    if endswith(path.path, r"\.svg"i)
+        Image(MIME"image/svg+xml"(), path)
+    elseif endswith(path.path, r"\.png"i)
+        Image(MIME"image/png"(), path)
+    else
+        throw(ArgumentError("Unknown image file extension, only .svg and .png are allowed. Path was \"$(path.path)\""))
+    end
+end
+
+# avoid writing file again which is already given as a path
+function get_image_file(i::Image{M,Path}, tempdir) where M
+    return i.object.path
+end
+
+file_extension(::Type{MIME"image/svg+xml"}) = "svg"
+file_extension(::Type{MIME"image/png"}) = "png"
+
+function get_image_file(i::Image{M}, tempdir) where M
+    ext = file_extension(M)
+    filepath = joinpath(tempdir, "temp.$(ext)")
+    open(filepath, "w") do io
+        Base.show(io::IO, M(), i.object)
+    end
+    return filepath
+end
+
 """
     InlineDrawing{T}(; image::T, width::EMU, height::EMU)
 
 Create an `InlineDrawing` object which, as the name implies, can be placed inline with
 text inside [`Run`](@ref)s.
 
 WriteDocx supports different types `T` for the `image` argument.
-If `T` is a `String`, `image` is treated as the file path to a .png or .svg image.
+If `T` is a `String`, `image` is treated as the file path to an existing .png or .svg image.
+You can pass an `Image` object which can hold a reference to an object that can be written
+to a file with the desired MIME type at render time.
 You can also use [`SVGWithPNGFallback`](@ref) to place .svg images with better fallback behavior.
 
 Width and height of the placed image are set via `width` and `height`, note that you have to
 determine these values yourself for any image you place, a correct aspect ratio will not
 be determined automatically.
 """
-Base.@kwdef struct InlineDrawing{T}
+struct InlineDrawing{T}
     image::T
     width::EMU
     height::EMU
 end
 
+function InlineDrawing(; image, width, height)
+    InlineDrawing(image, width, height)
+end
+
+InlineDrawing(image::T, width, height) where T = InlineDrawing{T}(image, convert(EMU, width), convert(EMU, height))
+
+# backwards-compatibility, interpret String as path to an image
+function InlineDrawing(path::AbstractString, width, height)
+    InlineDrawing(Image(path), width, height)
+end
+
+# fix ambiguity
+function InlineDrawing(path::AbstractString, width::EMU, height::EMU)
+    InlineDrawing(Image(path), width, height)
+end
+
 is_inline_element(::Type{<:InlineDrawing}) = true
 
 """
-    SVGWithPNGFallback(; svg::String, png::String)
+    SVGWithPNGFallback(; svg, png)
 
-Create a `SVGWithPNGFallback` for the svg file at path `svg` and the fallback png
-file at path `png`.
+Create a `SVGWithPNGFallback` for the svg `svg` and the fallback `png`.
+If `svg` or `png` are `AbstractString`s, they will be treated as paths to image files.
+Otherwise, they should be `Image`s with the appropriate MIME types. Use `SVGImage` and
+`PNGImage` as shortcuts to create these.
 
 Word Online and other services like Slack preview don't work when a simple svg file is added via
 [`InlineDrawing`](@ref)`{String}`.
 `SVGWithPNGFallback` supplies a fallback png file which will be used for display in those situations.
 Note that it is your responsibility to check whether the png file is an accurate
 replacement for the svg.
 """
-struct SVGWithPNGFallback
-    svg::String # path to SVG
-    png::String # path to PNG
-    function SVGWithPNGFallback(; svg::AbstractString, png::AbstractString)
-        svg = convert(String, svg)
-        png = convert(String, png)
-        if !endswith(svg, ".svg")
-            throw(ArgumentError("SVG file needs to end with .svg, got $svg"))
-        end
-        if !endswith(png, ".png")
-            throw(ArgumentError("PNG file needs to end with .png, got $png"))
-        end
-        new(svg, png)
-    end
+struct SVGWithPNGFallback{T1,T2}
+    svg::Image{MIME"image/svg+xml",T1} # path to SVG
+    png::Image{MIME"image/png",T2} # path to PNG
 end
 
-InlineDrawing(image::T, width, height) where T = InlineDrawing{T}(image, convert(EMU, width), convert(EMU, height))
+function SVGWithPNGFallback(; svg, png)
+    SVGWithPNGFallback(Image(svg), Image(png))
+end
 
 @partialkw struct Style{T}
     id::String
@@ -1303,10 +1365,6 @@ struct Relationship
     target::String
 end
 
-struct ImageMedium{T}
-    image::T
-end
-
 struct StyleRel end
 
 function resolve_rel!(x::StyleRel, i, dir, prefix)
@@ -1316,16 +1374,18 @@ function resolve_rel!(x::StyleRel, i, dir, prefix)
     )
 end
 
-function resolve_rel!(x::ImageMedium{String}, i, dir, prefix)
-    imgpath = x.image
-    mediapath = joinpath(dir, "word", "media")
-    mkpath(mediapath)
-    _, extension = splitext(imgpath)
-    targetpath = joinpath(mediapath, "$(prefix)image_$i" * extension)
-    cp(imgpath, targetpath)
-    type = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
-    target = relpath(targetpath, joinpath(dir, "word"))
-    return Relationship(type, target)
+function resolve_rel!(x::Image, i, dir, prefix)
+    mktempdir() do tempdir
+        imgpath = get_image_file(x, tempdir)
+        mediapath = joinpath(dir, "word", "media")
+        mkpath(mediapath)
+        _, extension = splitext(imgpath)
+        targetpath = joinpath(mediapath, "$(prefix)image_$i" * extension)
+        cp(imgpath, targetpath)
+        type = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
+        target = relpath(targetpath, joinpath(dir, "word"))
+        return Relationship(type, target)
+    end
 end
 
 function resolve_rel!(h::Union{Header, Footer}, i, dir, prefix)
@@ -1369,14 +1429,14 @@ end
 
 gather_rels!(rels, zipdir, ::Nothing) = nothing
 
-function gather_rels!(rels, zipdir, i::InlineDrawing{String})
-    add_rel!(rels, ImageMedium(i.image))
+function gather_rels!(rels, zipdir, i::InlineDrawing{<:Image})
+    add_rel!(rels, i.image)
     return
 end
 
-function gather_rels!(rels, zipdir, i::InlineDrawing{SVGWithPNGFallback})
-    add_rel!(rels, ImageMedium(i.image.png))
-    add_rel!(rels, ImageMedium(i.image.svg))
+function gather_rels!(rels, zipdir, i::InlineDrawing{<:SVGWithPNGFallback})
+    add_rel!(rels, i.image.png)
+    add_rel!(rels, i.image.svg)
     return
 end
 
@@ -1637,9 +1697,9 @@ xml(name, pairs::Pair{String,<:Any}...) = xml(name, [], pairs...)
 
 to_xml(xml::E.Node, _) = xml
 
-function get_ablip(i::InlineDrawing{String}, rels)
-    index = rels[ImageMedium(i.image)]
-    ablip = if endswith(i.image, r"\.svg"i)
+function get_ablip(i::InlineDrawing{<:Image{M}}, rels) where M
+    index = rels[i.image]
+    ablip = if M <: MIME"image/svg+xml"
         xml("a:blip", [
             xml("a:extLst", [
                 # this is the empty scaffolding of a png thumbnail that doesn't actually need to be there in modern Word as it seems
@@ -1650,17 +1710,17 @@ function get_ablip(i::InlineDrawing{String}, rels)
                 ], "uri" => "{96DAC541-7B7A-43D3-8B79-37D633B846F1}")
             ])
         ])
-    elseif endswith(i.image, r"\.png"i)
+    elseif M <: MIME"image/png"
         xml("a:blip", "r:embed" => "rId$index")
     else
-        error("Cannot deal with image that is not a .svg or .png.")
+        error("Cannot deal with image of MIME type $M")
     end
     return (; ablip, index)
 end
 
-function get_ablip(i::InlineDrawing{SVGWithPNGFallback}, rels)
-    index_png = rels[ImageMedium(i.image.png)]
-    index_svg = rels[ImageMedium(i.image.svg)]
+function get_ablip(i::InlineDrawing{<:SVGWithPNGFallback}, rels)
+    index_png = rels[i.image.png]
+    index_svg = rels[i.image.svg]
     ablip = 
         xml("a:blip", [
             xml("a:extLst", [
diff --git a/test/references/inline_drawings_with_showable_objects/[Content_Types].xml b/test/references/inline_drawings_with_showable_objects/[Content_Types].xml
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types
+    xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+    <Default Extension="png" ContentType="image/png" />
+    <Default Extension="svg" ContentType="image/svg+xml" />
+    <Default Extension="xml" ContentType="application/xml" />
+    <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml" />
+    <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml" />
+    <Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml" />
+</Types>
diff --git a/test/references/inline_drawings_with_showable_objects/_rels/.rels b/test/references/inline_drawings_with_showable_objects/_rels/.rels
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships
+    xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+    <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
+</Relationships>
diff --git a/test/references/inline_drawings_with_showable_objects/word/_rels/document.xml.rels b/test/references/inline_drawings_with_showable_objects/word/_rels/document.xml.rels
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
+  <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/image_2.svg"/>
+  <Relationship Id="rId3" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/image_3.png"/>
+</Relationships>
diff --git a/test/references/inline_drawings_with_showable_objects/word/document.xml b/test/references/inline_drawings_with_showable_objects/word/document.xml
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing">
+  <w:body>
+    <w:p>
+      <w:pPr/>
+      <w:r>
+        <w:rPr/>
+        <w:drawing>
+          <wp:inline>
+            <wp:extent cx="700000" cy="300000"/>
+            <wp:docPr id="2" name="Picture 2"/>
+            <a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
+              <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
+                <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
+                  <pic:nvPicPr>
+                    <pic:cNvPr id="2" name="Picture 2"/>
+                    <pic:cNvPicPr/>
+                  </pic:nvPicPr>
+                  <pic:blipFill>
+                    <a:blip>
+                      <a:extLst>
+                        <a:ext uri="{28A0092B-C50C-407E-A947-70E740481C1C}"/>
+                        <a:ext uri="{96DAC541-7B7A-43D3-8B79-37D633B846F1}">
+                          <asvg:svgBlip xmlns:asvg="http://schemas.microsoft.com/office/drawing/2016/SVG/main" r:embed="rId2"/>
+                        </a:ext>
+                      </a:extLst>
+                    </a:blip>
+                    <a:stretch>
+                      <a:fillRect/>
+                    </a:stretch>
+                  </pic:blipFill>
+                  <pic:spPr>
+                    <a:xfrm>
+                      <a:off x="0" y="0"/>
+                      <a:ext cx="700000" cy="300000"/>
+                    </a:xfrm>
+                    <a:prstGeom prst="rect">
+                      <a:avLst/>
+                    </a:prstGeom>
+                  </pic:spPr>
+                </pic:pic>
+              </a:graphicData>
+            </a:graphic>
+          </wp:inline>
+        </w:drawing>
+      </w:r>
+      <w:r>
+        <w:rPr/>
+        <w:drawing>
+          <wp:inline>
+            <wp:extent cx="1800000" cy="1097280"/>
+            <wp:docPr id="3" name="Picture 3"/>
+            <a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
+              <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
+                <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
+                  <pic:nvPicPr>
+                    <pic:cNvPr id="3" name="Picture 3"/>
+                    <pic:cNvPicPr/>
+                  </pic:nvPicPr>
+                  <pic:blipFill>
+                    <a:blip r:embed="rId3"/>
+                    <a:stretch>
+                      <a:fillRect/>
+                    </a:stretch>
+                  </pic:blipFill>
+                  <pic:spPr>
+                    <a:xfrm>
+                      <a:off x="0" y="0"/>
+                      <a:ext cx="1800000" cy="1097280"/>
+                    </a:xfrm>
+                    <a:prstGeom prst="rect">
+                      <a:avLst/>
+                    </a:prstGeom>
+                  </pic:spPr>
+                </pic:pic>
+              </a:graphicData>
+            </a:graphic>
+          </wp:inline>
+        </w:drawing>
+      </w:r>
+      <w:r>
+        <w:rPr/>
+        <w:drawing>
+          <wp:inline>
+            <wp:extent cx="700000" cy="300000"/>
+            <wp:docPr id="2" name="Picture 2"/>
+            <a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
+              <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
+                <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
+                  <pic:nvPicPr>
+                    <pic:cNvPr id="2" name="Picture 2"/>
+                    <pic:cNvPicPr/>
+                  </pic:nvPicPr>
+                  <pic:blipFill>
+                    <a:blip r:embed="rId3">
+                      <a:extLst>
+                        <a:ext uri="{28A0092B-C50C-407E-A947-70E740481C1C}"/>
+                        <a:ext uri="{96DAC541-7B7A-43D3-8B79-37D633B846F1}">
+                          <asvg:svgBlip xmlns:asvg="http://schemas.microsoft.com/office/drawing/2016/SVG/main" r:embed="rId2"/>
+                        </a:ext>
+                      </a:extLst>
+                    </a:blip>
+                    <a:stretch>
+                      <a:fillRect/>
+                    </a:stretch>
+                  </pic:blipFill>
+                  <pic:spPr>
+                    <a:xfrm>
+                      <a:off x="0" y="0"/>
+                      <a:ext cx="700000" cy="300000"/>
+                    </a:xfrm>
+                    <a:prstGeom prst="rect">
+                      <a:avLst/>
+                    </a:prstGeom>
+                  </pic:spPr>
+                </pic:pic>
+              </a:graphicData>
+            </a:graphic>
+          </wp:inline>
+        </w:drawing>
+      </w:r>
+    </w:p>
+    <w:sectPr/>
+  </w:body>
+</w:document>
diff --git a/test/references/inline_drawings_with_showable_objects/word/media/image_2.svg b/test/references/inline_drawings_with_showable_objects/word/media/image_2.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="120.214" height="34.848" viewBox="0 0 120.214 34.848"><defs><style>.a{fill:#0035c7;}</style></defs><g transform="translate(0 7.796)"><path d="M4.756,10.78A8.254,8.254,0,0,1,8.186,10c4.444,0,6.86,3.586,6.86,10.6,0,6.783-2.573,10.057-7.016,10.057a7.742,7.742,0,0,1-5.067-1.871v8.264H0V10.39H1.715l1.169,2.417Zm2.729,17.7c2.885,0,4.522-2.027,4.522-7.484v-.936c0-5.691-1.481-7.562-4.366-7.562a7.384,7.384,0,0,0-4.6,1.637v12.63A6.926,6.926,0,0,0,7.484,28.477Z" transform="translate(0 -10)"/><path d="M36.514,10.5h2.962V30.77H37.762l-1.169-2.417L34.877,30.38a9.478,9.478,0,0,1-3.9.78c-3.2,0-5.379-1.793-5.379-6.393V10.5h2.962V25.234c0,2.729,1.247,3.586,3.118,3.586a6.961,6.961,0,0,0,4.756-1.715V10.5Z" transform="translate(-5.642 -10.11)"/><path d="M66.746,10.958A8.141,8.141,0,0,1,70.41,10.1c3.274,0,5.3,1.793,5.3,6.393V30.759H72.749V15.947c0-2.651-1.091-3.43-3.04-3.43a7.383,7.383,0,0,0-4.522,1.715v16.45H62.225V15.947c0-2.651-1.247-3.43-3.04-3.43a7.138,7.138,0,0,0-4.522,1.637V30.681H51.7V10.412h1.715l1.169,2.495L56.3,10.958a8.141,8.141,0,0,1,3.664-.858,6.67,6.67,0,0,1,3.508.858l1.4,2.1Z" transform="translate(-11.395 -10.022)"/><path d="M99.381,16.549c0-2.261-.624-3.976-3.43-3.976a18.77,18.77,0,0,0-5.925,1.247l-.468-2.339A16.146,16.146,0,0,1,96.028,10c4.444,0,6.315,2.261,6.315,7.64v9.9c0,1.091.39,1.4,1.325,1.4h.78l.078,1.559a3.413,3.413,0,0,1-1.949.546,4.071,4.071,0,0,1-1.637-.312l-1.325-2.183L97.821,30.5a9.041,9.041,0,0,1-3.274.624c-3.2,0-5.847-1.481-5.847-5.847,0-4.054,2.183-5.691,7.25-6.237l3.508-.312V16.549Zm0,4.132-3.352.312c-3.2.312-4.522,1.325-4.522,4.132v.234c0,2.495,1.169,3.508,3.664,3.508A5.083,5.083,0,0,0,99.3,27V20.681Z" transform="translate(-19.549 -10)"/><path d="M119.794,19.221c-3.118-.858-4.21-1.169-4.21-3.508,0-2.495,1.247-3.2,3.664-3.2a11.59,11.59,0,0,1,4.678.936V11.036a11.551,11.551,0,0,0-4.834-.936c-3.82,0-6.393,1.871-6.393,5.769,0,3.664,2.027,4.911,4.911,5.691,3.82,1.013,4.6,1.481,4.6,3.9,0,2.573-1.481,3.43-3.976,3.43a13.54,13.54,0,0,1-5.145-1.169l-.39,2.261a12.166,12.166,0,0,0,5.769,1.247c4.444,0,6.627-2.495,6.627-5.925C125.252,21.56,123.381,20.235,119.794,19.221Z" transform="translate(-24.839 -10.022)"/></g><g transform="translate(105.168)"><path class="a" d="M136.849,13.409H134.9L139.266,0h2.183l4.288,13.409h-2.183l-.78-2.573h-5.223Zm3.43-10.836-.546,1.715-1.481,4.834h4.054l-1.4-4.834Z" transform="translate(-134.9)"/><path class="a" d="M151.6,0h2.027V13.409H151.6Z" transform="translate(-138.581)"/></g></svg>
diff --git a/test/references/inline_drawings_with_showable_objects/word/media/image_3.png b/test/references/inline_drawings_with_showable_objects/word/media/image_3.png
diff --git a/test/references/inline_drawings_with_showable_objects/word/styles.xml b/test/references/inline_drawings_with_showable_objects/word/styles.xml
diff --git a/test/runtests.jl b/test/runtests.jl
