poke

a single run of the event loop

event loop summary

a card is poked to a page
check if poker has permission
evaluate code.page agains the card
replace data.page with the result
if data changed, recurse for subscribers and ancestors

poking from the browser

;form(method "post")
  ;input.hidden(name "/", value "add-todo");
  ;input(name "/task/title", value "write manual");
  ;input(name "/task/body", value "...");
  ;input(name "/due", value "~2024.1.1");
==

this form encodes this card

/              tas/%add-todo
/task/title    t/'write manual'
/task/body     t/'...'
/due           da/~2024.11.30

note:
values will be interpreted as dimes if possible.
so if you send 42, the dime in the card will be ud/42, not the string containing 42.

if you want to force a string interpretation, encode using +wood or use the ;spine-input-atom web component which allows you specify the aura.

system data

along with data passed in the form, there is an extra branch /sys in the card which will be populated with other useful info.

/sys/src        p/~migrev-dolseg
/sys/our        p/~migrev-dolseg
/sys/now        da/~2024.1.1
/sys/eny        uv/0v...
/sys/from       t/'/path/to/originator'
/sys/url/[...]  ...

/sys/url/[...] will contain any url parameters from the POST request.

for example, a POST to
domain.com/~~/place?beep=boop&bing=bong
will result in a card containing...

/sys/url/beep    t/boop
/sys/url/bing    t/bong

system commands

the system interface uses the same “card-passing” semantics as the rest of the system.

by “system interface” we mean the way you do things like:

creating pages
deleting pages
copying pages
etc

you specify a command is to a system by using one of the special “root dimes” for the card you pass.

system root dimes

warning:
the system command interface is likely to change without warning until i get it right.
feel free to play around with it, but do not depend on it yet.

tas/%sys-copy
- expected sub-paths:
  - /to : the path to copy TO
- optional sub-paths:
  - /from : the path to copy FROM (defaults to the location you sent the card)
  - /init : an $info containing a card to pass to the newly copied location
tas/%sys-mock (reverse copy)
- expected sub-paths:
  - /from : the path to copy FROM
- optional sub-paths:
  - /to : the path to copy TO (defaults to the location you sent the card)
  - /init : an $info containing a card to pass to the newly copied location
tas/%sys-move
- expected sub-paths:
  - /to : the path to move TO
- optional sub-paths:
  - /to : the path to move FROM (default to the location you sent the card)
tas/%sys-cull
- expected sub-paths:
  - /pax : the path to FILE to delete complete (including sub-paths)
tas/%sys-oust
- expected sub-paths:
  - /pax : the path to PAGE to delete complete (keeps sub-paths intact)

redirect directives

usually, when you send a card from the frontend with a POST request, the response will be the updated page at the same path, which will get swapped into the page.

conceptually the same as... poke a card to a path, then peek the same path

but occassionally, you want to the UI to move to a different location after processing the poke.

for example, if you sys-move a file, from /foo to /bar, you probably want the UI to follow and end up at /bar after the poke succeeds.

to accomplish this, there are two system dimes that you can put in any card:

/sys/redirect
a cord-encoded path to redirect to after the poke succeeds
/sys/redirect-via-name
a cord-encoded path of a location in this same card to look for a path to redirect to.
this lets you easily piggy-pack off a path that is already encoded in the card.

example of copying a template into a sub-file, with initial value

::  hawk-500
:-  %manx
;form.fc.g1.page.prose
  =method  "post"
  ::
  ::  specify this card is a "system command"
  ::  by defining the "root dime"
  ::
  ;input.hidden(name "/", value "sys-copy");
  ::
  ::  after success, redirect to the path stored in /to
  ::
  ;input.hidden(name "/sys/redirect-via-name", value "/to");
  ::
  ::  the path to copy FROM
  ::
  ;input.hidden(name "/from", value "/~/system/templates/note");
  ::
  ::  the path to copy TO
  ::
  ;input.br1.bd1.p2
    =name  "/to"
    =value  "{(spud here)}/beneath"
    =placeholder  "path to copy to"
    ;
  ==
  ::
  ::  initial value for the note
  ::
  ;input.br1.bd1.p2
    ::  the note template expects text in /txt
    ::  so we place the inital value in /init/txt
    =name  "/init/txt"
    =placeholder  "initial text"
    ;
  ==
  ;button.br1.bd1.b1.p2: submit
==

sending multiple cards at once

a “poke” is not just the evaluation of a single card against a single location.

it is the entire run of the event loop which includes resolving dependencies and propagating changes up the tree.

the order of evaluation is: longest path first.

this allows effecient updates of the entire tree.

for some kinds of interactions it will be necessary to send multiple cards at once.

to do so use info multiplexing.