Conditions

[thegnuu]

Are there any plans to support conditions?

We used docxtemplater before but we would like to switch to this project because of the ability to add custom plugins (we need this feature to properly render Deltas from the quill editor).

Of course I can try to implement conditions with a plugin, but I think this would be a nice general feature for this project :)

[alonrbar]

Hi, Can you give an example of a condition you might use?

[thegnuu]

For example we have a report that shows customer data, on this report a few parts of the document should only be displayed if the customer has a given property. Something like this as an example:

{?hasProperty}
This paragraph should only be displayed if hasProperty is 'true'
{/hasProperty}
{?!hasProperty}
This paragraph should only be displayed if hasProperty is 'false'
{/hasProperty}

The {?...} syntax is just an example. This is just a really simple example of course, we could solve this by providing just this text as an input variable, but if the content of the paragraph is more complex something like this would be really helpful.

[alonrbar]

I have some considerations regarding adding new syntax. I will write them soon in additional comment. For the mean time: don't know if this exactly works for you but, a working solution using the current plugins would be to have this template:

{#condition is true}
This paragraph should only be displayed if the condition is true.
{/condition is true}
{#condition is false}
This paragraph should only be displayed if the condition is false.
{/condition is false}

With the data being either:

{
  "condition is true": [true],
  "condition is false": [],
}

Or:

{
  "condition is true": [],
  "condition is false": [true],
}

Depending if the condition should actually be true or not...

[alonrbar]

In version 0.6.0 I made some changes to the tagging system. You can check the changelog here but to summarize it, I decided that having a unique prefix for each tag type will eventually lead to quite fragmented/cryptic syntax on the template side (check out the situation in docxtemplater, it will soon run out of special symbols in the keyboard... it has # and / for loops, @ for raw xml, % for images, ? for paragraph placeholders and the list goes on...). My priority in easy-template-x is to make the template syntax as simple as possible since it is meant for non-programmers to be able to edit without too much difficulty.

In addition, the current API allows for tags to have names that includes white-spaces (as you can see in my previous comment and in several examples in the readme file). This makes it difficult to include additional syntax for equality operators for instance. Having said that I'm thinking on supporting some kind of "tag arguments" syntax but have not decided how exactly it should look like. This is actually the main reason why this library is still in v0.x.x and not 1.x.x.

I'm open for ideas for this "tag arguments" syntax and can share some example that came to my mind:

Option 1:

{[my tag name here] > 7}

Option 2:

{"my tag name here" > 7}

Option 3:

{my tag name here // > 7}

Option 4:

{my tag name here | > 7}

Option 5 (for image tags for instance):

{my tag name here | height = 60, width = 80}

Be happy to hear your thoughts.

[thegnuu]

You are totally right about not making the the syntax too complicated, I really like your "one tag for everything" approach. It makes it way simpler for the user who creates the template. In my case templates can be edited by the end users of our software which basically has no technical background and it should not be necessary for them to think about the type of variable they want to use.

Personally I would prefer option 4 because I think the syntax is clearer than the one of the other options. And as you described with option 5 it would be possible to provide additional parameters with this pipe as well.

I will test your example of the currently available approach tomorrow.

[R0BB3RT]

Are conditions actually in the library? 😄

[alonrbar]

Unfortunately no news here. You are welcome to use the workaround suggested above as well as to give your feedback about my previous post here.

[Heziode]

@alonrbar option 2 seems a good compromise to manage key with white space, and simplicity (but keys cannot contains double quote).

---

Another question, your syntax seems relatively similar to Handlebars, so what did you not use Handlebars for the syntax ?

[alonrbar]

Hi @Heziode, Thank you for your feedback!

The constraint on double quotes is actually pretty significant for some languages (in Hebrew for instance double quotes are used for acronyms and in some other places, for example the word school in Hebrew is usually acronymed as בי"ס or ביה"ס) so I tend more towards option 1 which has the same general look and feel but without this constraint (I assume square brackets are not common in any spoken language).

Regarding Handlebars, you are right, the syntax is similar and I was actually considering it's ancestor Mustache in the beginning. I neglected this idea as it gave no actual benefit implementation wise (Word files content resides inside XML files that cannot be processed directly using an off-the-shelf template processor) and had other syntactical limitation I didn't like, such as no support for whitespaces in tag names.

One of the main goals of this package is that it's templates syntax will be as friendly as possible for non-programmers and I felt Mustache and Handlebars, while quite simple indeed, do not exactly hit that sweet spot I was trying to achieve. One final note in that regards is that in my applications I actually leverage the ability to change the loop tag delimiters and use this form instead, which I find to be more clear to anyone not coming from Mustache or Handlebars background: {>> loop tag} {loop content} {<< loop tag}.

[alonrbar]

This is actually the main reason why this library is still in v0.x.x and not 1.x.x.

Just an update - version 1.0.0 is out now - therefor, if and when conditions support will be added to the library it will introduce a new major version.

[MedinaGitHub]

there are support to Conditions ?

[alonrbar]

@MedinaGitHub Nope, there isn't. Currently the best approach would be to follow this comment: https://github.com/alonrbar/easy-template-x/issues/13#issuecomment-558370209

[nttu307]

Have you update Conditions yet ?

[alonrbar]

No news here, sorry. To be honest I don't think I'm going to implement this in the foreseeable future as my hands are full with other matters and I don't really need this feature for my other projects. I am however encouraging whoever is willing to develop an extension or a plugin that implement this and I'll be happy to link to it in the main readme file.

[hydra1983]

@alonrbar any consideration of angular parser?

[alonrbar]

Hi @hydra1983, no that's not being considered currently. The main thing preventing me from implementing this (other than time...) is that I want templates to be non-programmer friendly. That's why tag names currently support arbitrary names, including whitespaces and non-English characters. Changing it will be a pretty significant breaking change, both for developers and for template editors (which again, may be non-developers).

Having said that, I see this is a pretty highly requested feature therefor I encourage anyone that is willing to write an extension or a plugin that supports it. I'm not sure entirely how the design of such feature will look like but would be happy to discuss if someone wants to pick up the glove.

[alonrbar]

Updating that although I can't commit on the release time, work on this feature has started in the develop branch.

[hydra1983]

@alonrbar what do you think the feature should look like?

Angular parser (docx-templater)

[alonrbar]

It will probably look very similar to what you attached. You can checkout the initial implementation of easy-template-x-angular-expressions (no README yet though). It's pretty much working as expected but there are some rough edges I want to polish before publishing it to npm.

In general, I'm trying to build this feature to be flexible enough to support alternative syntax easily. I will probably release one or two alternatives and it should be easy enough to add others if desired.

[alonrbar]

Version 2.0.0 is out now with support for custom resolvers. I've created easy-template-x-angular-expressions that leverages this capability to bring Angular expressions support to easy-template-x.

I believe this closes this ticket. Thank you everyone for you patience, it's been a long one this one :sweat_smile: If you find a bug or anything that is not working properly please open a new issue for it.

[thegnuu]

@alonrbar Thank you very much for your work on this! I will have a look at it in the next few weeks, just have e few higher priorities to do first :)