Skip to content

v0.19 Reach

Latest

Choose a tag to compare

@derstruct derstruct released this 17 Nov 21:27

Doors 0.19 Release Notes — "Reach"

Doors 0.19 lets you set up a resource in Go with the same settings its tag attributes take, use it in markup, and get its URL in code.

Highlights

Resource chains

Every resource attribute now has a method. A chain carries its settings with it, so you can define a resource once, pass it around, and use it in markup or turn it into a URL:

<script src=(doors.ResourceFS(web, "app.ts").Script().Module().Bundle())></script>

<script data:charts=({
	url, err := doors.ResourceFS(web, "charts.ts").Script().Module().Bundle().URL(ctx)
	if err != nil {
		return nil
	}
	return url
})>
	const url = $data("charts")
	if (url) {
		const { draw } = await import(url)
		draw()
	}
</script>
  • ResourceFS, ResourceLocalFS, ResourceBytes, and ResourceString return a ResourceStatic: an asset by default (Name, ContentType, Cache, Portable), or a script or stylesheet through Script() and Style().
  • Script stages: Raw, Bundle, Module, TypeScript, Profile, Name, NoCache, Private, Portable. Style stages: Raw, Name, NoCache, Private, Portable.
  • ResourceHook, ResourceHandler, and ResourceProxy return a ResourceDynamic with Name and Portable.

Defaults match the tags: scripts and stylesheets are cached at a public URL, assets are served through a hook unless you call Cache(), and handlers are always hooks. Any chain works as a src/href value or as a modifier. In markup the tag still decides the kind of a plain resource; a Module() chain on a <script> adds type="module". In code a plain resource is an asset, so use Script() or Style() for a script or stylesheet URL. See Builder API.

URL(ctx) returns the URL the matching tag would get, hosted or hook. It returns an error when the source cannot be read or built, and context.Canceled for a hook whose content has been cleared. See Resources. To build an app-wide URL once, keep it in a package-level store from doors.NewStore(), as in App-Wide URL.

Built scripts and styles at fixed paths

UseResource takes any cached chain, including bundled scripts and minified stylesheets:

doors.UseResource("/embed/v2.js", doors.ResourceFS(web, "embed.ts").Script().Bundle())

Fixed paths are served with ServerCacheControl, by default public, max-age=31536000, immutable, so put a version in the path and change it when the content changes. See App.

RaceLatest

doors.RaceLatest is a new Race mode for handlers where only the newest input matters. It works like RaceStrict, and a call waiting for its turn is canceled once a newer call arrives, so calls that pile up while one runs are skipped and only the newest runs next. See Race.

<input (doors.AInput{
	Race: doors.RaceLatest,
	On: func(ctx context.Context, r doors.RequestEvent[doors.InputEvent]) bool {
		return false
	},
})/>

ScopeCheckpoint

doors.ScopeCheckpoint lets one action wait until related work settles without stopping that work. cp.Scope(false) runs at once; cp.Scope(true) runs once earlier checkpoints are done and no ordinary request is in flight. Checkpoints queue in arrival order and nothing is rejected. For example, inputs autosave as you type while Submit waits until the autosaves settle, including keystrokes typed while it waits. See Checkpoint.

Indicating the submit button

doors.SelectorSubmitter() and the Submitter helpers, such as doors.IndicateContentSubmitter("Saving…"), target the button that submitted the form, whether it was clicked, triggered by Enter in a field, or clicked by an emit. On other events they select nothing. See Targets.

Reading the configuration

doors.AppConf(ctx) returns the app's Conf with defaults filled in, for example to reuse ServerCacheControl in your own handlers. See Configuration.

ProxyMod in front of a Door

doors.ProxyMod and the proxies built on it, such as doors.Class and event attrs like AClick, now work in front of a Door. They modify the Door's container (your element or the generated d0-r), or the first element of static Door content:

~>(doors.Class("panel")) ~(&p.orders)

The modification belongs to the surrounding render: it stays across the Door's own Inner and Outer updates and is replaced when the Door is rendered somewhere else. The generated d0-r is identified by data-d0r, so a mod can set its id. See Template Syntax.

Behavior Changes

  • ProxyMod no longer fails the render when text or other non-element output comes first. The mod is skipped and an error is logged.
  • $sys.emit and Emitter refuse disabled targets. When a target is a disabled form control (including one inside a disabled <fieldset>) or sits inside an inert subtree, nothing is dispatched and the emit fails: $sys.emit rejects with a canceled HookErr, and an Emitter call fails with ErrExecution. An Emitter checks all its elements first, so one disabled element fails the call for all of them.
  • Quieter logs. A failed browser call (Call failed) and an action requested from a canceled context are now logged at debug level, not error and warning. A call on a detached context still receives the error.

Fixes

  • Cached resources were gzipped even when gzip did not make them smaller, such as images and fonts. They are now served as is unless gzip saves at least 5%.
  • The same bytes served with different content types shared one cached /r/ URL.
  • Minified and unminified builds of the same stylesheet shared one cached URL.
  • A resource first rendered private was not reachable at its cached /r/ URL when later rendered with cache.
  • A <link rel="stylesheet"> without href logged an error; it now passes through.
  • raw scripts were cached once per profile, although profile does not apply to them.
  • A <script> that Doors does not process, such as one with a type it does not handle, could have some of its data: attributes rewritten. It now passes through as written.
  • $sys.emit and Emitter did not wait for hooks of events the emitted event triggers, such as the form submit that follows a click on a submit button. Those hooks are now awaited and counted, and their failures are reported.
  • A ScopeLatest request that replaced one still running its After actions could hang. It now runs, and the replaced request completes normally.
  • ScopeRate forgot its interval when a request finished before the interval ended, so the next event ran at once.
  • An indicator on the event element did nothing when a scope, such as ScopeDebounce, delayed the request.
  • Scopes shared by chains that feed each other could lose or double-run requests. A request released into ScopeRate or ScopeLatest while that scope was replacing its pending request was dropped, leaving the scope before it stuck for good, or ran untracked next to the newer one. ScopeDebounce could fire after its pending request was canceled the same way, throwing an error or starting the next request early.
  • A scope that emptied while one of its own requests was being released could unregister a newer scope with the same id, so a checkpoint, serial, or blocking scope stopped tracking requests already inside it. A request canceled while its scopes were still being released was released twice.
  • An invalid indicator, such as a bad selector, attribute name, or class token, could leave its request unsettled and its scopes stuck. The indicator is now logged and skipped, and anything it already applied is undone. Class names in an indicator are split on any whitespace.
  • Before and After actions such as ActionIndicate targeted the clicked inner element, such as a <span> inside a button, instead of the element with the event attr.
  • ASubmit and ARawSubmit did not send the name and value of the button that submitted the form. They are now sent, as in a native submit.

Breaking Changes

Doors now requires GoX v0.4.0. Install the matching gox CLI and run gox gen. GoX v0.4.0 removes the legacy ~{ ... } and func { ... } forms (run gox fmt from v0.3.5 first to convert them) and closes elements implicitly the way HTML does, so a </p> after a list or table no longer matches. See the GoX release notes.

Old New
doors.NewHook(ctx, r) returning (string, bool) r.URL(ctx) returning (string, error)
doors.NewResource(ctx, r, contentType) r.ContentType(contentType).Cache().URL(ctx); for scripts and stylesheets r.Script().URL(ctx) or r.Style().URL(ctx)
doors.UseResource(path, r, contentType) doors.UseResource(path, r.ContentType(contentType).Cache())
ResourceHook, ResourceHandler, ResourceProxy return Resource They return ResourceDynamic, which is still a Resource
$sys.emit resolves to the number of triggered hooks and rejects when one fails; Emitter event methods return ActionInto[int] $sys.emit resolves to { ok, canceled, failed } once every triggered hook has settled; Emitter event methods return ActionInto[EmitReport]

Migration

go get github.com/doors-dev/doors@v0.19.0
  • url, ok := doors.NewHook(ctx, r) becomes url, err := r.URL(ctx). Where ok was false, err is context.Canceled.
  • $sys.emit and Emitter calls no longer fail when a triggered hook fails or is canceled. Read the former count from ok (OK), and where you caught a failure, check failed (Failed) instead. Capture an Emitter result with Into(&report) into a doors.EmitReport. An Emitter call with no attached elements now fails instead of returning zero.
  • For JavaScript or CSS passed to NewResource, prefer .Script() or .Style(): the URL is built and minified like the tag's, with the right content type. A cached asset without ContentType gets a sniffed type, which is wrong for JavaScript and CSS.