Saving data from JavaScript

A JavaScript method body, Trigger action or Processor action saves data with the global Pagelove object. There is nothing to import. It has three methods, the same three a Sessel script uses, with the same behaviour:

Pagelove.PUT(item, path, selector)    // path and selector are optional for an instance
Pagelove.POST(item, path, selector, placement)   // selector and placement are optional
Pagelove.DELETE(target, selector)     // selector is optional

Where you can save

A method saves wherever a Sessel method in the same place could, and nowhere else.

Saves work in:

Saves are refused in:

A save made while a page is viewed is not checked again against your site's permission rules: the reader was allowed to view the page, and the resolver saves on the site's behalf. So a read resolver can change data that the reader could not change themselves. Only save what every reader of that page may cause to be saved.

A page served from a cache runs no code, so it saves nothing. Do not rely on a read resolver to count every view.

A save can still be refused, for example when the data breaks its schema. A refused save throws an Error you can catch, whether it was a PUT, a POST or a DELETE. See When a save is refused for what its message says. On a host with transition rules, a save is also refused when the page changed while the save was being checked. Your code can read the page again and retry the save. If you do not catch it, a refused save is your code's own error. A database failure under a save is reported as a server fault, and running out of budget (time, operations or memory) is reported as running out, as for search(). If you catch either of those and throw a different error, your code fails with yours. There are two exceptions, both when the request's operations or time are used up: a trigger or processor action then stops as running out, and so does a method that Sessel code calls, because Sessel cannot catch running out.

A save counts against the budget of the request your code runs for, schema checks and shape constraint checks included. In a trigger or processor action, a save whose checks run out of operations or time throws too, but your action has then run out of budget. Even if you catch the error, the action stops as running out, as it would for any code that runs out.

Saves inside saves

A save runs the full write pipeline for the page it saves. That pipeline can run code that saves again: a @write resolver that saves an item of its own type runs its own resolver again for that save. Three saves, each running inside the previous one, are allowed. A fourth fails. The script sees it as a refused save: an error you can catch, whose message says at most 3 saves may run one inside another. If your code does not catch it, the request fails with an error response.

Sessel recursion inside a nested save counts against one shared limit. Sessel code that recurses deeply inside a nested save shares its allowance with the Sessel scripts it runs inside, and each save counts as 16 levels of it, whether a Sessel script or JavaScript made the save. So the same Sessel code can fail with a recursion limit error sooner than it does when it runs alone. JavaScript recursion has its own limits.

A nested save is charged to the request's budget like any other save, and it also counts toward this depth limit. Save to a type whose resolver does not save, directly or through other types, when you need to save from a resolver.

What you can save

item is one of:

Anything else throws a TypeError. An item Note.search() finds cannot be saved yet: it does not carry the address it came from.

PUT

Call Saves Gives back
Pagelove.PUT(instance) back where the instance came from the instance
Pagelove.PUT(instance, path) the whole document at path, creating it if it does not exist the instance, now belonging to path
Pagelove.PUT(instance, path, selector) in place of the element selector matches in the document at path the instance, now belonging to that element
Pagelove.PUT(html, path, selector) the HTML at path, or in place of the element selector matches the item the HTML describes (see below)

An instance you have just built has not come from anywhere, so it needs a path:

PUT: Instance has no source path. Use PUT(instance, "/path.html")

Only a string counts as a path. If you pass undefined, for example from an optional parameter that was left out, the instance is saved back where it came from.

An instance is checked against its schema before it is saved, and an instance that breaks its schema throws. Properties you left unset get their schema defaults (@default), and the instance saved and given back includes them. Defaults are worked out without reading other data, so a default that looks up other records may not be filled in here.

If the schema declares a primary key (@key), its value becomes the saved element's id, even when a default supplied it. A value that is empty or contains a space is skipped.

POST

Pagelove.POST(item, path, selector, placement) adds the item to the document at path, next to or inside the element selector matches. placement says where. It takes the same values as the placement in a client's POST request:

placement The item goes
append (the default) last in the matched element
prepend first in the matched element
before just before the matched element, as its sibling
after just after the matched element, as its sibling

The value does not depend on case, and spaces around it are ignored. If you leave placement out, or pass null or undefined, the item is appended. Any other string throws an error and nothing is posted: POST: unknown placement "<value>"; use append, prepend, before or after. A client's request ignores an unknown placement, but your code gets an error, so a typing mistake never appends by accident. A value that is not a string throws a TypeError: Pagelove.POST's placement must be a string.

// Put the newest note first in the list.
Pagelove.POST("<li>Newest</li>", "/notes.html", "#notes", "prepend");

Without a selector, the item goes inside the page's body. append puts it last in the body and prepend puts it first, so Pagelove.POST(item, "/notes.html", null, "prepend") makes the item the first thing in the body. The rest of the page is kept. before and after need a selector, and without one they throw POST: placement "before" needs a selector; with no selector the item goes inside the page's body, with nothing posted.

With no selector, these pages have no body of their own to add to:

A save from a script is the same request a client POST makes, so the schema, shape constraints and cardinality all apply.

It gives back the item with no address. Where the new element ends up is not known, so the item cannot be saved again by its address: Pagelove.PUT(added) throws PUT: Instance has no source path. This stops a second save from replacing the container the item was added to. To change the item later, save it with a path and a selector that finds it: Pagelove.PUT(item, path, selector).

DELETE

Pagelove.DELETE(instance) deletes an instance from where it came from. Pagelove.DELETE(path) deletes the whole document, and Pagelove.DELETE(path, selector) deletes only the element selector matches and keeps the rest of the page. It gives back true.

When a save is refused

A refused PUT, POST or DELETE throws an Error. Its message is the verb, the status code and its name, then the reason when the platform gives one. When the platform lists several reasons, they are joined with ; . Examples:

A selector that matches nothing never creates the container. Catch the error to carry on:

try {
  Pagelove.POST("<li>New</li>", "/notes.html", "#notes", "prepend");
} catch (e) {
  // e.message is "POST returned 416 Range Not Satisfiable: …"
  Pagelove.POST("<ul id=\"notes\"><li>New</li></ul>", "/notes.html");
}

In JavaScript, e.message is this text alone. In Sessel, a caught error's message starts with runtime error: .

If you do not catch the error, the save fails the trigger or processor. The client gets a 500 error page, and its message includes the refusal, for example Trigger action failed: javascript/module binding threw: POST returned 416 Range Not Satisfiable: … (Processor action failed: … in a processor). If the refusal names another page, such as the page that already holds a unique value, the client reads another page in its place. The caught error carries the full reason, including that page's path. To control what the client sees instead, catch the error and throw your own HTTPResponse. The client then reads exactly what you throw.

What a save gives back

Every save gives back what it saved. You can ignore the result: code written before saves gave anything back works as it did.

In rare cases a save works but the saved item cannot be handed back to your script, for example when handing it back takes too long. The save still counts and the call returns undefined. It never throws, so you do not need to save again.

A schema instance saved with PUT comes back as an instance of the same class that knows its new address. So you can change it and save it again, and it goes to the same place:

export default function (title) {
  const saved = Pagelove.PUT(new Note({ title }), "/notes/first.html");
  saved.title = "Second thoughts";
  Pagelove.PUT(saved);   // saves /notes/first.html again
  return saved;
}

An item added with POST comes back with no address (see POST). DELETE gives back true.

HTML comes back as the item it describes, when its outer element has itemscope and itemtype. If your site has a schema for that type, you get an instance of its class. Otherwise you get a plain object of its properties. Other HTML gives back undefined.

Context

A method changes Context by assigning to it, for example Context.greeting = "hello". A save addressed to https://pagelove.org/Context throws. A trigger or processor action cannot change Context for later steps at all.

See also