* roll Chromium to version 86, r800071
* roll Chrome DevTools protocol version to 0.0.799653
* fix HTTPRequest.continue after
* CDP: accept post data in the binary form in Fetch.continueRequest.
https://chromium-review.googlesource.com/c/chromium/src/+/2315239
* update new-docs
This corresponds to Chromium 85.0.4182.0.
This roll includes:
- Enable SameSiteByDefaultCookies and CookiesWithoutSameSiteMustBeSecure
https://crrev.com/c/2231445
- [FlexNG] Enable FlexNG by default
https://crrev.com/c/2216595Closes#6151.
* chore: vendor Mitt into src/common/third-party
As discussed in #6203 we need to vendor our common dependencies in so
that when we ship an ESM build all imports point to file paths and do
not rely on Node resolution (e.g. a browser does not understand `import
mitt from 'mitt'`).
* chore: enforce file extensions on imports
To make our output agnostic it should include file extensions in the
output, as per the ESM spec. It's a bit odd for Node packages but makes
it easier to publish a browser build.
* feat(chromium): roll Chromium to r768783
* fix: update unit test for crrev:2135046
* chore: update devtools-protocol revision
Co-authored-by: Changhao Han <changhaohan@chromium.org>
* chore: Use devtools-protocol package
Rather than maintain our own protocol we can instead use the devtools-protocol package and pin it to the version of Chromium that Puppeteer is shipping with.
The only changes are naming changes between the bespoke protocol that Puppeteer created and the devtools-protocol one.
Now the async hooks helper is gone api.ts was only used by the coverage
tools and by doclint.
DocLint is nearing the end of its lifespan with the TSDoc work, so I
focused on how best to define a list of modules for the coverage
tooling. They define an object of classes, and the path to that module.
They need the full path because we also check if the module exports any
events that need to be emitted - the coverage tool asserts that the
emitting of those events is also tested.
It's not _great_ that DocLint relies on a constant defined in the
coverage utils, but it should only be this way for a short period of
time and no one is actively working on DocLint (bar the effort to remove
it) so I don't think this is worth worrying about.
This change also broke the DocLint tests; based on the fact that DocLint is on its way out it doesn't feel worth fixing the tests, so this commit also removes them.
If you want to run TypeScript only to verify that it's typechecking correctly, this command is quicker as it doesn't output CJS and ESM to disk. Useful for checking during development.
* chore: Don't store revisions in `package.json`
It's quite messy to have to require the `package.json` file in multiple
places purely to find out what revision of a given browser we want to
use. We can also achieve better type safety by placing it in an actual
source file.
This commit makes that change and also tidies up our reliance on
`package.json` within the source code generally; we now only use it to
find the location of the Puppeteer root such that we know where to
install downloaded browsers to.
To avoid using `package.json` to parse the name of the module, we also
now explicitly have an entry point for the Puppeteer module and the
Puppeter Core module. This will make it easier in the future to ship
less code as part of core (e.g. core never needs to download a browser,
so why ship that code?). Core can also then not have any revisions based
info contained in it.
The test install script has also been updated to ensure that
puppeteer-core can be installed correctly too.
Finally, the `install` script has been moved to TypeScript for nicer
typechecking and safety. The functionality of it has not changed.
* chore(agnostic): ship CJS and ESM builds
For our work to enable Puppeteer in other environments (e.g. a browser)
we need to ship an ESM build. This commit changes our config to ship to
`lib/cjs` and `lib/esm` accordingly. The majority of our code stays the
same, with one small fix for the CJS build to ensure that we ship a
version that lets you `require('puppeteer')` rather than have to
`require('puppeteer').default`. We do this with the `cjs-entry.js` which
is what the `main` field in our `package.json` points to.
We also swap to `read-pkg-up` to find the `package.json` file. This is
because the folder structure of `lib/` does not match `src/` now we ship
to `cjs` and `esm`, so you cannot rely on exact paths. This module works
up from the file to find the nearest `package.json` so it will always
find Puppeteer's `package.json`.
Note that we *do not* point any users to the ESM build. We happen to
ship those files so people who know about them can get at them but it's
not expected (nor will we actively support) that people will rely on
them. The CommonJS build is considered our main build.
We may make breaking changes to the structure of the ESM build which we
will do without requiring new major versions. For example the ESM build
currently ships all files that the CJS build does, but given we are
working on the ESM build being able to run in the browser this may
change over time.
Long term once the Node versions catch up we can ditch CJS and ship
exclusively ESM but we are not there yet.
This CL migrates all the tests to TypeScript. The main benefits of this is that we start consuming our TypeScript definitions and therefore find errors in them. The act of migrating found some bugs in our definitions and now we can be sure to avoid them going forwards.
You'll notice the addition of some `TODO`s in the code; I didn't want this CL to get any bigger than it already is but I intend to follow those up once this lands. It's mostly figuring out how to extend the `expect` types with our `toBeGolden` helpers and some other slight confusions with types that the tests exposed.
Co-authored-by: Mathias Bynens <mathias@qiwi.be>
Without the API-* dependencies pinned different versions may be
installed on local machines vs CI. One of the checks we do is to check
that the checked in docs matches what is generated on CI. Therefore we
need to ensure devs locally run the exact version that CI runs such that
they generate the same output. So in this case we pin to a particular
version of the dependencies.
As far as I can tell these became irrelevant as of v1.15 which added
`puppeteer.errors` and `puppeteer.devices [1]. This is a breaking change
but one that's easily mitigated. We've said that we don't consider
changes to our folder/file structure a breaking change, but we can't
really do that if we have these two top level files that we've
documented.
[1]: e3abb0aa32 (diff-522b24108d7446af4c59873472a90444)
It was causing some infra issues when trying to migrate tests to
TypeScript (that's WIP in another branch that I'll have up soon). It's
unusual to have the entire src in TS except for the main file, which
then reaches into the compiled `lib` directory for the files it needs.
Much better is to move the entry point into TypeScript itself and update
the `main` entry in our `package.json` to point to the compiled output.
This also has the advantange of hooking up all the TS type defs that we
are shipping and will make that process easier too, along with making it
easier to port our tests to TypeScript.
`api.ts` is a list of all our modules which is used to install a helper
and by DocLint. It's not that useful for our dep graph because it
literally requires the majority of modules so it just clutters up the diagram.
`--max-depth` stopped the chart including our own modules. What we want
instead is the `do-not-follow` option to make it go to infinite depth in
our code but stop at the top level of a node module.
* chore: ensure new-docs are up to date
This adds a Travis check that if we re-generate the docs we get the
exact output (by checking if the Git tree is dirty).
We do the dirty check by using `git status --porcelain`, seeing how many
lines that outputs, and using that as the exit code (taking only the
first 255 lines to avoid invalid exit codes). `--porcelain` makes the
output be empty if the repo is not dirty in anyway which translates into
an exit code of 0.
We can't use `git diff-index --quiet HEAD` as it exits with 0 if there are
untracked files in the repo but we want that to cause a failure.
I've had misleading type errors due to left over builds or tests
behaving oddly. We should just strip the entire folder out before
building again so there's no left over artefacts that could cause
issues.
The `|| true` in the command is so if `rm` errors because the folder
doesn't exist, it doesn't exit with an error code.
Replacing the Node EventEmitter with Mitt caused more problems than
anticipated for end users due to the API differences and the amount of
people who relied on the EventEmitter API. In hindsight this clearly
should have been explored more and then released as a breaking v4.
This commit rolls us back to the built in Node EventEmitter library
which we can release to get everyone back on stable builds. We can then
consider our approach to migrating to Mitt and when we do do that we can
release it as a breaking change and properly document the migration
strategy and approach.
* chore: migrate to Mitt as the EventEmitter
This commit moves us to using Mitt [1] for the event emitter in
Puppeteer. This removes our dependency to Node's EventEmitter which is
part of a larger stream of work to enable a Puppeteer-web version that
doesn't depend on Node.
There are no large breaking changes as we support the main methods that
EventEmitter had, but it also provides some methods that Puppeteer
didn't use. Technically end users could depend on this but it's
unlikely.
[1]: https://github.com/developit/mitt
This script generated an `index.d.ts` file but that file was never
commited to git nor included in Puppeteer when we ship. As of right now
people who want TS types can install from the DefinitelyTyped repo and
we are working on shipping types from Puppeteer itself.
Therefore this script is not adding any value and can be removed.
This corresponds to Chromium 83.0.4103.0.
This roll includes:
- Enable SameSiteByDefaultCookies and CookiesWithoutSameSiteMustBeSecure https://crrev.com/c/2122809
Sticking to a specific version of TS rather than a ^ version so we know
everyone is on the exact same version. Think that's preferable for such
an important dependency.
* Warn when given unsupported product name.
Fixes#5844.
This change means when a user launches Puppeteer with a product name
that is not supported (which at the time of this commit means it's not
`firefox` or `chrome) we will warn them about it.
Decided on just a warning vs an error because the current behaviour is
that we fallback to launching Chrome and I don't think this warrants a
breaking change.
* chore: remove src/externs.d.ts
It defined global types that we don't want to use, and instead we move
to using interfaces that we import and reference just like with any
other interface.
This means other than Protocol (which I think is fine to leave as is),
there are no other magic global types and you have to import any types
or interfaces that you want.
* chore: update how we track coverage during unit tests
The old method of tracking coverage was causing issues. If a test failed
on CI, that test's failure would be lost because the test failing would
in turn cause the coverage to fail, but the `process.exit(1)` in the
coverage code caused Mocha to not output anything useful.
Instead the coverage checker now:
* tracks the coverage in memory in a Map (this hasn't changed)
* after all tests, writes that to disk in test/coverage.json (which is
gitignored)
* we then run a single Mocha test that asserts every method was called.
This means if the test run fails, the build will fail and give the error
about that test run, and that output won't be lost when the coverage
then fails too.
Co-authored-by: Mathias Bynens <mathias@qiwi.be>
* chore: enforce src/protocol.d.ts is in sync
On CI we run `npm run compare-protocol-d-ts` which checks that the file
on disk is up to date with the protocol we fetch from the browser.
Co-authored-by: Mathias Bynens <mathias@qiwi.be>
We don't support it and v3 shipped without including puppeteer-web in the browser. People are welcome to manually use Browserify to try to get Puppeteer running in a browser but it ultimately isn't our primary focus right now.
Getting puppeteer-core able to run in a browser is something we'll be looking at in the future so we'll revisit this soon.
* chore: add test for npm package installing correctly
This command packs up the module and installs it again to check we're
correctly bundling everything we need to allow users to do a fresh
install.
* install realpath
The codebase was incredibly inconsistent with the use of spacing around
curly braces, e.g.:
```
// this?
const a = {b: 1}
// or?
const a = { b: 1 }
```
This extended into import statements also. Google's styleguide is no
spacing, so we're going with that.
Rather than a denylist (`.npmignore`) we can instead use an allowlist
via the `files` option in `package.json`. This makes it much harder to
accidentally include files or folders in the build as you have to
explicitly list the files that will be included.
Fixes#5648.
The change to the install script to require TypeScript works fine when
installing from npm (because on npm the `lib` directory with the
compiled code already exists) but doesn't if you install from a GitHub
URL. By default it seems npm uses the `files` list when you install from
GitHub which means it's missing a bunch of files that we need to
compile.
Additionally by default when installing from a GitHub URL npm doesn't
install the dependencies which is an issue for us when we need to
compile TypeScript.
The fix is to create a `prepare` script that runs TypeScript if
required. From the npm docs [1]:
> `prepare`: Run both BEFORE the package is packed and published, on
> local npm install without any arguments, and when installing git
> dependencies
And from the npm docs on install [2], it confirms that if a package has
a `prepare` script it is run when installing from GitHub:
> As with regular git dependencies, dependencies and devDependencies
> will be installed if the package has a prepare script, before the
> package is done installing.
Despite having the `prepare` script we still need the TypeScript check
in `install.js` to satisfy the 3rd scenario below where we need to force
a compile:
* If I'm a user installing `puppeteer@X` from npm, the module is
published with the `lib/` directory of compiled code, so I'm set.
* If I'm a user installing Puppeteer from GitHub, the `prepare` script
will run TypeScript for me so I'm set.
* If I'm a developer working on Puppeteer, the `prepare` script also
runs but _after_ `npm install` which means `install.js` fails as it
requires `./lib/helper.js`. So in `install.js` we call
`compileTypeScriptIfRequired` to catch this case.
[1]: https://docs.npmjs.com/misc/scripts
[2]: https://docs.npmjs.com/cli/install
Co-authored-by: Mathias Bynens <mathias@qiwi.be>
Fixes#5660.
This commit adds linting for `*.ts` files and loads up the recommended
list of TS rules from the ESLint TypeScript plugin. We can adjust the
exact rules overtime, but starting with the recommended list seems
sensible.
extract-zip removed support for callbacks and instead uses promises. Moreover, it has TypeScript support which allows us to remove the @types/extract-zip package.
This update allows downstream users to remove their installation of mkdirp, which uses a vulnerable version of minimist.
For more info, see https://github.com/maxogden/extract-zip/releases/tag/v2.0.0
Co-authored-by: Mathias Bynens <mathias@qiwi.be>
This commit updates all the non-Puppeteer unit tests to run using Mocha and then deletes the custom test runner framework from this repository. The documentation has also been updated.
Rather than maintain our own test runner we should instead lean on the community and use Mocha which is very popular and also our test runner of choice in DevTools too.
Note that this commit doesn't remove the TestRunner source as it's still used for other unit tests, but they will be updated in a future PR and then we can remove the TestRunner.
The main bulk of this PR is updating the tests as the old TestRunner passed in contextual data via the `it` function callback whereas Mocha does not, so we introduce some helpers for the tests to make it easier.
Rather than use our own custom expect library, we can use expect from npm [1], which has an API almost identical to the one Puppeteer has, but with more options, better diffing, and is used by many in the community as it's the default assertions library that comes with Jest.
It's also thoroughly documented [2].
[1]: https://www.npmjs.com/package/expect
[2]: https://jestjs.io/docs/en/expect
This updates our `tsconfig.json` so it emits our JavaScript files as
well as type checking them. We compile into `./lib` which we then ship
in our npm package. The source code has moved from `./lib` into `./src`.
Because the `src/` directory is exclusively JS files, this change is a
no-op in terms of code functionality but is the first step towards being
able to replace `src/X.js` with `src/X.ts` in a way that allows us to
migrate incrementally.
The `lib` directory is gitignored, and the `src` directory is
npmignored. On `npm publish` we will now run `npm run tsc` in order to
generate the outputted code.
TypeScript seems to struggle to understand `Promise.all` when the items in the array return different types. If we were authoring in TS we could fix this with TS generics (`Promise.all<OurTypeHere>(...)`) but for now we can typecast the result. We'll fix this properly when we author in TS.
Continues the work to get up to TS 3.8 (latest release at time of writing).
This version of TS introduced built in definitions for web workers that include an `interface Worker` so TS gets confused when it sees us reference a `Worker`. I have renamed the imports to `PuppeteerWorker` as I couldn't figure out a way to tell TS to not load in the worker types; longer term we might consider renaming `Worker` to `PuppeteerWorker` (or an alternative) but that would be a breaking change that we don't need right now.
The other fix is similar; TypeScript doesn't differentiate between the built-in `WebSocket` type and the `ws` library. Renaming the import solves this too.
TS 3.5 got much stricter on writing changes to objects with varied types [1] so we have to do a bit of typecasting work to convince TS about the types of keys and values that we are setting.
Longer term we should think about a better data structure that avoids us having to jump through some hoops but for now I think this is a reasonable step to get us onto 3.5.
Same story regarding bindings on `window`: the easiest fix is to cast `window` to `any` for the code that adds to it. I'm sure we can come up with a more type-safe way of doing this in the future.
[1]: https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#fixes-to-unsound-writes-to-indexed-access-types
* (feat) Add option to fetch Firefox Nightly
Add Firefox support to BrowserFetcher and the install script.
By default, the latest Firefox Nightly is downloaded
directly from archive.mozilla.org (dmg, tar.bz2 and zip)
This also required changes that impact `puppeteer.launch()`
and `puppeteer.executablePath()`
Fixes#5151
* Update docs/api.md
Co-Authored-By: Mathias Bynens <mathias@qiwi.be>
* Clean up revision promise
* Improve error handling in revision check
* Remove matchAll
* Use explicit octal mode
* Update .gitignore
Co-authored-by: Mathias Bynens <mathias@qiwi.be>
* chore: update relevant Node.js versions from 8 to 10
* chore: remove node6 and node8 folders from puppeteer-firefox ci
* fix: loosen definition for proc.stdio
* fix: update typescript version used in npm run test-types
This changes the Chromium revision to r722234 (Chrome 80.0.3987.0),
since that's the most recent version in the Chromium 80 range for
which a download exists for all supported platforms.
https-proxy-agent requires agent-base, which currently monkey-patches the core `https` Node module, causing problems in unrelated code. The latest version of https-proxy-agent uses the latest version of agent-base which no longer does this monkey patching.
* fix: prepare jsHandle.uploadFile for CDP Page.handleFileChooser removal
https://chromium-review.googlesource.com/c/chromium/src/+/1935410
removes Page.handleFileChooser from the CDP.
* fix: improve binary file support
UTF-8-decoding the input file could fail for binary files, and so we
now read the raw file buffer and base64-encode it. To base64-decode it
within the page context, we use the Fetch API in combination with a
data URL. This requires knowing the proper MIME type for the input
file, which we now figure out using the new mime-types dependency.
* feat: Set which browser to launch via PUPPETEER_PRODUCT
This change introduces a PUPPETEER_PRODUCT environment
variable as a first step toward using Puppeteer with
many different browsers. Setting PUPPETEER_PRODUCT=firefox, for
example, enables Firefox-specific Launcher settings.
The state is also exposed as `puppeteer.product` in the API
to support adding other product-specific behaviour as needed.
The bulk of the change is a refactoring in Launcher
to decouple generic browser start-up from product-specific
configuration.
Respecting the puppeteer-core restriction for PUPPETEER_
environment variables, lazily instantiate the Launcher
based on a `product` Puppeteer.launch option, if available.
* test: Distinguish Juggler unit tests from Firefox
The funit script is renamed to fjunit (j for Juggler, which is
used only by the experimental puppeteer-firefox package.
In contrast, the funit script now refers to running Puppeteer
unit tests against the main puppeteer package with Firefox.
To do so with Firefox Nightly, run:
`BINARY=path/to/firefox npm run funit`
A number of changes in this patch make it easier to run
Puppeteer unit tests in Mozilla's CI.
Node.js v6 was end-of-life'd in April, 2019, with AWS Lambda prohibiting updaets to the Node.js v6 runtime since June 30, 2019.
This makes it quite safe for us to remove the Node 6 support from the repository.
This roll includes:
- https://crrev.com/681997 - Turn on default SiteInstance by default.
The SiteInstance by default was breaking "devtools: true" option, so
there's a new feature we disable now by default.
This keeps pressuring us towards OOPIF support since that's an
inevitable future.
* feat(chromium): roll Chromium to r665405
This roll includes:
- https://crrev.com/665226 - DevTools: make interception respect cross-process frame boundaries
This fixes page loading with dynamic OOPIFs - test is added.
Fix#4442
* fix lint
This roll includes:
- [inspector_protocol:8ec18cf](8ec18cf088) Support STRING16 in the template when converting CBOR map keys
to protocol::Value.
- [inspector_protocol:37518ac](37518ac421) fix parsing of the last ASCII character
This fixes protocol handling of UTF8 in both V8 and Chromium.
Fixes#4443.
This roll includes:
- https://crrev.com/653809 - FrameLoader: ignore failing provisional loads entirely
- https://crrev.com/654750 - DevTools: make sure Network.requestWillBeSent is emitted on time for sync xhrs
The FrameLoader patch is the reason behind the test change. It's
actually desirable to fail frame navigation if the frame detaches - and
that's consistent with Firefox.
Fixes#4337
Introduce a `npm run funit` script that runs puppeteer tests
against Puppeteer-Firefox.
Next steps:
- bring Puppeteer-Firefox unique tests to Puppeteer
- skip failing tests and run Puppeteer-Firefox on CI
- work through tests to pass them all with Puppeteer-Firefox
This roll includes:
- https://crrev.com/624247 - DevTools: Allow DOM.resolveNode to resolve
into isolated worlds
- https://crrev.com/624486 - DevTools: addScriptToEvaluateOnNewDocument
should work with disabled javascript
This roll includes:
- https://crrev.com/619087 - DevTools: support interception for file: schema
- https://crrev.com/616936 - Complete the screen capture color space plumbing
This should allow us to switch to network service by default.
Note: We now have to force a specific color space since https://crrev.com/616936
tries to pick the system one.
This roll includes:
- https://crrev.com/609886 - DevTools: force-detach worker sessions
on navigation
This should eliminate flakiness with our worker test.
Also, new Chrome now exposes a new type in its protocol - binary.
It becomes a raw C++ array once used through C++ bindings, but for
us it's still a base64 string.
This roll includes:
- https://crrev.com/599782 DevTools: force a style recalc before reporting final CSS coverage
- https://crrev.com/599769 DevTools: Expose more properties through the accessibility protocol
References: #2033
This upgrades us to TypeScript 3.1.1, which fixes some build failures. Annoyingly TypeScript does a better job of checking `process.stdio`, which exposes that the DefinitelyTyped definition for it is wrong. See https://github.com/DefinitelyTyped/DefinitelyTyped/issues/11587. I'll look into submitting a patch for that later.
This patch:
- adds "browser" field to the package.json with default
bundling options.
- introduces "bundle" and "unit-bundle" commands to
create bundle and test bundle
- starts running bundle tests on Travis Node 8 bots
Fixes#2374.
This roll includes:
- https://crrev.com/584293 - DevTools: execute scripts in addScriptToEvaluateOnLoad in order
- https://crrev.com/585630 - DevTools: introduce Browser.grantPermissions
- https://crrev.com/587156 - Revert "[Base] Use background mode for ThreadPriority::BACKGROUND threads (behind feature) (reland)."
The "revert" patch fixes headless functionality on windows.
References #846.
Fixes#3106.
This patch rolls Chromium to r579032. The patch includes:
- https://crrev.com/577366 - DevTools: report redirect responses only if response interception is enabled
- https://crrev.com/577212 - DevTools: intercept requests resulting from redirects
- https://crrev.com/578934 - DevTools: Add a protocol method to insertText
Interception Logic in DevTools protocol has changed regarding redirects;
this patch migrates interceptions to dispatch "request" events based on
requestWillBeSent event.
This roll includes:
- https://crrev.com/574785 - DevTools: allow tracing over the remote debugging pipe.
This fixes tracing over the remote debugging pipe.
This roll includes:
- https://crrev.com/567104 - DevTools: introduce Target.exposeDevToolsProtocol() method
The patch includes a drive-by fix to DevToolsAgentHostImpl that
eliminats chromium crashes in certain cases.
This patch drops the markdown-toc module and instead rolls out
our own simple markdown table-of-contents generator.
As a side effect, it fixes links to `page.$` and `page.$$`.
Previously protocol.d.ts was generated on `npm run tsc`. This was inconvenient because it meant that vscode checking was wrong until type checking was run manually, and was inefficient because it necessarily regenerated the types even if no new Chromium was downloaded. This patch generates the types when npm install is run from the github checkout, assuming a new Chromium revision was downloaded.
This roll includes:
- https://crrev.com/551261 - DevTools: page.navigate should fail when server returned HTTP 204
- https://crrev.com/550319 - DevTools: fix resource mimetype for request interception of file:// urls
References #1879
References #1506
This roll includes:
- https://crrev.com/549003 - DevTools: make pptr tests pass with DCHECKs.
The patch fixes a browser crash that happens during browser close.
As a result, cookies were not saved properly (and thus the flaky test we
had).
Fixes#1537.
This uses the `/json/protocol` endpoint to generate type definitions for the protocol.
Currently it is lacking protocol events and commands, but I will add those later.
This roll includes:
- https://crrev.com/547982 - v8 roll that includes [fixed
Runtime.callFunctionOn](1637818671) method
The upstream fix makes it possible to run frame.waitFor* functions on
pages with strict CSP.
References #1229.
This roll includes the following important CLs:
- https://crrev.com/545955 - DevTools: Update page scale immediately in InputHandler
- https://crrev.com/544446 - Make HeadlessWebContentsImpl::Close wait for the renderer to go
- https://crrev.com/546865 - DevTools(Headless): close WebContents when closed via
'window.close'
- https://crrev.com/546685 - Headless: Add support for the --remote-debugging-pipe flag
This should drastically reduce flakiness for pptr input events.
This patch:
- removes the "tags: true" field, we want to publish every commit
- makes sure we publish from node7 only
- prebuilds node6 before publishing
This patch rolls chromium to r524617. This roll includes:
- http://crrev.com/523674 - Headless printing: refactor print template
to allow header/footer customization.
References #373
