Hi all,
I took over maintenance of this library from @rowanc1 a while back, as we use this project quite heavily. That being said its not a particularly large library, and I have been weighing up dropping it in favour of a new solution for quite some time.
The problem with the library is that the code does not support most of docx features yet, and extending it has proved very cumbersome.
For example recently I extended it to add support for custom sections, but extending it to add support for custom headers and footers is proving to be near impossible.
Overall i've felt that the drawbacks and limitations of the library in the current state, outweigh the benefits - and we have actually opted to just using docx directly.
But I believe it can be fixed, so I'm just posting my thoughts here - I will probably update this with more information in future.
The problem
The biggest issue in my opinion is that all of the functions are mutating some central state value that is used to blindly render the final document into docx format.
e.g we have defined a bunch of custom serializers for image nodes, and paragraphs which we spent a lot of time on.
But now if we want to add a function like renderHeader - its not easy for us to implement cleanly, as the renderHeader cannot call other renderContent functions- as these functions always default to placing their children onto the main children array in the state.
A cleaner approach
The library would be much better if we handled all the serializing functionaly, ie. a serializer should have a signature like this
serializeSomeNode(node: Node, ctx: Context) => (Paragraph | Table)[]
Where every serializer returns the Docx entities it created.
Why is this useful?
Because we don't always want to render a node into the docx body, we may want to render a node into the header, or the footer - and this will allow us to re-use our serializers to put content anywhere
Hi all,
I took over maintenance of this library from @rowanc1 a while back, as we use this project quite heavily. That being said its not a particularly large library, and I have been weighing up dropping it in favour of a new solution for quite some time.
The problem with the library is that the code does not support most of
docxfeatures yet, and extending it has proved very cumbersome.For example recently I extended it to add support for custom sections, but extending it to add support for custom headers and footers is proving to be near impossible.
Overall i've felt that the drawbacks and limitations of the library in the current state, outweigh the benefits - and we have actually opted to just using
docxdirectly.But I believe it can be fixed, so I'm just posting my thoughts here - I will probably update this with more information in future.
The problem
The biggest issue in my opinion is that all of the functions are mutating some central state value that is used to blindly render the final document into docx format.
e.g we have defined a bunch of custom serializers for
imagenodes, andparagraphswhich we spent a lot of time on.But now if we want to add a function like
renderHeader- its not easy for us to implement cleanly, as therenderHeadercannot call otherrenderContentfunctions- as these functions always default to placing their children onto the mainchildrenarray in the state.A cleaner approach
The library would be much better if we handled all the serializing functionaly, ie. a serializer should have a signature like this
serializeSomeNode(node: Node, ctx: Context) => (Paragraph | Table)[]Where every serializer returns the Docx entities it created.
Why is this useful?
Because we don't always want to render a node into the docx body, we may want to render a node into the header, or the footer - and this will allow us to re-use our serializers to put content anywhere