Here is my summary of the conversation and my take on it.
There are two primary use cases discussed in the thread.
1. Multiple templates instantiated in multiple ways (with multiple "data
models"). This was our use case.
2. A bunch of templates being instantiated based on a single shared "data
model"
So how to best bring together the "data model" and the "template" to fit
these use cases with minimal overhead?
There is the generic way which is to list out all of the templates and data
models in separate locations, and then to bring together the templates and
data models via some configuration. In this world, a structure might be:
(@daniel you seem concerend by the default location being /src/main/freemarker,
do you have a better idea in mind?)
/src/main/generated/freemarker/dataModels - data models
/src/main/generated/freemarker/templates - freemarker templates
/src/main/generated/freemarker/generators - json, one per output file
The issue with this more generic structure is that in exchange for this
flexibility, you might have a bunch of extra files. For example, in the
special case #2, one needs twice as many files in the above structure.
So instead of the above structure, the suggestion in the thread is to embed
both of the common use cases into the plugin in a way that they "play nice"
together.
Create a generators directory and have the plugin interpret how to generate
the source based on the type of thing in that directory.
I think that we could instead ask how we might deviate from the above
generic structure that allows a many-to-many mapping while reusing both
data models
and templates in such a way that the two special cases can be naturally
supported.
The first enhancement is that a generator could optionally embed the data
model. This handles case #1 if you do not want
to reuse data models. It also naturally comes from enhancing the
json structure in the way that Daniel suggested:
{
"templateName": "foo.ftl",
"otherFutureMavenPluginKey": "something",
"dataModel": {
/* your application-specific stuff */
"myString": "a string",
"myNumber": 1,
...
}
}
Here the other option would be for "dataModel" to refer to a file in the
"dataModel" directory.
I would say that instead of overloading the "generators" directory to also
include templates, we allow the plugin to operate in an alternate mode,
enabled by configuration, say by setting a "defaultDataModel" parameter. In
this mode, we generate sources for all templates in the template directory
from a common data model. In this use case, the project would only use
this structure only:
/src/main/generated/freemarker/dataModel.xml
/src/main/generated/freemarker/templates/...
Having said all of this, I think the changes we would make in the short
term would be to update the json structure to include the dataModel as a
subtree, and to change the default locations to use the /generated
subdirectory rather than /data, and whatever suggestion is appropriate.
-Ben
On Thu, Aug 16, 2018 at 4:18 PM, Ben Jackson <[email protected]> wrote:
> Yes, this makes sense.
>
> -Ben
>
> On Thu, Aug 16, 2018 at 2:56 PM, Daniel Dekany <[email protected]> wrote:
>
>> Wednesday, August 15, 2018, 10:52:41 PM, Mark Malynn wrote:
>>
>> [snip]
>> > 3) I agree that using the well known json field 'templateName' seems
>> > 'hacky' (from a freemarker point of view). However, from the point of
>> view
>> > of the maven plugin it works nice. It provides the flexibility I need
>> with
>> > the minimum fuss. I will entertain another mechanism as long as it
>> supports
>> > my main use case.
>> [snip]
>>
>> The problem with that is that it doesn't work if you happen to need a
>> "tempalteName" field in your actual data. Yes, that's unlikely, but
>> take it as a demonstration of why it's not correct. The "correct" solution
>> is like this:
>>
>> {
>> "templateName": "foo.ftl",
>> "otherFutureMavenPluginKey": "something",
>> "dataModel": {
>> /* your application-specific stuff */
>> "myString": "a string",
>> "myNumber": 1,
>> ...
>> }
>> }
>>
>> Note how it allows adding new keys (like "otherFutureMavenPluginKey")
>> without breaking backward compatibility.
>>
>> --
>> Thanks,
>> Daniel Dekany
>>
>>
>
>
> --
> Benjamin Grant Jackson
>
--
Benjamin Grant Jackson
