Skip to content

Links guide + fix the tutorial and sample anti-pattern #757

Description

@romain-pm

Part of #749. The canonical sample teaches the pattern that breaks.

samples/hydrogen/src/components/Hero/CallToAction/default.server.tsx types j:linknode as a non-optional JCRNodeWrapper and calls buildNodeUrl on it unguarded, puts an author-supplied j:url straight into href, registers no cache dependency, reads no j:target and emits no rel. It is the exact component whose live failure was reproduced for this epic.

  • docs/2-guides/<n>-links/README.md: the one-liner recipe; the not-navigable contract and why an unresolvable reference is the normal state; cache dependencies and the three key forms; cache.mainResource; target/rel and the page-builder carve-out; current-page state; what core already does for you and what it does not.
  • Be explicit that anchor.href is a server-side intermediate. Core completes it after the render, and only for URLTraverser's tag/attribute pairs (a[href], img[src|srcset|data-src|data-srcset], form[action], link[href], embed[src], source[srcset], param[value]) in an html template type. A URL in an Island payload, a data-* attribute, or an action's JSON response gets neither vanity rewriting nor the ?jsite= cross-site parameter that SiteParameterAdder adds in live. Jahia/jahia.com ships two divergent URLs per link today for exactly this reason.
  • Islands: the form is <a {...anchor}>, not <JLink {...}> — the library cannot be imported client-side. Mention action() as the way to fetch link data after hydration, and its URL caveat.
  • Update samples/hydrogen's CallToAction and NavBar to <JLink>. Flag two behaviour changes rather than presenting them as a refactor: the CTA's none branch renders <s>{title}</s> today, which whenUnresolved="children" does not reproduce; and NavBar's current-page test is page === mainNode, reference equality on Graal proxies, which becomes identifier equality.
  • Update the blog tutorial wherever it renders an anchor.
  • A callout that dangerouslySetInnerHTML on rich text is outside JLink's reach: core resolves the internal links there, but nothing sanitises an author-pasted javascript: href — verified end to end on 8.2.3. Name registerRenderFilter above priority 21 as where such a policy would live.
  • 3-reference is hand-written and Academy-published, so the guide carries the teaching.

First pass in #751.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions