Add advanced “TEMPLATE_ENGINE.md” documentation. #193
Conversation
theengineear
force-pushed
the
advanced-template-engine-docs
branch
from
61b0c6e to
0f2c0ff
Compare
|
@klebba — Took some time (maybe more than I’d like to admit) trying to update these docs as you suggested. As discussed, these are aimed at folks who are already experts with JS / DOM-APIs. Rather than be a high-level explainer (like the last one was) — it goes through a series of examples (each building off the last) to introduce the key problems that template engine has to solve. |
theengineear
force-pushed
the
advanced-template-engine-docs
branch
3 times, most recently
from
4fa7318 to
7666e4c
Compare
doc/TEMPLATE_ENGINE.md
Outdated
| An html template engine allows developers to ergonomically create dynamic web | ||
| applications — plain and simple. | ||
|
|
||
| One way to accomplish this would be to create an entire html document in a |
There was a problem hiding this comment.
IMO the server side example could be omitted here, else give a complete example for comparison. If the latter, point out that a server side template takes the form of a single string of markup to be unpacked by the browser. The browser would not be able to detect the difference between preprocessed HTML and static HTML
doc/TEMPLATE_ENGINE.md
Outdated
| interface ought to be something like: | ||
|
|
||
| ```js | ||
| render(container, html`<div>markup</div> + <div>${data}</div>`); |
There was a problem hiding this comment.
nit: the + looks like an operator — how about +
| const selectedItem = data.items[data.selected]; | ||
|
|
||
| // Interpolate our template with our state idiomatically. | ||
| const result = html` |
There was a problem hiding this comment.
Following is an example which contains:
an attribute binding on line
a property binding on line
a list on line
nesting within the list
a conditional statement
These cover most of the cases the engine must handle
| ### Iteration 1 — a first crack | ||
|
|
||
| ```js | ||
| // Recursively create html by joining strings with values. |
There was a problem hiding this comment.
nit: densify the comments here
doc/TEMPLATE_ENGINE.md
Outdated
| * Some scripted implementation details leaking. †††† | ||
| * Change-by-value detection. ††††† | ||
|
|
||
| † This has broad implications — including unsafe injection of strings.<br> |
doc/TEMPLATE_ENGINE.md
Outdated
|
|
||
| **What it doesn’t do** | ||
|
|
||
| * Nothing is cached and the DOM is thrashed. |
doc/TEMPLATE_ENGINE.md
Outdated
| **What it doesn’t do** | ||
|
|
||
| * Some markup abstractions are leaking. | ||
| * Many edge cases are not considered. |
| does recursive string concatenation… all the way to an html-aware, performant | ||
| DOM management system. Nice! | ||
|
|
||
| The remaining edge-cases and markup-cleanup won’t be covered here, but this |
There was a problem hiding this comment.
perhaps "wont be covered here, but from here we would direct you to the source itself"
The point of this document is to explain (to folks that are already experts in web development) how html template engines conceptually work. It walks the reader through a series of iterations which add increasing sophistication to a toy template engine library. Closes #187.
theengineear
force-pushed
the
advanced-template-engine-docs
branch
from
7666e4c to
ff01fae
Compare
|
Iterated on nearly all the comments you left in here @klebba — the one main thing that I am going to put to later is adding additional code comments to the example code. I think that will actually take quite a bit more time to thoughtfully do and I’d like to pause on this for now. 
|
The point of this document is to explain (to folks that are already experts in web development) how html template engines conceptually work.
It walks the reader through a series of iterations which add increasing sophistication to a toy template engine library.
Closes #187.