DocumentAssembler: Support for Images

[BrettBailey]

It would be nice if there was an easier way to insert images into an assembled document. Currently we are using a some bookmark replacement code found on @EricWhiteDev 's blog but to do this we have to save the WmlDocument to disk and then open it again as a WordProcessingDocument to run the snippet before saving again.

If we add it to document assembler there needs to be some way of controlling one or both of height and width.

[EricWhiteDev]

This is one of the enhancements slated to go in, as time permits.

My tentative design:

• There would be a new metadata element, Image, which would have attributes for height and width.
• Would also be nice to have attributes to support whether the image is in-line, behind text, or in front of text.
• Probably would not support floating images. It would be problematic from a user's point of view to position them.
• The metadata element would contain a Select attribute to find the XML element in the data file for the image. The XML element in the data file would contain base64 encoded image as its text content. There should be a MimeType attribute in the XML element in the data file that contains the mime type for the image, i.e. image/bmp, image/jpeg, image/x-png, image/png, image/gif
• Alternatively, the XML element in the data file could be empty, and instead, have src attribute that contains a URI pointing to the image file on disk. Could determine the mime type from the file name extension in this case.

Thoughts?

[BrettBailey]

Sounds good.

From my own usage scenario I would never go to the bother of embedding the image in the source xml file. I also don't think I would ever need to place an image behind / over text.

It could be that we de scope those 2 things in the first instance to make this an easier task? Certainly much easier to unit test ;-)

If you want more control over image placement could you do some kind of content replacement on an actual image?

eg in the template you put an actual image. size it and place it exactly where you want and then we could mark it up in somehow with a selector that resolves to an image uri and then document assembler loads the image and sizes it to the box. I've no idea how tough this will be :-)

Hope this helps
~Brett

[MDendura]

This would be really useful. Has anyone had any further thoughts on this?

[mapo80]

Any news for this feature?

Thx.

[luizfbicalho]

Hi, I made one example that updates images, but I'm not sure that it's the best way to do it
@EricWhiteDev Can you see if it heps the issue?

I saw that it doesn't work in the header.

DocumentAssembler.zip

[ADD-Juan-Perez]

@EricWhiteDev
We are very interested in this new feature. We wonder if there is a plan to include it this year.

Thank you in advance.

[pigrew]

I've created a new tag "BlockContent" which will allow arbitrary XML to be substituted in a document at the block-level. It's pull request #163. I'm using it for embedding custom tables, but I think that it may also be usable for images, given an additional directive to embed the image data in the archive (as specified by a file path/URL?).

[krembf]

In my fork 3779fc4 I've made an implementation for ImageContent tag which allows embedding image input of different kind (base64 or file path). I've added bunch of unit tests which show different scenarios of using it. I'm sure it's not going to support all possible scenarios, but this is working code which I'm using for creation of various templates. So feel free to take a look and provide feedback.

[pigrew]

@krembf,
Could you fix your link? It's giving me a 404 error when I click it.
I like the patch, and will give it a try when we need to redo any of our reporting code. I think that it'll fit our needs. My current patch ("BlockContent") is a bit unwieldy though it works and gives the user full control of everything (I've been using it both for table generation and for image insertion).
Security implications may need to be considered in some environments (where data.xml is from an untrusted source), though I think that data.xml should be trusted in most cases (it is in my use).

It also looks like there is a new "Aspect" tag for an image? I don't see the code that checks for that or the values that it can be. Could it be described?

[krembf]

@pigrew ,
Sure, thanks for your comments. Just fixed the link, should be working now (although this is already not the latest commit). The "Aspect" tag is not in use anymore, so removed it already, sorry about that. My original intention was to specify whether the aspect ratio of the original image should be preserved or not. Eventually, I was able to achieve the same results by checking/unchecking the "Lock aspect ratio" option of Image Size menu:

There are several scenarios the image can be embedded, all dealing with the size and the ratio. I would recommend you to take a look at the DA270-ImageSelect.docx template file which I've made for unit test. It has the combinations mentioned above. Also, all tests between DA270 and DA280 verify different cases with images.
Let me know if it's still unclear and you need more info.

[ADD-Juan-Perez]

@krembf,

I have tested your implementation for ImageContent. It is working if the image is placed in the body of the document, but when it is in the header an exception is thrown. Could it be possible to support this scenario?

Thanks for your work

[krembf]

@juanperezADD ,
Thanks for your feedback. Yes, support for ImageContent in header and footer is still work in progress. I will let you know once the implementation is done.

[krembf]

@juanperezADD ,
Just added the implementation for header and footer plus some bug fixes. There are also new unit tests that were added.

[EricWhiteDev]

I'll take a look at this. I have a bit too much work, but have noted this on my radar. Thanks for doing this work - looking forward to looking at it.

[krembf]

Thanks, @EricWhiteDev, this will be great!

[VictorIranzo]

@krembf,
We want to edit templates using OpenOffice and we are interested in your implementation to support images, also in headers and footers. Is it compatible with the DocumentAssembler notation using # ? Are you going to do a pull request with your changes soon?
Thanks for your work :)

[krembf]

@VictorIranzo ,
Thanks for the feedback and glad to hear you want to use this feature. I would love to pull the changes back to origin, hopefully it will be done soon.
Regarding the # notation, do you mean using the <# and #>, right? If yes, I'm working on it, will let you know once it's done.

[krembf]

@VictorIranzo ,
Just submitted the changes. There are also new unit tests, majority of them are duplicates of the existing ones made for image content, but with # notation. It's now possible to use both methods (with or without content control):
With:

Without (note there is no content control surrounding the image under the metadata):

[cosmaioan]

This sound like a very nice and useful feature.
Has this been already merged ?

[krembf]

@cosmaioan I don't think so. The maintainer promised to review my fork, but my guess it never happened, despite the feature being requested by several devs. I can try to submit PR, let's see how it goes.

[VictorIranzo]

@cosmaioan We tested the changes of @krembf and they work nice. We were using its fork but it will be better if they are merged here.

[ForeverSmiling]

@krembf @EricWhiteDev any news when this feature will be added? I'm still waiting for it. ;-)

[krembf]

@ForeverSmiling I wish I knew :). There is pending PR since July #236, but I'm not sure if anyone had a chance to review it. Honestly, I would suggest to do a review with anybody else who is familiar with the code and willing to do so, as it looks like the currently assigned person doesn't seem to be available to make it.

[MalcolmJohnston]

@krembf I was wondering if another way to tackle this would be to refactor DocumentAssembler so that new elements could be registered somehow. If we could get that merged then we could maintain our extensions elsewhere. We'd need buy in from the maintainers to do this though

[sksallaj82]

Wow three years and running, any news on this? I have a deadline on applying images coming up soon, and this would have been a nice feature to have included.

[MalcolmJohnston]

@CloudyBrain you can use the fork that @krembf created with image support. I have been using the basis of this for over a year now and it works very well.

[MalcolmJohnston]

Additionally, I have been thinking that perhaps a better way forward for additional features in DocumentAssembler would be to refactoring it so that supported elements are extensible.

I'd be happy to take this on or contribute to other efforts but would like some reassurance that it may actually get merged :)

[EricWhiteDev]

Hi all,

Just to let you know - I have a completely refactored new version of this that I will be posting within 2-3 weeks. It supports images, sub-documents, and more. I will comment on this thread when it is posted.

The new module is refactored so that it is extensible. (The resulting functionality is split into half a dozen modules.)

Best, Eric

[MalcolmJohnston]

Hi @EricWhiteDev,

Looking forward to seeing the refactored code base for Document Assembler.

A question on the extensibility, will existing elements be able to be overriden. For example I have extended the Content element to do some basic inline HTML to WML in the fork I maintain.

Would I (in theory) be able to override the default implementation when the refactored code arrives?

Thanks for the update!

Cheers,
Malcolm

[sksallaj82]

I tried using Kembf's code, but can't get it to work against a stored base64 string. It would be great if the library knew how to generate the byte array and immediately spit an image, without using c# code to save the png to a location that the document would have to retreive.

This is what I have for the xml document:

<DocModel>
    <ImageBlob>data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHht.... </ImageBlob> 
</DocModel>

When I use kempf's document example:

<Image Select="/ImageBlob" />

It throws a yellow highlighted warning:

Error: Unmatched metadata can't be in paragraph with other text

Which doesn't make sense.

But if I save it to a disk, it works. So this isn't want I'm looking for. I'm saving images on the fly, and it's just easier to store the blob information which can then be extracted and spit out.. than play around with filenames and maintaining photos on the filesystem.

[luizfbicalho]

Muito posto has a ZIP file. Thaís version uses base 64 inside the XML file. Check It out

[sksallaj82]

Yeh but Kembf mentioned that it should work in an earlier comment.. but I don't see any demo of it working.. all the demos are showing that it works with png images that are already saved to disk. I'll try the other versions if you can send me the link of where they are.. I can't wait until Eric posts his new refactored code.. I been trying various strategies trying to get this to work. If I had a few images I could use a conditional if.. but these images are built on the fly and need to be spit into a report.

[krembf]

I'll check it later, but in the meantime, have you looked at any of the unit tests to see an example?

[sksallaj82]

Yes I'm trying it out.. but apparently my results are giving a weird error. I just realized that the image isn't even trying to be converted because it can't find the xml element. If I change this:

<Image Select="/ImageBlob" />

to

<Image Select="/BlahBlahBlah" />

I get the same error.

Error: Unmatched metadata can't be in paragraph with other text

When I switch it to this:

 <Content Select="/ImageBlob" />

I get the whole image blob spitting onto the report. So maybe I was wrong in assuming that it doesn't read the 64 byte array.. the Image tag just can't recognize any of the elements in my xml doc the same way that the Content tag does..

[sksallaj82]

Okay I got it. My experience with this hasn't been that great, but it works.

Basically I can't have this image on the same line as other content on the page. When I added a new line to get the image isolated from the rest of the paragraph, it gave me a new error. Saying there is no image immediately after the image metadata tag.. I tried my best to remove all sorts of whitespaces and it wouldn't work no matter how hard I tried. So frustratedly, I copied and pasted a working demo from one of the unit tests, and I got a new error.. where I had used an invalid format: svg+xml.

Perhaps an idea is adding some attribute to the picture content that would hook to the image metadata tag, so it doesn't matter where the picture is placed.

I changed the image to a jpeg and it worked. Unfortunately, my image looks squashed and disproportionate due to how the side of the image would look. I'll play around that more to make it look better. I'd love it if formatting of the doc would be easier. I also wish it'd have svg support (which I don't blame this tooling).. it's more to do with DocumentFormat.OpenXML. I did a bit of research and found this ticket:

dotnet/Open-XML-SDK#204

I hope that gets updated and supported soon.

[sksallaj82]

Sorry to barrage this thread, unfortunately I can't use this library. I gave it plenty of effort today, and lots of opportunities to get to where it needs to be. The formatting is extremely difficult, if I make any adjustments to the formatting and content, I get the following error:

Image metadata is not immediately followed by an image

Even though the image is right next to the Image metadata (I inspected it with paragraph marks turned on). This error could be thrown for any reason during edits. Once you get this error, you can't go back unless you undo your changes. Isolated images would work well here, but I need content placement, and tons of adjustments to make these streamlined images work. I hope Eric made improvements to the code. I will wait for the updates if there aren't any other alternatives.

[EricWhiteDev]

Release date of the new module is scheduled for Feb 7. I'll post on this thread when it is released.

[MalcolmJohnston]

@CloudyBrain without seeing your template document it is hard to say what is going on.

However, to me it sounds like you are using floating images? Is that the case?

[tomjebo]

Closing all issues as this repo is being archived and will no longer be maintained by Microsoft. The project is licensed for continued use and development by forking to your own repo.

[VictorIranzo]

@EricWhiteDev, after the announced bad news about this repo, do you have plans of releasing the announced module? Are you going to continue collaborating there? 😢

[EricWhiteDev]

@VictorIranzo I am going to maintain the Open-Xml-PowerTools at EricWhiteDev/Open-Xml-PowerTools. Yes, I will be releasing the announced module in that repo. And I certainly will be continuing development of this project.

[MalcolmJohnston]

@EricWhiteDev that is good news. Had a bit of a heart in mouth moment when I saw Microsoft would no longer be supporting the repo and relieved to see there will be a central repository maintained going forward.

If you need any help with DocumentAssembler bits and pieces then happy to help. I will keep an eye out for your rewrite of that module in the new repository.