Custom placeholders implementation

[AntonOellerer]

The concept of placeholders can be used to integrate optional functionality into the jocument library.
This could, for example, be tables of contents, custom processing of external files (inserting the abstract of a report).
In this issue, the implementation details of a "custom placeholder" standard library are discussed, for custom placeholder suggestions see #9.

[AntonOellerer]

The way I see it, a custom placeholder library adds a lot of complexity to jocument seperated from the actual generating work.
Maybe it would be best to implement some kind "plugin system" where each placeholder (or groups of placeholders) are outsourced to another library.
Another way would be to very carefully consider each custom placeholder proposal and to restrict the set of custom placeholders to a certain subset directly included into the library.

[AntonOellerer]

Codecitizen:

Maybe it would be best to implement some kind "plugin system" where each placeholder (or groups of placeholders) are outsourced to another library.

We already have a plugin system, since you can easily implement custom placeholders, but we have to make PlaceholderResolver an abstract class and add some registration/resolving logic. Like a program or template global custom placeholder registry. Would do in a separate issue.

I like how hamcrest separates its dependencies into hamcrest-core for the assertion mechanism and hamcrest-library for their standard lib. We could do jocuments-core jocuments-docx-elements jocuments-xlsx-elements or by type jocuments-table-elements ....

[AntonOellerer]

Seems like a reasonable approach to me aswell +1
I would actually use this issue for discussing the registration/resolving logic.

Re packaging: Maybe like some apache projects, where the exposed packages are actually just wrapping of functionality taken from some repositories, so a placeholder resolver could be in multiple repositories?

[AntonOellerer]

Codecitizen:

I would actually use this issue for discussing the registration/resolving logic.

I guess we should see the registration of customer palceholder defintions at the resolver level. The resolver is the component responsible for deciding how to replace a placeholder. So it should detect if its custom and if there's a implementation for it.

I could imagine this either being passed to the template or resolver directly as registry object or with an additional aspect oriented approach, where you place annotations on the resolver functions / clases (e.g. @DocumentPlaceholder(name = "PICTUER-TABLE", mimeTypes = {DOCX,XLSX})).

Re packaging: Maybe like some apache projects, where the exposed packages are actually just wrapping of functionality taken from some repositories, so a placeholder resolver could be in multiple repositories?

You mean like use case oriented? Like in Apache Commons?

[AntonOellerer]

I could imagine this either being passed to the template or resolver directly as registry object or with an additional aspect oriented approach, where you place annotations on the resolver functions / clases (e.g. @DocumentPlaceholder(name = "PICTUER-TABLE", mimeTypes = {DOCX,XLSX})).

I like the Aspect oriented approach, generally I think the placeholders should be registered at the resolver, not the template, since the control of the generation service should be in the hands of the developers and not the user.

You mean like use case oriented? Like in Apache Commons?

Yes

[AntonOellerer]

Codecitizen:
Maybe draw up a concept and research for aspect-o approaches

[AntonOellerer]

If possible, placeholders should also be parameterisable (like e.g {{image https://www.example.com/image.jpg}})

[AntonOellerer]

First sketch for how this could work:

• Packages have to be included into project
• Developer has to register desired modules at resolver startup
• (Optionally, modules could also be toggled via special placeholders at document head, e.g. {{images}})
• Modules can define their own aspects for cross cutting concerns (e.g. generate table of content after document generation finished)
• Modules register @ resolver registry with name, get cast on retrieval and parameters passed

TODO: Determine whether necessary/how to do context passing in aspects

[AntonOellerer]

An implementation of a postprocessing approach can be seen in #16 .

After consultation with @amp-dt, it was decided that the approach should be done via the CustomPlaceholder (See #12) interface, and to document & merge the postprocessing for future use.