Script element

A <p:script> element declares several variables for a page in one block of Sessel or JavaScript. Each variable behaves as if you had written it as an e: or j: attribute on the element that holds the script. Use it when a page needs more than a few computed values, so you do not have to write a long run of namespace attributes. For the one-value-per-attribute forms, see Sessel expression binding and JavaScript expression binding.

The element is part of composition. It runs on the server, and the page you serve does not contain it.

The Pagelove namespace schema, https://pagelove.org/1.0, lists script with its type parameter, marked as handled natively. Composition runs the element itself, so the schema holds no code for it.

A Sessel script

<html xmlns:p="https://pagelove.org/1.0">
<body>
  <section>
    <p:script type="application/sessel">
      let total = ${[itemprop="price"]}.sum();
      let count = ${[itemprop="price"]}.count();
    </p:script>
    <div p:template="text/liquid">{{ count }} items, £{{ total }}</div>
  </section>
</body>
</html>

The script declares total and count. The <div> next to it reads them. The served page has the <div> and no <p:script>.

A JavaScript script

<html xmlns:p="https://pagelove.org/1.0">
<body>
  <section>
    <p:script type="application/javascript">
      import Note from "https://example.com/Note" with { type: "https://pagelove.org/Schema" };

      const red = Note.search({ tag: "red" }).length;
      const pause = await Promise.resolve(5);
    </p:script>
    <p p:template="text/liquid">{{ red }} red notes</p>
  </section>
</body>
</html>

A JavaScript script can use await and import at the top level. The import above loads a schema so the script can call search().

Namespace and prefix

<p:script> belongs to the Pagelove namespace, https://pagelove.org/1.0, like p:template, <p:include> and <p:stamp>. Declare the namespace on the script or on any element above it:

<html xmlns:p="https://pagelove.org/1.0">

You can choose another prefix. Pagelove matches the prefix to its declaration, so <pl:script> works when xmlns:pl="https://pagelove.org/1.0" is in scope. An element named script with a prefix bound to any other namespace, or to none, is not a Pagelove script. It is read as an ordinary element. A plain <script> without a prefix is the browser's script element and composition ignores it.

Types

The type attribute chooses the language. Pagelove ignores capital letters and spaces around the value.

Type Language
application/sessel or text/sessel Sessel
application/javascript or text/javascript JavaScript

A script with no type, or any other type, fails the request.

Variables the script declares

Each top-level declaration becomes a variable.

Five things are not variables:

A JavaScript script must not use an export statement or a return, even one inside a block such as an if. The script is not a module of its own, and it ends when its last statement has run. Either one fails the request. A name that a script declares must be written as it is, so a declaration such as const \u0061 = 1; also fails the request. So does a declared name that starts with __pagelove_script_, which Pagelove keeps for itself. A JavaScript script can be at most 256 KiB. A longer one fails the request.

Scope

The variables belong to the element that holds the script, called its container. They are visible to the container's template and to everything inside the container, wherever in the container the script sits. An element that comes before the script can read them. The container's later siblings cannot. The container's own attribute bindings run before the script, so they cannot read the script's variables.

<section>
  <h2 p:template="text/liquid"></h2>   <!-- sees total -->
  <p:script type="application/sessel">let total = 1;</p:script>
  <p p:template="text/liquid"></p>     <!-- sees total -->
</section>
<aside p:template="text/liquid"></aside> <!-- does not -->

An inner container can declare the same name to shadow the outer value. Inside the inner container the new value wins. Outside it the outer value is unchanged.

Place the script as a direct child of the element you want to give the variables to. A script in a deeper element belongs to that deeper element.

Order of evaluation

For one container, Pagelove works in this order:

  1. The container's own attribute bindings (r:, e: and j:) are evaluated, as they are without a script.
  2. Each <p:script> that is a direct child runs, in document order.
  3. The container's own p:template renders, and the rest of the page is composed.

A script therefore sees:

When two declarations use the same name, the later one replaces the earlier one for that container, whether they sit in one script or two.

A JavaScript script reads these names as plain identifiers when they are valid JavaScript names. A name the script declares itself is the script's own. The object Context holds all of them for names that are not valid identifiers.

A script inside an element that composition replaces never runs. That includes an element replaced by an e: or j: method result, by <p:include> and by <p:stamp>. Content that composition brings in is composed as well, so a <p:script> in it runs. That covers includes, stamps, method results, list items, template output and self. Pagelove reads that content with the namespace bindings in scope where it lands, which are the declarations on the ancestors of the element it replaces. The nearest declaration wins. A prefix that the page declares twice, in two places, is read the way the page serializes it at the place where the content lands. The source page's bindings fill in only a prefix that is not bound there, and only so that Pagelove can read a script's text as written and recognise the script. Every other prefixed element and attribute in the content is dispatched by the page's namespaces, as it always was. So if p is bound to something else where the content lands, a <p:script> in the included content is not a script, even when the source page binds p to the Pagelove namespace. If p is bound to the Pagelove namespace there, it is a script, whatever the source page binds. If p is not bound there and the source page binds it to the Pagelove namespace, the script runs. An XML page or an XML source has no raw text, so no binding is added for it and the text is read as the markup it was written as. If a fragment is skipped because it would include itself, Pagelove removes its scripts, so none reaches the browser.

A script's raw text also survives the Sessel builders. clone(), turning an element into an instance, and a schema hook that rewrites an instance all keep the text as written, and so does a save of an instance or an element. A <p:script> that a Sessel expression builds by hand, with no source to read it from, is still escaped. In JavaScript, the document global gives a <p:script>'s text as written.

A script in a transient element's session copy does not run. Pagelove puts the copy in the page after composition, so bindings in it are not composed either. Pagelove removes the script from the copy before it serves it.

Read-only

Like a binding, a script can search and read but cannot save. A script that tries to save fails the request. A JavaScript script that calls Pagelove.PUT, Pagelove.POST or Pagelove.DELETE gets the same refusal as a j: binding.

What the served page contains

The <p:script> element is removed after it runs. The page you serve never shows it, and a selector read through the serving path does not find it.

WebDAV is the authoring view and shows the script as you stored it, byte for byte. A WebDAV save is stored as it is. It is not run or checked for errors.

The script source is part of the stored page. Anyone who can read the source can read the script: over WebDAV and in the mutation events that the server sends to browsers. Do not put secrets in a script.

Text inside the script

A <p:script> holds raw text, as a browser's <script> does. A < is script text, not the start of an element, so a<b and if (x < 3 && y > 1) work without escaping. Character references such as &lt; are not decoded, so write < itself.

The text ends at the matching end tag, </p:script>. A </p:script> inside a JavaScript string also ends the script, as </script> does in a browser. Write it as <\/p:script> there. A text/plain write into a <p:script>, as into a <script> or <style>, is stored as you write it, so 1 < 2 stays 1 < 2. If the text holds the element's own end tag, Pagelove stores it escaped, so it stays inside the element.

When you append HTML to a <script>, <style> or <p:script>, Pagelove keeps the text already there byte for byte. If the appended HTML holds the element's own end tag, that closes the element, and the rest becomes siblings after it. A whole-page re-read gives the same result.

Raw text applies only when the prefix is bound to https://pagelove.org/1.0 at that point in the page. The binding has the scope of the element that declares it, so an inner declaration shadows an outer one. A prefixed script element bound to another namespace, or not declared at all, is read as ordinary HTML.

If a <p:script> has no matching end tag, the page reads it as an empty element, as if you had closed it straight away. What follows is ordinary markup outside the script. A missing end tag cannot hide the rest of the page. An empty script declares nothing, and the page saves and reloads without change.

Where the namespace has to be visible

The page reads a stored page with its own declarations, so xmlns:p on <html> is enough. A selector write reads a piece of a page without its surroundings. Pagelove reads the body in the namespace scope of the element it targets, so a PUT or POST with a Range: selector= header can send <p:script> text containing < when the target, or an element above it, binds the prefix. If the target binds nothing, declare xmlns:p on the <p:script> in the body.

XML documents

A <p:script> works in an XML document and runs the same way. The difference is how you write the text. An XML document has no raw text, so the script is ordinary XML text. Write < as &lt; and & as &amp;, or put the script in a CDATA section.

<feed xmlns:p="https://pagelove.org/1.0">
  <p:script type="application/javascript"><![CDATA[
    const ok = 1 < 2 && 3 > 2;
  ]]></p:script>
  <title p:template="text/liquid"></title>
</feed>

Pagelove runs the text after it has decoded the entities and CDATA sections. XML is case sensitive, so the element must be written p:script with a lower-case script, and the declaration must be a lower-case xmlns:p.

Errors

A script fails the request, as a failing e: or j: binding does, when:

The error is an HTML document with microdata (http://pagelove.org/Error, with statusCode and description properties). Its description names the script, for example the 2nd p:script in <section>, so you can find it. The status is 500. A Sessel script that throws an HTTP response keeps that response's status, headers and cookies, so it can end the request with a 404. Its cookies are checked by the same rules as any cookie page code sets. A JavaScript script that throws gets the same 500 as a j: binding.

Budget

Scripts run under the request's budget, the same time, operations and memory limits as bindings. All the scripts on a page share one budget. A script costs 100 operations to run, and a Sessel script also costs one operation for each unit of the size of its program. If the page runs out of any limit, the response is the typed budget response (https://pagelove.org/BudgetLimit), whatever the language. Catching the error in the script does not hide it. Composition has no separate allowance, so the number of scripts and method calls a page can use depends on the site's operations setting: about 1 method call or script for every 100 operations.

Caching

A script that reads a per-user part of request, such as request.auth, makes the response vary by user. The response is then served with Cache-Control: private. A script that reads only shared parts, such as request.path or request.method, leaves the page publicly cacheable. This is the same rule as for j: bindings.

See also