documentation

[FND]

Getting Started

• choosing an adaptor
• compiling views
• creating and organizing views (e.g. views/manifest.js convention)

→ in-browser demo - see Bruck for a nicer editor experience, possibly even a proper editor

API

• renderer
  • views vs. regular macros (the former are never passed any child elements)
  • registering and rendering views
  • document fragments
  • sync vs. async mode
• deferred child elements
• <Fragment> (cf. 867417f)
• HTML encoding (cf. ad5c195)
• terminology (e.g. "macros for markup expansion; parameterized placeholders" ≈ components, views, params etc.)
• blank values (children, attributes)
• BufferedStream to emit string rather than writing to stream

Examples

• embeddable-content: minimal markup (container + link), PE results in augmented DOM thanks to custom element's client-side processing

Tips

• JSX conventions: uppercase vs. lowercase, looping, Fragment
• limited post-processing (unlike DOM) ⇒ explicit wrapping macros (e.g. <CardHeader> <h3> because if(children[0].tagName === "h3") { addWrapper(…); } doesn't work)
• scalar vs. complex attributes

Internals

• HTML generation (≙ generateHTML, JSX idiosyncrasies)
• macros (≙ createElement, Renderer)

Background

• rationale (abstraction & composition, cross-platform)
• why streaming? (→ progressive rendering)
• origin story
  • decoupled BE vs. FE teams, in part due to tooling deficiencies ⇒ SPA ⇒ network API ⇒ awkward coupling and frustrating coordination
    resulted in experimenting (flailing) with Nashorn and servlets
  • zero-runtime templating; JSX as DSL for function invocations
• "complate" (suggested by tillsc)

Marketing

• component-oriented templating
  traditional templating does not sufficiently account for components (≈ abstraction + composition)

• nutshell: generating static HTML, typically server-side rendering

• "declarative rendering", "expressive, declarative UI components"

• tech-agnostic (JS as lingua franca)

• JSX for markup abstraction

• JavaScript import semantics

• testimonials

• an example on Glitch might double as effective marketing

• blurbs

  if you're stuck on a JVM project but expect a suitable FE environment anyway

  if you like React's developer workflow (modern front-end tooling), but are
  unhappy with consequences for users (bloat, performance) and complexity
  (SSR + rehydration)

Alternatives

• Pug
  • mixins for abstraction, named blocks for composition
  • implementations in various langauges, but with differences and thus limited portability? (e.g. versioning: uncertain whether Java implementation supports named blocks)
  • global namespace for mixins? potentially brittle, also less explicit and flexible than JavaScript imports
• Mustache:
  • lacks abstraction/composition capabilities
  • implementations in many langauges, but with differences and thus limited portability?
• React SSR:
  • same abstraction/composition capabilities
  • client-side origins (e.g. state, component life cycle) might complicate debugging and overhead while browsing official documentation
  • uncanny valley (e.g. className)
  • runtime-agnosticism; Node only? (i.e. integration with other languages/runtimes would require a sidecar with a corresponding API - i.e. a contract specification between application and renderer - and thus additional overhead/complexity)