Blaze about guide HOT 23 CLOSED

Original outline:

Blaze guide: The Tracker-based reactive templating system

Write “HTML with holes” just like you're used to, and get a fast, fine-grained, reactively updating page with no sweat.

1. Spacebars syntax, and how to use the built-in helpers
2. Building reusable components with Blaze by avoiding global data
3. How to use reactivity in a principled way
4. Writing maintainable helpers and event handlers that aren't tightly coupled to HTML
5. Reusing logic and HTML snippets between templates

from guide.

Maybe a small chapter with a comparison to React/Angular as lots of users are asking this all the time.

from guide.

Perhaps. However, I don't think the guide is a place for discussion - that will clutter it up for people who are just looking for answers. We should have this content somewhere, and link to it from this guide.

from guide.

@stubailo , sure, I also think that the Blaze guide is not the best part. Maybe we can have something like an overview of the front-end frameworks for Meteor, their pros and cons, differences, etc.

Don't know, where to put this though but it can be a great part of the guide as many users are seeking for this answer, both newcomers and experienced ones.

from guide.

Oooh, that's a good point - that might be a big decision for a lot of people when building a serious app. Framed in that way, it actually makes a lot of sense for that to be in the guide, much like a discussion of different databases would also belong if we supported more than Mongo.

from guide.

Ok, posted a next iteration on what I think the headings are.

I don't think we are decided yet on whether we be more boilerplatey like @sanjo's comment here: #8 (comment) or tell people to use Blaze Components.

Perhaps I will try both in the todos app and see how it feels.

(Keeping this separate from the other ticket which is really a discussion on whether to use Blaze Components. In fact I'll rename that ticket).

from guide.

Accessing data from a template

This seems to be more in line with the data loading chapter, if we are suggesting loading data pretty much only in templates?

I also think the beginning should go over how the thing works a little? Like somewhere there should be a description of the following:

1. What is the data context/what's a View
2. How does the build system translate .html into JavaScript using HTMLJS
3. What parts of the page re-render when data changes

Basically, some stuff that you would need to know to do advanced work with Blaze.

Also, what about animations/uihooks/momentum?

from guide.

meteor/meteor#4977

It could be good to go over how array reactivity is supposed to work, as well.

from guide.

Perhaps I will try both in the todos app and see how it feels.

Yes, that would be great. :-) I would love your feedback.

from guide.

Never use this.title, instead post.title

You mean like always use {{#let}} and {{#each ... in}}?

Being careful about using this.$ and event maps

I think this should also strongly caution against using global $ - people do this all the time

Testing Blaze components (or is this in the testing chapter?)

I think this should be in the testing chapter

Other things

1. Helpers should not have side effects, and should expect to rerun often, so don't put high-CPU code there
2. I really like the https://github.com/raix/Meteor-handlebar-helpers package - I think it is a wonderful workaround for Meteor's lack of JS expressions in templates, IMO it would be good to recommend it
3. We should have some great patterns for showing loading indicators, or at least a snippet of example code. this.subscribe makes it easy.

from guide.

Never use this.title, instead post.title

You mean like always use {{#let}} and {{#each ... in}}?

Yup.

Being careful about using this.$ and event maps

I think this should also strongly caution against using global $ - people do this all the time

That's what I meant, more or less

Testing Blaze components (or is this in the testing chapter?)

I think this should be in the testing chapter

I guess I was thinking about the mechanics of rendering a component to a off-screen div and using selectors to find HTML. It's Blaze-specific so wouldn't be in the testing chapter if we wanted to keep it agnostic?

Other things

1. Helpers should not have side effects, and should expect to rerun often, so don't put high-CPU code there

Good point, very much need to mention this. Perhaps a "reactivity" section could mention this and the each thing?

I really like the https://github.com/raix/Meteor-handlebar-helpers package - I think it is a wonderful workaround for Meteor's lack of JS expressions in templates, IMO it would be good to recommend it

I'm not sure I'd recommend it to the point of using in the example apps but maybe a list of "useful packages for Blaze" section could prominently feature it?

We should have some great patterns for showing loading indicators, or at least a snippet of example code. this.subscribe makes it easy.

Yeah. This is a section in the UI/UX chapter, but we could mention Template.subscriptionsReady here.

from guide.

I'm not sure I'd recommend it to the point of using in the example apps

Not sure why? It basically fills in for a missing feature of having expressions in Spacebars.

from guide.

It's just a bit messy is all

from guide.

It's just a bit messy is all

• 1 :-)

It is cool inspiration, but I mostly just copy functions from there.

Helpers should not have side effects, and should expect to rerun often, so don't put high-CPU code there

Maybe mentioning things like computed field to minimize/cache reactivity as well?

I guess I was thinking about the mechanics of rendering a component to a off-screen div and using selectors to find HTML. It's Blaze-specific so wouldn't be in the testing chapter if we wanted to keep it agnostic?

Maybe tinytest could be extended with things like trimEquals (like here) so that it is easier to compare HTML?

And also testing things for real components, so when you do need to test events.

from guide.

In the current deployed version of the guide I have noticed this text:

XXX: we are violating our own rule here and reading into the sub-component. But there’s no real mechanism to pass through generic event handlers in Blaze

In the "Reusing code in Blaze - Composition" section. It is regarding this code:

<template name="autocompleteInput">
  {{> blurringInput name=name value=currentValue}}
</template>

Template.autocompleteInput.helpers({
  currentValue() {
    // perform complex logic to determine the auto-complete's current text value
  }
});

Template.autocompleteInput.events({
  'change input': function(event, instance) {
    // read the current value out of the input, potentially change the value
  }
});

So a proposed "clean" solution is for every reusable component such as blurringInput to emit jQuery events when it is necessary and describe them in the components docs. So instead of listening on the change input event in the parent event-map, you would listen on input-change componentEl event or something like this. Granted, capturing the right DOM node might be hard (would be easier if Blaze forced attaching event-listeners on components).

from guide.

@Slava - you're right! This is the "correct" way to do this in Blaze, I had forgotten. I guess a question is whether to do this, or the more "Reacty" thing of passing onChange in as an argument to blurringInput.

What do you think @stubailo?

from guide.

Just going through the content again and came across this: https://github.com/meteor/guide/blob/master/content/blaze.md#helpers-in-tags

Not having seen that style of helper before, I got all excited 😉. But either I'm missing something fundamental, or it just doesn't work. I'm hoping for the former, because it looks really neat.

(I used your exact example)

from guide.

Hmm, it should definitely work. We should make sure that code sample is correct!

from guide.

It needs transpiling. @robfallows are you using the ecmascript package?

from guide.

@reel : yes - it's not the transpiling that was the issue - it built ok, but just didn't work.

from guide.

So, I've got a bit further with this. I get failure to render if I use (the example from the guide):

Template.foo.helpers({
  attributes() {
    return {
      class: 'A class',
      style: {background: 'blue'}
    };
  }
});

However, it works fine without nested objects:

Template.foo.helpers({
  attributes() {
    return {
      class: 'A class',
      style: 'background: blue;'
    };
  }
});

from guide.

Regarding this section: https://github.com/meteor/guide/blob/master/content/blaze.md#if--unless

In JS null, undefined, 0, '', [], and false are considered "falsy", and all other values are "truthy".

We should maybe link somewhere that explains this more fully. We could. for example add NaN as a falsy value. However, my biggest problem is [] which evaluates to truthy or falsy depending on how you use it. !![] evaluates as true, whereas []==true evaluates to false.

This article does quite a good job

from guide.

Oh wow, interesting. [] might be a case where Blaze actually deviates from JS in what is truthy or falsy. That's unfortunate.

from guide.