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 interface

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

this form encodes this card

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

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

• 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.

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.