rooseveltframework
diff --git a/‎CHANGELOG.md‎
Lines changed: 18 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 32 additions & 15 deletions b/‎README.md‎
Lines changed: 32 additions & 15 deletions
@@ -4,6 +4,24 @@
 
 - Put your changes here...
 
+## 1.2.0
+
+- Added view transition support in the default render method.
+- Added support for multiple DOM update targets in the default render method.
+- Added `req.backButtonPressed` and `req.forwardButtonPressed` to `app`.
+- Added classes `backButtonPressed` and `forwardButtonPressed` which will populate on the `<html>` element if either button was pressed.
+- Added `[data-page-title]` to the top of the list of accepted query selectors for sourcing content to announce to screen readers when a new page is rendered.
+- Added new params to the `res.beforeRender(params)`, `beforeEveryRender(params)`, `res.afterRender(params)`, and `afterEveryRender(params)` methods:
+  - It now supplies an object with:
+    - `model`: The data model supplied to the template to be rendered.
+    - `doc`: The document object created from the template after it is rendered.
+    - `markup`: The HTML string that will be written to the page.
+    - `targets`: The list of DOM nodes that will be updated.
+- Fixed a bug that caused `postRenderCallbacks` not to function properly.
+- Fixed a bug related to script tags from the rendered page being executed unnecessarily.
+- Fixed a bug causing unnecessary outlines to appear on page transitions in Safari.
+- Updated dependencies.
+
 ## 1.1.1
 
 - Fixed crash related to unfinished HTML validation feature.
 
@@ -3,7 +3,9 @@
 [![Build Status](https://github.com/rooseveltframework/single-page-express/workflows/CI/badge.svg
 )](https://github.com/rooseveltframework/single-page-express/actions?query=workflow%3ACI) [![npm](https://img.shields.io/npm/v/single-page-express.svg)](https://www.npmjs.com/package/single-page-express)
 
-A client-side implementation of the [Express](http://expressjs.com) route API. It works by hijacking links and form submits, then providing a direct imitation of the Express route API to handle "requests" (click or submit events) and issue "responses" in the form of DOM updates. It will update the browser history to match the route accordingly, update the scroll position appropriately, and there are hooks available for setting animations as well.
+A client-side implementation of the [Express](http://expressjs.com) route API. It works by hijacking links and form submits, then providing a direct imitation of the Express route API to handle "requests" (click or submit events) and issue "responses" in the form of DOM updates.
+
+When a `single-page-express` route is triggered, it will update the browser history state to match the route accordingly, update the scroll position appropriately, set focus appropriately, will start a [view transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) to animate the DOM updates, and there are hooks available to customize the animations as well. If view transitions are not supported in the browser, the page will transition, but it will not animate unless you set a custom animation using another animation technique.
 
 This allows you to write isomorphic (aka universal, [amphibious](https://twitter.com/kethinov/status/566896168324825088), etc) router code that can be shared verbatim on the client and the server in your Express application.
 
@@ -46,8 +48,8 @@ The package is distributed with the following builds available:
 Then, in your frontend code:
 
 ```javascript
-const templatingEngine = // define which templating engine to use here
-const templates = // load some templates here
+const templatingEngine = require('') // define which templating engine to use here
+const templates = {} // load some templates here
 ```
 
 For `templatingEngine`, use something like [teddy](https://github.com/rooseveltframework/teddy), [mustache](https://github.com/janl/mustache.js/), or any other templating system that supports Express and works in the browser.
@@ -191,7 +193,7 @@ There are 3 sample apps you can run to see demos of how `single-page-express` ca
 The default render method will handle both full page renders as well as rendering partials:
 
 - If you set `res.title`, the page's title will be updated with its contents. Alternatively, if the template render output contains a `<title>` tag, the page's title will be updated with its contents.
-  - When the new page is rendered, it will be announced to screen readers. The content to read to screen readers will be sourced from one of the following querySelectors: `h1[aria-label]`, `h1`, or `title` in that order.
+  - When the new page is rendered, it will be announced to screen readers. The content to read to screen readers will be sourced from one of the following querySelectors: `[data-page-title]`, `h1[aria-label]`, `h1`, or `title` in that order.
 - If the template render contains an `<html>` or `<head>` tag and there are new attributes on the `<html>` or `<head>` tags that aren't present in the current document, those attributes will be set on the current document. This behavior is additive or replacement-level only. Attributes cannot be removed simply by omitting them in the template render. If you want to remove an attribute, do it with JavaScript, or set it to a different value in your template render.
 - If there are any new children for the `<head>` in the template render, they will be inserted into the current document's `<head>` tag if they are not present already.
   - If any of the new tags are `<link>` or `<script>` tags, the DOM update will be delayed until those external files load to prevent a [flash of unstyled content](https://en.wikipedia.org/wiki/Flash_of_unstyled_content).
@@ -204,8 +206,10 @@ The default render method will handle both full page renders as well as renderin
   - If you set `res.removeHeadTags`, all tags except `<title>` will be removed from the `<head>` before adding any new ones.
 - If you set `res.target`, the DOM will be updated at that spot. `res.target` is a query selector, so an example value you could give it would be `#my-container`. That would replace the contents of the element with the id "my-container" with the output of your rendered template.
   - If the output of your rendered template also has an element matching the same query selector, then the contents of that portion of the output will be all that is used to replace the target.
-  - If you do not set `res.target`, the contents of the `<body>` tag will be replaced with the output of your rendered template.
-- If you set `res.focus`, the browser's focus will be set to that element after the page is rendered. If you do not set `res.focus`, then the browser's focus will be set to the first non-inert element in the DOM with the `autofocus` attribute, or, if none are present, it will be set to whatever the target element was set to for the DOM update.
+  - If you do not set `res.target` and neither `app.defaultTarget` nor `app.defaultTargets` is set, then the contents of the `<body>` tag will be replaced with the output of your rendered template.
+  - You can also supply an array of query selectors to `res.target`. Elements found matching the query selectors in the array will be replaced with the corresponding query selectors from the rendered template.
+  - If you set `res.appendTargets = true`, any new target(s) you add will be in addition to whatever is set by `app.defaultTarget` or `app.defaultTargets`.
+- If you set `res.focus`, the browser's focus will be set to that element after the page is rendered. If you do not set `res.focus`, then the browser's focus will be set to the first non-inert element in the DOM with the `autofocus` attribute, or, if none are present, it will be set to whatever the target element was set to for the DOM update. If there are multiple targets, the first target on the list will be what is selected.
 - There are also hooks for setting animations as well. See "Hooks for setting animations" below.
 
 If this DOM manipulation behavior is undesirable to you, you can supply your own render method instead and do whatever you like. To supply your own render method, see the constructor parameter documentation below.
@@ -229,18 +233,27 @@ These constructor params are only relevant if you're not supplying a custom rend
 
 ##### Pre-render
 
-- `beforeEveryRender(model)`: Optionally supply a function to execute just before your template is rendered and written to the DOM. Useful for beginning a CSS transition.
-  - You can also set `res.beforeRender(model)` on a per request basis.
+- `beforeEveryRender(params)`: Optionally supply a function to execute just before your template is rendered and written to the DOM. Useful for beginning a CSS transition.
+  - You can also set `res.beforeRender(params)` on a per request basis.
+  - The `params` argument contains:
+    - `model`: The data model supplied to the template to be rendered.
+    - `doc`: The document object created from the template after it is rendered.
+    - `markup`: The HTML string that will be written to the page.
+    - `targets`: The list of DOM nodes that will be updated.
 - `defaultTarget`: Query string representing the default element to target if one is not supplied by `res.target`. Defaults to the `<body>` tag if neither `res.target` or `app.defaultTarget` is supplied.
+- `defaultTargets`: Array of query strings representing elements to target for replacement if such an array is not supplied by `res.target`. Elements found matching the query strings in the array will be replaced with the corresponding query string from the rendered template.
 - `updateDelay`: How long to wait in milliseconds between rendering the template and writing its contents to the DOM. This is useful to give your animations time to animate if you're using animations. Default: `0`
   - You can also set `res.updateDelay` on a per request basis.
 
 ##### Post-render
 
-- `afterEveryRender(model)`: Optionally supply a function to execute just after your template is rendered and written to the DOM. Useful for finishing a CSS transition.
-
-  - You can also set `res.afterRender(model)` on a per request basis.
-
+- `afterEveryRender(params)`: Optionally supply a function to execute just after your template is rendered and written to the DOM. Useful for finishing a CSS transition.
+  - You can also set `res.afterRender(params)` on a per request basis.
+  - The `params` argument contains:
+    - `model`: The data model supplied to the template rendered.
+    - `doc`: The document object created from the template after it was rendered.
+    - `markup`: The HTML string that was written to the page.
+    - `targets`: The list of DOM nodes that were updated.
 - `postRenderCallbacks`: Optionally supply an object with keys that are template names and values that are functions to execute after that template renders. You can also supply `*` as a key to execute a post-render callback after every template render.
 
 ### Application object
@@ -254,6 +267,7 @@ When you call the constructor, it will return an `app` object.
 - `appVars`: List of variables stored via `app.set()` and retrieved with `app.get()`.
 - `beforeEveryRender`: Function to execute before every template render sourced from the constructor params.
 - `defaultTarget`: Query string representing the default element to target if one is not supplied by `res.target`.
+- `defaultTargets`: Optional array of query strings representing elements to target for replacement if such an array is not supplied by `res.target`.
 - `expressVersion`: Which version of the Express API to use for route string parsing sourced from the constructor params.
 - `postRenderCallbacks`: List of callback functions to execute after a render event occurs sourced from the constructor params.
 - `routes`: List of routes registered with `single-page-express`.
@@ -366,6 +380,8 @@ Likewise all other `req` methods [from the Node.js API](https://nodejs.org/api/h
 
 #### New properties defined by single-page-express
 
+- `req.backButtonPressed`: This will be `true` when the browser back button was pressed. A class `backButtonPressed` will also be added to the `<html>` element.
+- `req.forwardButtonPressed`: This will be `true` when the browser forward button was pressed. A class `forwardButtonPressed` will also be added to the `<html>` element.
 - `req.singlePageExpress`: This property will always be set to `true`. You can use it to detect whether your route is executing in the `single-page-express` context or not.
 
 ### Response object
@@ -380,8 +396,9 @@ Likewise all other `req` methods [from the Node.js API](https://nodejs.org/api/h
 
 ##### New properties defined by single-page-express
 
-- `res.afterRender(model)`: If using the default render method, you can set this to a function that will execute after every render.
-- `res.beforeRender(model)` If using the default render method, you can set this to a function that will execute before every render.
+- `res.addTargets`: If using the default render method, use this variable to set an array of query selectors representing elements to target for replacement in addition to whatever is set by `app.defaultTargets`. Elements found matching the query strings in the array will be replaced with the corresponding query string from the rendered template.
+- `res.afterRender(params)`: If using the default render method, you can set this to a function that will execute after every render.
+- `res.beforeRender(params)` If using the default render method, you can set this to a function that will execute before every render.
 - `res.focus`: If using the default render method, if you set `res.focus`, the browser's focus will be set to that element after the page is rendered. If you do not set `res.focus`, then the browser's focus will be set to the first non-inert element in the DOM with the `autofocus` attribute, or, if none are present, it will be set to whatever the target element was set to for the DOM update.
 - `res.removeBaseTags`: If using the default render method, this will remove any `<base>` tags from the page before doing the DOM update.
 - `res.removeHeadTags`: If using the default render method, this will remove all children of the `<head>` tag except the title element from the page before doing the DOM update.
@@ -390,7 +407,7 @@ Likewise all other `req` methods [from the Node.js API](https://nodejs.org/api/h
 - `res.removeScriptTags`: If using the default render method, this will remove any `<script>` tags from the page before doing the DOM update.
 - `res.removeStyleTags`: If using the default render method, this will remove any `<style>` tags from the page before doing the DOM update.
 - `res.removeTemplateTags`: If using the default render method, this will remove any `<template>` tags from the page before doing the DOM update.
-- `res.target`: If using the default render method, use this variable to set a query selector to determine which element's contents will be replaced by your template render's contents. If none is supplied, the `<body>` tag's contents will be replaced.
+- `res.target`: If using the default render method, use this variable to set a query selector or array of query selectors to determine which DOM node contents will be replaced by your template render's contents. If none is supplied, and neither `app.defaultTarget` nor `app.defaultTargets` is set, then the contents of the `<body>` tag will be replaced with the output of your rendered template.
 - `res.title`: If using the default render method, use this variable to set a page title for the new render.
 - `res.updateDelay`: If using the default render method, use this variable to set a delay in milliseconds before the render occurs. If not using the default render method, this property will still allow you to specify a delay before resetting the scroll position.
 - `res.resetScroll`: Purges the memory of the scroll position for this route so that scroll position is reset to the top for this page and all its child containers.