Provide clearer documentation as to the logic-less advantage of Dynamic Names?

[chrisdotcode]

Hi all,

After discovering the optional Dynamic Names feature (the README documentation also needs updating, by the way: it currently states that "at present, the only module being described as optional is regarding support for lambdas", which is no longer correct), and reading the documentation in the ~dynamic-names.yml file itself, I came away with the conclusion that it was an unnecessary addition to the language: that you had to munge up your data with extraneous dynamic names for something that already could be solved with if/elses.

However, the biggest pro for Dynamic Names - the one that defeats the above argument, and a con not documented in the if/elses section - is the fact that including a bunch of if/elses inside mustache templates is inherently logic-ful, not logic-less. Since ~dynamic-names.yml only implies this and never mentions it explicitly, I believed that Dynamic Names were a misfeature. However, after reading #54, I came across this comment, which explicitly states the above: one of the advantages of logic-less templating is the lack of logic (duh), and Dynamic Names removes logic from the templates entirely. Interestingly enough, that con is presented for lambdas, but is missing from the if/else section. The pro of Dynamic Names adhering to the logic-less ethos - which as I again believe is the biggest advantage they have over other implementations - is likewise missing from its details.

I think it would be worthwhile to explicitly document the above in the ~dynamic-names.yml file. Can I go ahead and make a PR?

[chrisdotcode]

Also considering GraphQL (and TypeScript), could a more real-world example replace the current one in that file? Instead of dynamic: text|image, it could be __typename:text|image. GraphQL could even be called out by name, e.g.: "Often, this "dynamic name" will be some sort of data type. This type can be automatically retrieved from many databases. GraphQL, for example...".

Not only is this more real-world, but it makes the example more concrete. The current "dynamic" Dynamic Name example seems purely fabricated in my opinion - as if a developer would have to manually ensure each item in items had that field - but dynamically loading a partial based on already-preexisting type information (such as __typename) could show that that value could likely be auto-populated automatically from a database.

[jgonggrijp]

I'm not 100% sure I understand all of your suggestions, but it sounds sensible.

Regardless, everyone is welcome to submit pull requests; permission for that is never needed.

If I understand correctly, the changes you suggested in your second post could exist independently of the changes you suggested in your first post. If that is correct, I encourage you to submit two pull requests, so we can also review the changes independently.

[chrisdotcode]

Will do!

[agentgt]

@chrisdotcode

I agree the documentation does not make it clear and it took me awhile to see value as well.

I don't know if this helps but the way I see dynamic names when used with partials is you are trying to dispatch based on the shape of the data. In some programming languages this is done with pattern matching on an ADT (which given your experience with PureScript I think you know).

The problem is most make their data struct like (e.g. lack inheritance or ADT) and do not have polymorphic data (e.g. a list of heterogenous types of objects) as having mixed types is tricky for regular JSON serialization.

Your GraphQL example is great example that hopefully spans across other languages without the need to get into category theory.

EDIT here is an example in Typescript of what I'm talking about: https://github.com/jstachio/jstachio/issues/140#issuecomment-1563396778