Microsoft 365 Community Community Demos, 10 Aug 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Use Linq to XML in Office.js Add-ins

Description

To support Office.js Add-ins, presenter Thomas Barnekow has developed two TypeScript libraries (linq-to-xml and linq-to-ooxml) to handle Open XML markup. In this 21-minute Developer-focused demo see how the code enables pure functional transformations of Office Open XML documents in Office.js Add-ins. In the Linq samples shown, see how to use capabilities from the libraries to transform a Word document that contains a massive number of content controls. The Add-in removes all direct formatting, while retaining all paragraph and character styles. This PnP Community demo is taken from the Office Add-ins community call – August 2022, recorded on August 10, 2022.

Demo Presenter
• Thomas Barnekow, Senior Principal Architect (Analog Devices)

Supporting documents
• Repo – OpenXmlDev / linq-to-xml | https://github.com/OpenXmlDev/linq-to-xml
• npm - LINQ to XML for TypeScript | https://www.npmjs.com/package/@openxmldev/linq-to-xml
• Repo – OpenXmlDev / linq-to-ooxml | https://github.com/OpenXmlDev/linq-to-ooxml
• npm - OOXML Namespace-Related Classes for LINQ to XML for TypeScript | https://www.npmjs.com/package/@openxmldev/linq-to-ooxml
• Sample – OpenXmlDev / linq-add-in | https://github.com/OpenXmlDev/linq-add-in

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - http://aka.ms/m365/community

A

Hi everybody, my name is thomas barnico, I'm a senior principal architect with analog devices since august 1st, so my second week just to know quickly. My email address, if you wanted to reach me on my kind of side business address which I'm also using for open source development, a few words about myself quickly.

A

As I said, I'm since august 22, I'm a senior principal architect with analog devices. In parallel, I'm the developer of a tool called documate used for high performance, word, document, automation and processing. My main activities in the past 20 odd years were in management, consulting and outsourcing sales. However, I've always been a software developer and in the recent years since 2014, some something I've actively contributed to open source projects specifically to the openxml sdk and the open xml power tools, for example, and some others not related to openxml.

A

So this is also the background of today's talk yeah specifically for today, what I've done is in support of officejs add-ins.

A

I've developed some typescript libraries for dealing with openxml markup in office add-ins in typescript yeah, so one library would be the open, xml dev, slash link to xml library, which is basically a link to xml that you might know from.net for typescript yeah and then for dealing with openxml markup. You might know the all of the namespaces that you have like the w, the p and so forth, so those names are all defined in in this library, yeah, all of them posted in npmjs.org and, finally, to demonstrate what those libraries can do.

A

I've also open sourced a link add-in projects on github I'll, give you the links later they're, all in the open, xml dev organization on github, and this basically is what I'm showing today, which basically demonstrates how to use those other libraries to explain a bit the background, I'm using some slides that I've also shared already in the dev days, redmond 2021, now to provide some context yeah.

A

So, let's look at this quick example of a word document snippet on the left, which came with tons of content, controls and nested content controls specifically, and that that was very hard to to work with in an outsourcing deal context, and so the desire was to transform the the documents that came in this form into a cleaner form. That did not have those content. Controls yeah, which you can see here by by those markup icons here, yeah, and so the transformation of this document from the left form into the right form was the task.

A

And if you look at that task in open, xml, markup yeah, what you see on the left is basically a very simplified excerpt of the markup from the left document yeah, and what you would see is the sdt, so structured document tags or content controls yeah, which basically always have a wsdt and then a wsdt content child, and then it can have nested content. In this case a paragraph and again, content control, yeah with again a nested content control and ultimately some revision markup, so inserted deleted.

A

The content in this case a run which basically was a closing square bracket right and all of this was to show a closing square record that was once inserted and then deleted. The cleaned up, markup, which we obviously require some recursion to do, looks like the markup on the right yeah. So this only has the paragraph with the inserted run, the deleted run or the deletion marker and then the actual run with the deleted text of the square bracket yeah.

A

So this was the basically the task to turn the left markup into the right markup to transform open, xml, markup or generally any xml markup. The most natural thing to to do. If you understand uh a little bit about the technology, would be the xslt, so the xml style sheet language transformations and in such transformations, which are expressed in xml themselves.

A

You define templates yeah, for example, one at the top here matching wsdt elements and then applying a certain template to process that, in this case, throwing away the sdt and the sdt content content and only looking at the node, but applying basically the same templates again on the node. And if something wasn't an sdt, then a so-called identity transformation would be applied, which simply copies the thing on the level over to the new document and then runs those templates again. So a recursive functional transformation of the openxml document.

A

If you will the same thing in c, sharp yeah in the on the net platform looks like uh the code on the right yeah. So there is a clear correspondence between those first boxes here, yeah. So, for example, the if you take, and if you have a node that is to be transformed and that node is an element, an x element, the name of which is w dot sdt.

A

So the text that w colon sdt, then you transform it by taking the element, take its wstt content, yeah the nodes of the content and then simply transforming those nodes in by using the same transformation function.

A

And the thing at the bottom is nothing else than the identity transformation which basically takes. The element here, creates a new one yeah with the same name, the same attributes and a set of nodes that are transformed by the exact same function. So this is why this is called a pure functional, recursive transformation yeah.

A

So this is what you can do in c sharp very easily, and the good news now is that you can do pretty much the same thing yeah so with just the language specific changes of upper casing versus lower casing, for example, of certain property names or function, names and so forth. So you can do the exact same thing now in typescript yeah, on the client side in an office.js add-in.

A

What is used for this uh purpose would be uh the libraries that are already mentioned yeah, so the link to xml yeah.

A

So you would see the library in github and the npm js package and then the link to open xml or oo xml package again with hosted in the office in the open, xml dev organization and the same on the npm js and then, lastly, the link to xml a sample add-in that shows how this is used and which I'm going to demo next to understand when to use this I mean this is a very good approach for everybody, having previous experience with openxml and ideally also the c-sharp uh way of using the link to xml um package and the namespaces in open xml, and I mean ideally also if you have experience wherever the officejs api does not provide adequate support uh for the use case that you are looking at yeah, I'm going to demonstrate the use case, for which at least I did not see readily how this would be done in the office.js api, which does not say that there is no way yeah and I'd be interested to see.

A

If anybody knows how to do this, whether there is a way to do this, so let's look at the demo right now. Let me show you first what this looks like in word. I have provided a very simple word document that has some formatted text, body text and text in a table.

A

The first one is a heading 1 paragraph that comes as standard in the normal dot x and I've just bolded this paragraph and the second one is a heading two, which I simply italicized and then there's formatted text of the exact same kind. The quick brown fox jumps over the lazy dog.

A

In this case, the first quick is formatted using the intense emphasis character style. The second bold word is formatted, using the strong character style. Everything else here on the right is formatted using direct formatting. So, for example, just turning the font red applying a highlight trying to then make this look like the text on the left by applying italicizing and coloring, the font and the dog is simply a direct, bold yeah, not the character style.

A

The purpose of the add-in is to basically remove all direct formatting, while retaining all paragraph styles or character styles, and so, if we look at the first one, for example, I I if I am in the paragraph or if I've marked the paragraph as a whole, this will basically transform this single paragraph. So if I click here, it will retain the heading one paragraph style and simply remove the bolding the same here, the heading two initially italicized.

A

If I click this, it will simply remove the italic formatting but keep the style yeah oops in this case here um I let me let me undo this, so I could. I can do this again in this case here.

A

If I run this, it will retain the first formattings which are character styles, but throw away everything else, and I can also do this by marking the whole document, for example, and running, and you see how quick this goes right, so this is really fast on the mac and on the windows world host.

A

However, and let's not, I can't go into too much detail on the office online host the web host. This is significantly slower and will at least when I tried this last- show some user interface or some dialogue saying that something needs to be inserted. So this is basically what this does.

A

One word of caution is that, if I remove this, if this is done in a table for reasons that might possibly be a bug in microsoft, word I don't know the tool at least as it's written will not transform this text because, for example, it will tell you that the selected range is invalid.

A

The reason is that, if you select text within a table, for example, also two two cells or I don't know a row or a column, then you cannot even take the open, xml and re-insert the exact same open, xml into the same range that will mess up the document, and so basically, I'm careful and don't even try to transform this yeah. It might work if you treat it, especially if you simply select a single cell that works.

A

If you wanted to transform a table, you would have to take the table, and at least the following paragraph. If I do this, that can be done. Okay, so now jumping into the code, the first class that is hit when uh you launch the add-in is the app component yeah, which returns some markup here, including the default button with the on click handler click, which is this handler at the top that handler basically uses. The word run call to run some code in the word context, and this key line is this one.

A

Here it is composed of two functions, namely the transform selection, which acts like kind of a driver which makes sure that, for example, the correct content is selected. You must always select the full full paragraphs, otherwise you will throw away paragraph formatting and then this.

A

The second thing is the remove direct formatting, which is the actual transformation function um that performs the transformation which I will show in the second step, so looking at the transform selection first, if we go into that function, this is a function that takes a transformation function and the word request context.

A

It first gets the selection yeah, making sure that full paragraphs are selected tests, whether the selection is valid by making sure that this is not a table that is selected and if it's not valid, returns false and doesn't even try to transform.

A

If it is valid, it calls the transform method that is passed to this function on the selection. That was basically determined, and this means the selection is an object here at the top. So this means- and it it assumes that the document element here is, is basically changed and then, ultimately, it takes the document key, basically, the content and inserts that back in into the document yeah.

A

So this is the rough order of events here and the transformation is the key point that I'm going to look next, so this transformation yeah this first function is kind of is the one that has the desired signature. So it takes a selection. Object um in this case simply takes the document property of this selection.

A

It calls the next method, which is the actual pure functional transformation, and once it has turned the document into a transformed document, it basically replaces that document with the transformed document, and that is then the basis for doing the next step in the driver.

A

If you will looking at the pure functional transformation, this is a normal recursive function yeah, so you have a function that typically takes a node, an x node in this case- and this is exactly the same thing that you would have in c sharp and it returns an x node or null null in case when you want to ignore an element filter, it filter it out. It basically always ignores anything that is not an x element because, like like an x text, for example, that will be returned directly.

A

Otherwise, if this is an element, it then looks at whether the element is a paragraph properties element like a pwppr.

A

If so, it calls the paragraph properties. Transformation basically transforms the wppr and all its child elements. If it is a wrpr element, it performs a run properties transformation. So all the character formatting, for example, will be dealt with and if those elements are different, it will basically do the identity, transformation and return. As I shown you on the slide, it will return a new element with the same name, the same attributes and it will transform the nodes using the exact same, remove direct formatting transformation method. Now, so that's the pure functional character.

A

Here it does not change or have does not have any side effects and it is recursive yeah. Looking at those paragraph properties and run properties transformations, we look at whether the element that we have is the wppr. If so, we transform the elements of the ppr by again selecting the paragraph properties transformation. Yes, so also a recursive way.

A

We retain everything that is not knowledge or be basically not ignored um and turn this into an array. This is exactly how you would do this in c: sharp, no, no difference really, and then, if we find that we have some elements, we create a new x element here and call it ppr with the retained elements as its children. Otherwise we ignore the ppr entirely and return another and that will then basically be treated with at up top right.

A

The ppr can also have an rpr again, so the same run properties transformation applies and then for any child element. For example, if it's a p style, so the paragraph style it will be retained and we also need to retain the numbering properties for the w numpr. So in this case we simply return the the element, and otherwise we we simply ignore everything else. So if we return null like for bold italics, some font properties that we've set here all of this will be ignored and thrown away.

A

Lastly, the run properties. Transformation. If you look at this quickly same pattern as above, so we look at the rtr, we take the retained elements and either create a new rpr with just the retained elements, everything else thrown away, or we also return null meaning the whole rpr can be ignored because everything was direct formatting.

A

The only thing that we retain here by saying, if element name, equals our style. So that's the run style. We return that otherwise everything else is simply ignored, and so this is pretty much it yeah. So I think this is nice and sweet and very clean does not require any specific knowledge of the office.js. Api could generally be an approach that works and is very fast on at least the word host on on on windows and mac.

A

I was told that the team is working on improving the performance on office online.

A

Of course, you can always use the office.js api if it supports your use case yeah, and certainly if it supports the use case, you have no previous experience with link to xml or the open, xml markup, which is super complicated, the markup itself yeah.

A

Then it's always best to use the office.js api yeah, but for the open, xml developer that that might be a good approach for certain use cases with that back to you, david.

B

All right, thank you, thomas. That was a great demo. It's it's exciting to see like how, if you already have c-sharp knowledge in the space, how it translates so well to the typescript site, like it's just almost the same very cool.