Multi-homed attributes

Many WebPDF attributes work on three elements: the WebPDF <script>, every <pdf-file> and every <pdf-page>. You set one once for the whole document, then override it where a file or a page needs something else. We call these attributes multi-homed.

An example

Here the script turns viewer controls on for every page. The first page inherits them, and the second turns them off with controls=-:

Controls everywhere but one page

html
<script src=//new.webpdf.pro/.js type=module controls></script>
<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>
<pdf-page of=f scale=0.3></pdf-page>
<pdf-page of=f scale=0.3 controls=-></pdf-page>

Hover both pages: only the first one shows its bar.

Which attributes are multi-homed

Attribute<script><pdf-file><pdf-page>Rule
controls signaturesYesYesYesOn or off: the nearest element that has the attribute decides, and - turns it off.
iumYesYesNoOn or off, the same way, per file. On the script, a bare ium only makes PDFium available, and ium=+ makes it every file's default.
toolbarYesYesYesOne of a set: the nearest element that names a valid edge wins, else bottom.
event:prefix placeholder:aspect-ratioYesYesYesOne value: the nearest one wins, and - turns it off.
-YesYesYesTokens that add up from the outside in: -token drops an inherited token, and a bare - drops them all.
controlslistYesYesYesTokens that add up the same way.
trust:storesYesYesNoTokens that add up the same way.
trust:src trust:srcdocYesYesNoValues that add up; a file's - drops the script's.

A page looks at its own attribute first, then at its file's, then at the script's. The other attributes, such as src, no or scale, belong to one element only.

On and off

For an on/off attribute, the nearest element that has the attribute decides: the attribute without a value (or with any value but -) turns the feature on, and - turns it off. Without it anywhere, they are off:

html
<pdf-file id=f src=//pdf.ist/web.pdf signatures></pdf-file>
<pdf-page of=f></pdf-page>                  <!-- cards: from the file -->
<pdf-page of=f signatures=-></pdf-page>   <!-- no cards on this page -->

ium is the exception on the script: there, a bare ium only makes PDFium available to every file, and ium=+ makes it every file's default. See Choosing a renderer.

Single values

event:prefix and placeholder:aspect-ratio take one value: the nearest element that has the attribute wins, and - turns an inherited value off.

html
<script src=//new.webpdf.pro/.js type=module placeholder:aspect-ratio=A4></script>
<pdf-file id=slides src=slides.pdf placeholder:aspect-ratio=16/9></pdf-file>

toolbar takes one of a set of edges: the nearest element that names a valid one wins, in any case, and a bare toolbar, - and other values pass an outer edge on. Without any, the bar sits at the bottom.

Tokens that add up

Token lists, -, controlslist and trust:stores, add up from the outside in: the page gets the script's tokens, plus its file's, plus its own. A token written as -token drops an inherited one, and a bare - token drops them all:

html
<script src=//new.webpdf.pro/.js type=module controls controlslist="nocopy nodownload"></script>
<pdf-file id=f src=report.pdf controlslist=-nocopy></pdf-file>
<pdf-page of=f></pdf-page>                  <!-- leaves out: nodownload -->
<pdf-page of=f controlslist=-></pdf-page>  <!-- leaves out nothing -->

So controlslist=notoolbar on a file takes the bar away from its pages, and controlslist=-notoolbar on one of them brings it back. One token decides over the others: -=controls anywhere on the way turns the controls off, whatever controls says.

Values that add up

trust:src and trust:srcdoc on the script add their certificates to every file's own. A file whose value is - drops the script's value of that attribute.

From JavaScript

Properties give the effective value: page.controls is true on a page that inherits controls. Setting it writes the page's own attribute, and null removes the attribute, so the page inherits again:

js
const page = document.querySelector("pdf-page");
page.controls;          // true: inherited from the <script>
page.controls = false;  // controls=-
page.controls = null;   // no attribute: inherited again

Token lists, PDFPageElement.off and PDFElement.controlsList, are the element's own tokens, as DOMTokenList objects.

The script's attributes are live: change controls on the script, and every page follows. Its loader settings, ium, break and the other flags of the <script> page, are read once, when WebPDF loads.

See also