No page reloads
When a reader clicks a link to another page of your site, Postdoc doesn't load a new document. It fetches the next page's HTML, updates the <head>, swaps the <body> and adds an entry to the browser history. Stylesheets that both pages share stay loaded, so moving between pages is quick, and the back button restores the scroll position.
The pages are still ordinary HTML files. With JavaScript turned off, or for a search engine, links work the usual way.
Which links
Postdoc handles links to pages of the same site. The browser handles everything else as usual:
- links to other sites, and links to a section of the current page (
#install) - clicks with a modifier key, such as Ctrl-click to open a new tab
- links with a
targetother than_self, or with adownloadattribute - links to files such as PDFs or images
Screen readers and the keyboard
After a page load, a screen reader reads out the new page, and the next Tab starts from the top of it. Postdoc does the same when it shows a page in place: it announces the new page's title in a live region, and moves the focus to the top of the page. For a link to a section of another page, such as /guide/install.html#requirements, the focus moves to that section instead. When an onRender callback moves the focus itself, or the page has an element with autofocus, Postdoc leaves the focus there.
postdoc test checks that this works with your layouts and scripts.
Run code on every page
A script that loads a module, <script type="module" src="...">, runs once, when the reader opens the site. It doesn't run again when they move to another page, because the browser only runs a module once per document. Code that sets up the page, such as attaching event listeners, should run in an onRender callback instead:
import { onRender } from 'postdoc/page';
onRender(() => {
document.querySelectorAll('details').forEach((element) => {
element.addEventListener('toggle', () => console.log('Toggled'));
});
}, {
forPage: () => true
});onRender runs the callback right away if the current page matches, and again each time a matching page is shown. By default, a callback only matches the page that registered it. forPage widens that: it takes a function that receives the page's URL and returns true to run, or a regular expression that is tested against the full URL:
onRender(() => {
// Only on guide pages
}, {
forPage: /\/guide\//
});Inline scripts, like <script>...</script> without src, run again on every page they're part of.
If a callback starts work that finishes later, such as loading a library or drawing a chart, make it async or return a promise. Postdoc waits for it before it marks the page as ready.
Know when a page is ready
When a page has been shown and its onRender callbacks, including the promises they return, have finished, Postdoc sets a data-postdoc-ready attribute on the <html> element. It's removed when the reader moves to another page, and set again once that page is ready.
Tests use it to wait for content that's rendered in the browser. In a Nightwatch test:
browser.waitForElementPresent('html[data-postdoc-ready]');Page checks wait for it before they check a page.
Before a page is left
onLeave runs before the current page is replaced, with the current and the next URL. It takes the same options as onRender:
import { onLeave } from 'postdoc/page';
onLeave((currentUrl, nextUrl) => {
console.log(`Leaving ${currentUrl.pathname} for ${nextUrl.pathname}`);
}, {
forPage: () => true
});Navigate from code
import { navigateTo } from 'postdoc/page';
await navigateTo(import.meta.env.BASE_URL + 'guide/install.html');import.meta.env.BASE_URL is the site's base path, / unless you set one. Links in pages and layouts get the base path added for you, but URLs in scripts don't.
Settings
export default {
session: {
// Fetch a page as soon as the pointer moves over a link to it.
enable_prefetch: true,
// Turn navigation without reloads off, and load every page normally.
disable_spa: false
}
};