Tutorial 01 Intro: Add note regarding bracket style in Hypertext 101 section

[Benjamin Sugar]

Hi,

First, thanks for a great tutorial. Very helpful! However, I got stuck for a long while on the correct syntax for the text node in <div class="saucer">Greetings</div>.

Aside from this HTML to Hyperscript converter, I haven't found any documentation that yields the correct solution. According to the hyperscript documentation tested in the interactive demo, all of the following should work:

h('ul',
  h('div.landscape', [h('div.saucer', ['Greetings'])]),
  h('div.landscape', h('div.saucer', ['Greetings'])),
  h('div.landscape', h('div.saucer', 'Greetings')))

Renders:

<ul>
  <div class="landscape"><div class="saucer">Greetings</div></div>
  <div class="landscape"><div class="saucer">Greetings</div></div>
  <div class="landscape"><div class="saucer">Greetings</div></div>
</ul>

My suggestion is to add some text to the 'Hypertext 101' section that articulates that while there are a few ways to render children nodes, for the sake of the demo, the preferred way is always to encase them in brackets.

[Andrew Duensing]

The documentation for the function signature of the h function is available here. Although the implementation is similar to the hyperscript documention you linked, Maquette uses it's own implementation and does not make use of any external hyperscript libraries, as far as I can tell. Maquette used to accept all of the examples you offered as valid, but since version 3.0 the function signature is more static/strict.

That all being said, I think your suggestion is still a good one. Maybe it would be good to link to the hyperscript documentation from the first tutorial. @johan-gorter what do you think?

[Johan Gorter]

@CitrusFruits is correct, maquette has always used its own dialect of hyperscript and since 3.0 content must be an array. The tutorial text pre-dates version 3.0, where encasing in brackets was still optional. I think rephrasing the text for the first tutorial level should make it easier for people to get to level 2. A link to the api documentation buries the user with detail and that should imho be reserved for later in the tutorial. How does

The final parameter is an array producing the contents of the node. Strings produce text, and h() calls produce childnodes.

Sound as a replacement for

The final parameters represent the content. Strings become text, and h() calls create childnodes.

[Benjamin Sugar]

Personally, I think both are a good ideas. Normally I'd argue that it's never to early to get someone using the documentation, but after taking a look at it, I guess I agree that it might complicate things initially.

I like the language change, but I have one more thought which is connecting the two sentences more explicitly. Right now, to me, it reads as being about three separate things:

a) The final parameter is an array producing the contents of the node.
b) Strings produce text
c) h() calls produce childnodes.

Perhaps something like:

The final parameter is an array producing the contents of the node. The array may contain strings which produce text, and h() calls to produce childnodes.

On more thing, I would consider adding the word 'dialect' to the line:

Maquette uses a notation called hyperscript.

Either way, I leave both to you and trust in your judgement.

Thanks for your consideration!

[Johan Gorter]

I made the suggested modifications. Thanks for the input!

[Benjamin Sugar]

Thanks for the library! I'm confident there's a lot of folks like me who are eager to become familiar with today's style of front end programming and it's nice to have a framework like yours where the barrier of entry is low, but is still expressive.

Take care!