Question

Reading about the different Spark annotation types here: https://github.com/meteor/meteor/wiki/Spark

I am still confused on where Landmarks and Branch Labels need to be placed. What’s the difference between the two, and when does Handlebars call them? I am the author of the Blade templating engine, and I am trying to integrate Blade with Spark.

Answer 1

In Handlebars, every template and every {{#constant}}…{{/constant}} region is wrapped with a landmark. When a region of the DOM is reactively updated, the old and new landmarks are matched for the purpose of DOM preservation, lifecycle callbacks (created/destroyed), and landmark-local state.

Landmarks are identified by the “path” formed by the branch labels that contain them. (Landmarks themselves don’t contribute to the path.) It’s illegal to have two landmarks with the same path. It’s also important that you compute the HTML that will go inside the labeled region or the landmark from the body of the function argument to labelBranch or createLabel. This is because Spark is actually already matching the DOM when you call these functions so that it knows whether to call “created” (because this is a new landmark) or not (because it is a re-rendering of an old one) before running the function to calculate the HTML.

Handlebars calls labelBranch in several places to distinguish any template (landmark) invocations that should be distinct. Basically, the labels should determine the “call stack” that led to the template invocation. Each template invocation in the template source ({{> someTemplate}}) gets a label, and loops are also instrumented, labeling each iteration of the loop based on the _id of the object in question or some other heuristics if there isn’t one. (Note that there are two code paths for loops in Meteor templating, one for observable cursors from the database and one for everything else, like normal arrays.)

In this snippet from a template that includes the “foo” template several times, each invocation of “foo” (including each iteration of the loop) is done within a different branch label:

{{> foo}}
{{> foo}}
{{#each collection}}
  {{> foo}}
{{/each}}
{{> foo}}

What if a helper invokes template functions directly?

var myHelper = function () {
  return Template.foo() + " " + Template.bar();
}

In this case, the day is saved because the template package also wraps each template in a label like “Template.foo” or “Template.bar” (labels are cheap). However, there will be a duplicate landmark problem if a helper calls the same template multiple times with different arguments; in this case, it is up to the helper to drop additional branch labels to disambiguate.

The implementation of Template.foo that is generated by the templating package (in deftemplate.js) uses the following nested annotations, from outer to inner: label, data, landmark, events, isolate. This order is pretty constrained. For example, the landmark enclosing the events annotation is used to find the data. The isolate annotation is intentionally on the inside.

The current factoring of the handlebars and templating packages may not be great for adding additional templating packages! This is a new frontier for us. We’re very interested in having more templating languages, though, and happy that you’re working on this.