v21 syntax

[delaneyj]

Datastar v0.21 API

Datastar makes signals declarative. Signal values are accessed in expressions using the syntax signalName.value.

Attributes

Attributes take the form data-{pluginName}-{key}.{modifier}, with key and modifier being optional.

data-bind

data-bind="foo"

data-indicator

data-indicator="foo"

data-ref

data-ref="foo"

data-signals

data-signals="{foo: 1, bar: 2}"

data-signals-foo="1"

data-computed

data-computed="{baz: foo.value * bar.value}"

data-computed-baz="foo.value * bar.value"

data-on

data-on="{click: sseGet()}"

data-on-click="sseGet()"

data-attrs

data-attrs="{disabled: foo.value, hidden: bar.value}"

data-attrs-disabled="foo.value"

data-class

data-class="{hidden: foo.value, visible: bar.value}"

data-class-hidden="foo.value"

data-show

data-show="foo.value"

data-text

data-text="foo.value"

data-persist

data-persist

data-persist="{key: 'foo bar'}"

data-persist-key="'foo bar'"

data-intersects

data-intersects="console.log(foo.value)"

data-scroll-into-view

data-scroll-into-view

data-view-transition

data-view-transition="vtName"

Actions

Actions take the form {pluginName}({arguments}).

SSE Plugin

sse(url, {method='get', headers={}, remote=true})

DOM Plugins

clipboard()

Logic Plugins

setAll(regexp, value)

toggleAll(regexp, value)

[bencroker]

We should carefully consider whether to namespace actions using @ or ds, to help prevent naming conflicts. Also, because signals are user-defined, whereas actions are not, it could be confusing to see customAction() in your data attribute.

One other thing to consider is whether sse should be renamed request. I realise that sse might be considered more specific, but it describes the response rather than the action, which is to make a request to the backend.

<div data-on-click="request(url, {method: 'post'})"></div>

[bencroker]

We decided against namespacing actions, and in favour of sse.

Also, this syntax presents issues, so we’ll not proceeding with it for now.
data-computed="{baz: foo.value * bar.value}"

[delaneyj]

Fixed in #308

[khalwat]

We decided against namespacing actions, and in favour of sse.

Also, this syntax presents issues, so we’ll not proceeding with it for now. data-computed="{baz: foo.value * bar.value}"

Lodging my requisite objection: Datastar actions should have a prefix to avoid the inevitable ("not if but when") namespace collisions, and to mark them as being from or related to this thing called Datastar.

I'd rather see:

dsGet()
dsPut()
dsClipboard()

than:

sseGet()
ssePut()
clipboard()

[bencroker]

Just to clarify, there is only sse() (no sseGet, ssePut, etc.).

https://github.com/starfederation/datastar/blob/develop/site/static/md/reference/plugins_backend.md#sse

[khalwat]

I know... and I'm not a fan. The fact that you want to put shortcuts in the IDE autocomplete or the Craft Datastar APIs make me think they really should be in the Datastar API itself.

[bencroker]

Well, plugins in Datastar should each have a single concern. By moving get(), post(), etc. into a single action, we consolidated 5 plugins with the same concern into a single plugin. Your objection sounds like personal taste, which is fine. Autocompletion is only there to save a few keystrokes.

[khalwat]

Sounds like a limitation of the plugin system, if a single plugin can't provide multiple actions.

Probably you should be ok with removing the autocomplete macros from the VSCode plugin if the current API is fine.

[bencroker]

Sounds like a limitation of the plugin system, if a single plugin can't provide multiple actions.

Yes, I believe it is.

Probably you should be ok with removing the autocomplete macros from the VSCode plugin if the current API is fine.

Yeah I probably will.

[khalwat]

Since it mirrors the fetch API I guess it's something people will be familiar with so I'm good with it, just won't provide expansion shortcuts in the IntelliJ plugin.

The difference is in a JS context, you'll get pretty good syntax checking... the trick is getting VSCode/IntelliJ to know the attribute is a JS expression, and offer the language syntax injection there.

I haven't figured that out yet for IntelliJ yet, but hopefully it's possible. I'm not sure about VSCode?