Consider allowing block tags immediate access to parent variables

[dorner]

I understand that the current implementation of JsRender treats each block tag as essentially its own view. This means that if you have a variable accessible to the main template, it is no longer accessible to the block:

{{!-- called with {foo: 'bar', baz: [1, 2, 3]} --}}
{{: foo}}
{{for baz}}
  {{: foo}} {{!-- error, can't find it--}}
{{/for}}

I know there are ways around this, either by using #parent.parent.data or passing variables in explicitly. However, it seems unintuitive to have to do this every time you open a for block. Just based on experience with pretty much every programming language in existence, a simple block does not lose all access to parent variables - it's not like using an external template, which would be more akin to a new function with new local scope.

I also understand that this is due to JsRender's (rather odd, IMO) decision to only "work" on a single data item at once and all normal accesses would be properties of that item. But we could at least attach the parent item's properties as helper objects, for example, so they could be easily accessed as ~variables without having to explicitly declare them for every single block.

[BorisMoore]

Thanks for your question and thoughts.

So here are some responses:

If you compare {{for}} with for (...) {} in programming languages, yes in JsRender parent scopes are not visible in the same way. But this is not a programming language, it is a templating language, and so there are a lot of differences. Other templating languages mostly do not expose outer scopes like that. If they do then they are a) probably using nested with() in the imlementation, which is a significant perf hit, b) following a philosophy which is far from the 'logicless' idea preferred by many. More specifically, if a template language is used in the context of MVVM or similar, or following that kind of philosophy, then there is a goal of separating Model and View, and maintaining appropriate encapsulation.

In JsRender we try to strike a balance: we provide a lot of the flexibility and power obtained by not adhering to strict 'logicless' ideas, and providing an expression language within template markup, but still providing some guarantees around encapsulation - which incidentally also provides better security as well as better maintainability. For that reason you cannot write {{:globalJavascriptVariableFoo}}. But you can pass in that variable as a helper, and then write{{:~helperVariableFoo}}.

In JsRender you can also set allowCode: true on your template and then include {{* ret += globalJavascriptVariableFoo; }} in the template... - but you have to opt in to those semantics.

About: "it's not like using an external template, which would be more akin to a new function with new local scope", they really need to be the same. Writing this

{{for baz}}{{:foo}}{{/for}}

should be equivalent to writing

{{for baz tmpl='getFoo'/}}

and then

$.templates("getFoo", " {{:foo}}");

So you need encapsulation. You have no idea whether getFoo template will actually be used in a nested context which includes a foo property. 'getFoo' is designed to work on a model that has a foo property, not a view which happens to be nested in another view which uses a model with a foo property. View/Model separation needs to be respected.

And even if we did try to implement your suggestion, it would mean that we have to create a contextual data object that is a merged object with all the properties of the models of the parent views. But if now you switch to JsViews, and you want data-linking then if a parent model gets an observable property change, we would have to ensure that all the nested contextual data objects are listening to that change so that the cloned properties are also changed observably. That sounds like a lot of code, bad performance, and a probably source of bugs and maintenance issues...

Finally it would be a big semantic change to introduce so late after beta. I am heading to V1.0 so I am trying to avoid breaking changes.

[dorner]

I can definitely see the issues involved with it (particularly that it's late in the game now). I just don't really agree that
{{for baz}} ... {{/for}}
and
{{for baz tmpl="#external-template" /}}

should be equivalent. In one you are explicitly calling an external template; in the other it's a simple block in the existing template. A few other templating languages will simply expose the "receiver" of the block as a named variable, e.g. something like
{{for baz ~thebazitem}}
and allow you to reference ~thebazitem while not changing the existing scope at all. (On reflection this makes a hell of a lot more sense than what I wrote above.) I have a feeling that this is the most common use case.

Depending on how complex the implementation is, this may even be a non-breaking change you can introduce, since this syntax is not used right now - you could theoretically keep the existing, scope-changing syntax while introducing the new one to allow non-scope-changing.

Just something to think about, I guess, because this is really the only negative I've found about using this framework - I've tried four others and this is definitely the best in all other aspects for what I need.

[BorisMoore]

Concerning templating languages that simply expose the "receiver" of the block as a named variable, e.g. something like {{for baz ~thebazitem}}, can you point me to an example of that? I'm not sure I understand how it is supposed to work.

Also, I am curious when you talk about having tried four other frameworks - are you using JsViews, or just JsRender. What other frameworks did you explore?

[oserra]

Great conversation guys!

I really agree with dorner that the sintax {{for baz ~thebazitem}} is great
and it is a non-breaking change, backwards compatible.

I also think jsRender and jsViews are really good. I think that this
framework lacks of popularity... it's great but not many people knows about
it (that's what I perceive).
I'd also love a plugin for eclipse that syntax-checks&colour the code
within template scripts :-)

[dorner]

I'm just using JsRender, not JsViews. I'm currently in a project that has an existing paradigm that doesn't involve a full MVC solution - I'm only interested in the templating part. 8-)

The other frameworks I've tried are Google Closure Templates, doT, Handlebars and EJS. Nunjucks also looked really interesting but it seems like it's aimed exclusively at Node.js (the docs specifically say that rendering fully client-side is really slow). The main things I'm interested in are:

• Fully client-side solution (no compilation required)
• Ability to call other templates with parameters (it's surprising how many templating libraries don't support this)
• Syntax which is concise (not a lot of extra characters) but readable (I didn't like doT's use of ? instead of if, for example)
• Easy to add tags or helper methods (this is the reason I had to move away from Closure Templates)
• Not "logic-less" - I find these sorts of libraries to be nowhere near powerful enough to build even simple single-page web apps

So like I said, JsRender hits all the right buttons except for this one nitpick. 8-)

An example of the thing I'm discussing in Closure Templates:

  {foreach $slide in $slideList}
    {$slide.url} in {$slideList.length}
  {/foreach}

In doT:

{{~ myArray :value}}
  {{=value}} in {{=myArray.length}}
{{~}}

In both examples you have access to both the iterated variable and the original scope.

[BorisMoore]

OK - thanks - so in each case (Closure and doT) you have to specify the 'variable' for the inner context - '$slide' or 'value' and then access the properties using that reference - '$slide.url' 'value.url'. JsRender instead has an implicit inner variable '#data' and lets you get {{:url}} directly. This makes things more compact:

  {foreach $slide in $slideList}
    {$slide.url}
  {/foreach}

becomes

  {{for slideList}}
    {{:url}}
  {{/for}}

Advantage - more succinct, and I can use and external template without needing to tell it the name of the reference variable 'slide':

  {{for slideList tmpl='inner'/}}

inner:

    {{:url}}

So what if I want to get the array.length:

  {foreach $slide in $slideList}
    {$slide.url} in {$slideList.length}
  {/foreach}

becomes

  {{for slideList ~list=#data}}
    {{:url}} in {{:~list.length}}
  {{/for}}

which is still more compact than Closure. But now the inner template and caller will need to agree on the name of the array variable '~list'

  {{for slideList tmpl='inner' ~list=#data/}}

inner:

    {{:url}} in {{:~list.length}}

To avoid needing to share the array name, we can write

inner:

    {{:url}} in {{:#parent.parent.data.length}}

but that is certainly less friendly.

So maybe an easy improvement would be to expose the stack of data objects from the outer scopes as a built-in contextual variable, like we do already for '~root' - which is the outermost one.

We could call it '~dataStack' or 'contexts' or 'roots' ?? - so you would write:

  {{for slideList tmpl='inner'/}}

inner:

    {{:url}} in {{:~roots[0].length}}

Thoughts?

BTW - about your syntax {{for baz ~thebazitem}} - that would not work, since it corresponds to the existing syntax which allows you to pass multiple unnamed parameters to a tag, so here we have two - baz and ~thebazitem which we are passing to {{for}} - but of course ~thebazitem is undefined.

What you are really suggesting is semantically equivalent to what you can write today as {{for baz ~thebazitem=#data}}. But as I say above that still means that for an external template you need to agree on the '~thebazitem' variable name. The ~roots suggestion above avoids that...

[BorisMoore]

@oserra: Thanks for your comments. BTW I would love to write a plugin for Eclipse - but of course, as you can imagine, I neither have the time nor the knowledge to do so :). Maybe you or someone in the Eclipse community would be interested in doing so :). It could work for any Mustache-like template.

[dorner]

My main concern is that when the inner block needs to use multiple variables from the outer block, the existing syntax gets more and more unwieldy:

{{for slides ~slideList=slideList ~viewMode=viewMode ~selectedURL=selectedURL}}
  {{if viewMode == 'all'}} {{!-- do something }}
  <option {{if url == selectedURL}}selected{{/if}} value="{{:id}}">{{:name}}
{{/for}}

versus

{{for slides ~slide}}
  {{if viewMode == 'all'}} {{!-- do something }}
  <option {{if ~slide.url == selectedURL}}selected{{/if}} value="{{:~slide.id}}">{{:name}}
{{/for}}

I'm fine with the "inner and outer blocks having to agree on the name of the array variable" because they are in the same template.

The main advantage of my suggestion is that instead of having to pass every single scope variable you are interested in into the inner loop, you'd be passing just a single variable (the one newly introduced by the loop) and continuing to have access to all the existing ones. The disadvantage is the extra reference to ~slide, but in my opinion it's far more natural than having to remember each variable you intend to use and manually pass it into what's essentially an inner block.

I'm not a big fan of exposing data scope that way you suggest (with roots) - we have scope for a reason, we should just be designing the scope so it makes sense. 8-) And it's very unnatural to access it that way - the writer should generally be able to write a variable name, with some minor decoration () and access it naturally.

I don't think my suggestion is equivalent to {{for baz ~thebazitem=#data}} - because #data at that point is the outer context; I am suggesting leaving the current context as it is and passing in a variable for what is currently the inner context.

Re syntax, we could just use a different symbol, like : or & :

{{for slide &slide}}
  {{~slide.url}}
{{/for}}

[BorisMoore]

The whole approach in JsRender is that there is a current data context in each block. If slide is an object, {{for slide}} moves the context to slide - which is referenced by #data. (Like 'this').
One reason for that is so that any block in a template can at any time be converted to an external template, without change, (a 'partial') and so the original template can be 'modularised' and its component parts can also be reused.

Handlebars and Mustache do the same as JsRender, and do not allow the nested context to see the outer one.

{{#each person}}
    {{name}}
    {{#each phones}}
        {{number}} 
        {{!-- in this block, the contextual {{this}} is a phone. {{name}} will not work here --}}
    {{/each}}
{{/each}}

doT and Closure do not have that approach. They have a single context, and expose additional variables in nested blocks.

So when you say "I am suggesting leaving the current context as it is and passing in a variable for what is currently the inner context." that means changing from the Mustache/Handlebars/JsRender approach to the doT/Closure approach which would of course be a big breaking change.

You would have to write:

{{for slides &slide}}
  {{:~slide.url}}
{{/for}}

and the following which works today, and is equivalent, would no longer work:

{{for slides}}
  {{:url}}
{{/for}}

BTW you generally don't need to alias each variable since they are properties of the current #data context, so rather than

{{for slides ~slides=slides ~viewMode=viewMode ~selectedURL=selectedURL}}
  {{:~slides.length}}
  {{if ~viewMode == 'all'}} {{!-- do something --}}
  <option {{if url == ~selectedURL}}selected{{/if}} value="{{:id}}">{{:name}}
{{/for}}

you can write

{{for slides ~outerOb=#data }}
  {{:~outerOb.slides.length}}
  {{if ~outerOb.viewMode == 'all'}} {{!-- do something --}}
  <option {{if url == ~outerOb.selectedURL}}selected{{/if}} value="{{:id}}">{{:name}}
{{/for}}

[dorner]

OK, I have a better understanding of this now. I'm still not convinced that the "change context entirely" is the correct approach. Handlebars is a "logic-less" template, and revolves around the whole idea that the data you're passing in is relatively simple, having done all your computation already. I find that approach to be difficult to work with, which is precisely why I tried to find something more powerful.

Since JsRender does allow you to do more complex things, I think it makes sense to have it think more like a programming language and less like a somewhat "dumb" template.

It's true that this is a philosophical change, but that doesn't necessarily mean that it technically needs to be a breaking one, at least for now. & variables and ~ ones can be made to be mutually exclusive, so if you use & variables you are indicating that you want the scope to stay as is, and if you use ~ ones you want it to change. This would give the user the best of both worlds, at least IMO.

A few more arguments in favor of the change:

1. Nested loops. If I want to reference an outer variable, I'd have to keep passing in into all the nested tags:

{{for items ~outerData=#data}}
  {{for fields ~outerData=~outerData ~outerInnerData=#data}}
    {{:name}} {{~outerData.someModifier}}
  {{/for}}
{{/for}}

2. Simple loops don't gain much by the current way of doing things:

{{for someStringList}}
  {{: #data}}
{{/for}

vs.

{{for someStringList &string}}
  {{:string}}
{{/for}}

and at least this way the writer gets to define the variable themselves as something that's self-documenting, instead of using the rather generic #data.

3. The whole idea of having to reference the "current context" explicitly doesn't sit right with me. The way I generally call templates is by passing a hash of key -> values to it. That hash has no semantic significance; it's just a way for me to give the template a set of different data pieces. Having to keep references to it and use them manually seems unwieldy to me.

Here's my rundown of what I think the pros/cons are to the different approaches:

Advantages of the current way:

• Consistency between logic of nested blocks and external ones
• Succinctness - assuming your current context is meaningful and you are working on attributes rather than the value itself
• Simplicity of implementation - only need to program one kind of parsing for {{for loops

Advantages of proposed way:

• No requirement to pass contexts down the path - they are always available
• Recognizes that most often the one or two new variables introduced by the loop are not important enough to justify changing the entire scope and losing immediate access to other important data
• Consistency in referring to attributes - it is always attr and not ~someContext.attr or ~attr
• Gives the template writer full control over the names of all their variables
• Feels more natural from a programming perspective

Sorry, I really don't mean to drone on here or write walls of text (I don't usually do this). I'd just really like this already awesome library to be a bit more natural and intuitive. 8-)

[BorisMoore]

Quick reply:

JsRender already has context that is visible to all levels of nesting - ~foo is either a helper (which is added to context at the top-level, or a contextual variable ~foo=someExpression which is added at some level of the nested blocks. Either way, once added to context they are visible to all levels of additional nesting. (Blocks inherit the parent context).

So you don't need to do

{{for items ~outerData=#data}}
  {{for fields ~outerData=~outerData ~outerInnerData=#data}}
    {{:name}} {{~outerData.someModifier}}
  {{/for}}
{{/for}} 

You can just do

{{for items ~outerData=#data}}
  {{for fields ~outerInnerData=#data}}
    {{:name}} {{~outerData.someModifier}} {{!-- this is visible from here too --}}
  {{/for}}
{{/for}}

So that is pretty simple.

Javascript plain objects are hashes, or course. So when you say you pass in a hash, yes, but sometimes it is hierarchical data. You can access the hierarchy using paths a.b.c or you can use {{for a.b}} to step in to the level of hash c. Either way you can access the values of the hash, by key, directly. From nested contexts if the case of hierarchical data, you can still do ~root.a.b.c so your top-level hash is always available.

Arrays of strings is a secondary scenario. The primary target scenario is arrays of objects (hashes if you will). So usually you don't need to reference #data directly. But if you do, it is no more rocket science than accessing this or this.bar - it is a this pointer...

So for an array of objects you will generally have:

{{for someList}}
  {{:someProperty}}
{{/for}

In your notation that becomes

{{for someList &object}}
  {{:object.someProperty}}
{{/for}

which is much less succinct and intuitive IMO.

So here are your Advantages of proposed way: with some responses to some of them...:

• No requirement to pass contexts down the path - they are always available You don't need to pass them down. Just define them once, same as in the proposal
• Recognizes that most often the one or two new variables introduced by the loop are not important enough to justify changing the entire scope and losing immediate access to other important data
• Consistency in referring to attributes - it is always attr and not ~someContext.attr or ~attr No, it will be myVariable.attr - if we have an array of objects, not strings
• Gives the template writer full control over the names of all their variables They already have that. Usually they don't refer to #data, but if they do it is exactly equivalent to 'this` and if they want to expose it as inherited context, they can do so and they choose the name they want for that variable.
• Feels more natural from a programming perspective

[dorner]

Hmm... I wasn't aware about the inheritance of helpers throughout parent contexts, so thanks for clueing me on this. I'm getting a much better feel for the framework here.

And I took another look at the render() call - since you can pass in helpers directly, this mitigates some of the pain because I can basically use the helpers hash instead of the data hash for properties that I need access to throughout all contexts. In fact, I could just pass an empty hash into the data and put all my current objects into helpers and it would basically act the way I want in the first place. 8-) In fact I just tried it and it works wonderfully.

I think "helpers" is a misnomer - it is really a hash of things that are always in scope. It sounds like "data" is information and "helpers" are functions (this is how things work in e.g. Rails) but that's not the case; "data" can include functions and "helpers" can include data. Data is really "current context" and helpers are "globals". I'd consider renaming them appropriately.

One thing I think would mitigate some of the edge cases is to give the user one extra view helper, #parentData, which would be the equivalent of calling #parent.parent.data. It's a lot more succinct and it may be useful in these sorts of situations. I also think using something like #self instead of #data in general is more accurate, but I'm not sure you would want to make that change now.

I do think the documentation needs a lot of work; I'll be adding another ticket for that.

Thanks for your patience throughout this thread. I'm really happy with the framework now that I understand it better.

[BorisMoore]

That's right. You can use helpers for all that...
Take a look at http://www.jsviews.com/#helpers

For view paths, #foo is short for #view.foo, so #parent means #view.parent, #data means #view.data.

See:
http://www.jsviews.com/#samples/jsr/paths
https://msdn.microsoft.com/en-us/magazine/hh975379.aspx
http://stackoverflow.com/questions/20900963/jsrender-jsviews-how-to-loop-a-selected-object-list/20914994#20914994

And yes, getting better docs will help a lot - it is part of getting to V1.0

So #parent.parent... steps up through parent views, and each view has its data context, view.data.

But it is not always #parent.parent.data you need:

• In {{for object}} there is an outer view and a nested item view, so #parent.data is the outer data.
• In {{for array}} there is an outer view, a nested "array" view, and n nested "item" views. So from the block content (an "item" view) #data is the item data, #parent.data is the array and #parent.parent.data is the outer data.

I am exploring an idea to provide something related to your request. I'll keep you posted.

[dorner]

Awesome. Yeah, basically just a unified, concise way to get to the context just outside the current scope.

I understand about the view paths - I just think that the most common usage of anything involving the current view will be to get the current data, so even adding an alias of #self to #data would make it clearer what's being referred to.

[BorisMoore]

I have created an update, here https://raw.githubusercontent.com/BorisMoore/jsviews.com/itemVar/download/jsviews.js, and a sample here: http://jsfiddle.net/BorisMoore/zgr90L3s/ - with an added feature you can use on any tag to get a context variable (which is visible in nested contents) for the data item(s) "#data" of the block:

{{for people itemVar='~person'}}
    {{:~person.name}}
    {{:name}} {{!-- this still works --}}
    {{for ~person.address itemVar='~address'}}
        {{:person.name}} lives in {{:~address.street}}
...

See also the unit tests here:
https://github.com/BorisMoore/jsviews.com/blob/itemVar/test/unit-tests/tests-jsrender-no-jquery.js#L463

So this makes it easier to get an alias for the block data which can be used at all nested levels. But it does not modify the fact that a {{for x}} block will move the data context to x (if x is not an array - or to the array items if it is).

I did explore additional behavior of keeping the outer data context, but it led to a number of complexities and it was not clear that the advantages/scenarios where it was actually useful were sufficient to justify that complexity - and the potential confusion it could create for people who are trying to understand how JsRender and JsViews templates work. Simpler is better.

So my plan is to merge this into master and gh-pages branches. You are welcome to test it out, in the meantime.