docs: clarify headerTemplate

docs/api/web-contents.md

@@ -1472,12 +1472,7 @@ win.webContents.print(options, (success, errorType) => {
     * `right` number (optional) - Right margin in inches. Defaults to 1cm (~0.4 inches).
   * `pageRanges` string (optional) - Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
   * `ignoreInvalidPageRanges` boolean (optional) - Whether to silently ignore invalid but successfully parsed page ranges, such as '3-2'. Defaults to false.
-  * `headerTemplate` string (optional) - HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
-    * `date`: formatted print date
-    * `title`: document title
-    * `url`: document location
-    * `pageNumber`: current page number
-    * `totalPages`: total pages in the document
+  * `headerTemplate` string (optional) - HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: `date` (formatted print date), `title` (document title), `url` (document location), `pageNumber` (current page number) and `totalPages` (total pages in the document). For example, `<span class=title></span>` would generate span containing the title.
   * `footerTemplate` string (optional) - HTML template for the print footer. Should use the same format as the `headerTemplate`.
   * `preferCSSPageSize` boolean (optional) - Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size.
 

docs/api/webview-tag.md

@@ -578,12 +578,7 @@ Prints `webview`'s web page. Same as `webContents.print([options])`.
     * `right` number (optional) - Right margin in inches. Defaults to 1cm (~0.4 inches).
   * `pageRanges` string (optional) - Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
   * `ignoreInvalidPageRanges` boolean (optional) - Whether to silently ignore invalid but successfully parsed page ranges, such as '3-2'. Defaults to false.
-  * `headerTemplate` string (optional) - HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
-    * `date`: formatted print date
-    * `title`: document title
-    * `url`: document location
-    * `pageNumber`: current page number
-    * `totalPages`: total pages in the document
+  * `headerTemplate` string (optional) - HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: `date` (formatted print date), `title` (document title), `url` (document location), `pageNumber` (current page number) and `totalPages` (total pages in the document). For example, `<span class=title></span>` would generate span containing the title.
   * `footerTemplate` string (optional) - HTML template for the print footer. Should use the same format as the `headerTemplate`.
   * `preferCSSPageSize` boolean (optional) - Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size.
 

docs/breaking-changes.md

@@ -14,6 +14,62 @@ This document uses the following convention to categorize breaking changes:
 
 ## Planned Breaking API Changes (20.0)
 
+### API Changed: `webContents.printToPDF()`
+
+`webContents.printToPDF()` has been modified to conform to [`Page.printToPDF`](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF) in the Chrome DevTools Protocol. This has been changes in order to
+address changes upstream that made our previous implementation untenable and rife with bugs.
+
+**Arguments Changed**
+
+* `pageRanges`
+
+**Arguments Removed**
+
+* `printSelectionOnly`
+* `marginsType`
+* `headerFooter`
+* `scaleFactor`
+
+**Arguments Added**
+
+* `headerTemplate`
+* `footerTemplate`
+* `displayHeaderFooter`
+* `ignoreInvalidPageRanges`
+* `margins`
+* `scale`
+* `preferCSSPageSize`
+
+```js
+// Main process
+const { webContents } = require('electron')
+
+webContents.printToPDF({
+  landscape: true,
+  displayHeaderFooter: true,
+  printBackground: true,
+  scale: 2,
+  pageSize: 'Ledger',
+  margins: {
+    top: 2,
+    bottom: 2,
+    left: 2,
+    right: 2
+  },
+  pageRanges: '1-5, 8, 11-13',
+  headerTemplate: '<h1>Title</h1>',
+  footerTemplate: '<div><span class="pageNumber"></span></div>',
+  preferCSSPageSize: true
+}).then(data => {
+  fs.writeFile(pdfPath, data, (error) => {
+    if (error) throw error
+    console.log(`Wrote PDF successfully to ${pdfPath}`)
+  })
+}).catch(error => {
+  console.log(`Failed to write PDF to ${pdfPath}: `, error)
+})
+```
+
 ### Default Changed: renderers without `nodeIntegration: true` are sandboxed by default
 
 Previously, renderers that specified a preload script defaulted to being

shell/browser/api/electron_api_web_contents.cc

@@ -2810,6 +2810,8 @@ void WebContents::Print(gin::Arguments* args) {
                      std::move(callback), device_name, silent));
 }
 
+// Partially duplicated and modified from 
+// headless/lib/browser/protocol/page_handler.cc;l=41
 v8::Local<v8::Promise> WebContents::PrintToPDF(const base::Value& settings) {
   v8::Isolate* isolate = JavascriptEnvironment::GetIsolate();
   gin_helper::Promise<v8::Local<v8::Value>> promise(isolate);

shell/browser/printing/print_view_manager_electron.cc

@@ -33,6 +33,10 @@ constexpr char kInvalidRequestPrintPreviewCall[] =
 
 }  // namespace
 
+// This file subclasses printing::PrintViewManagerBase
+// but the implementations are duplicated from
+// components/printing/browser/print_to_pdf/pdf_print_manager.cc.
+
 PrintViewManagerElectron::PrintViewManagerElectron(
     content::WebContents* web_contents)
     : printing::PrintViewManagerBase(web_contents),