[float]
=== PDF and PNG

[float]
==== Job parameters
A configuration for a PDF or PNG report job is represented with an interface that includes the `BaseParams` and the following
fields. To create a request for one of these report types, these required job parameters are encoded into a query string variable
of the report generation URL:

----
interface BaseParamsPDFV2 {
  layout: {
    id: string; <1>
    dimensions: {
      height: number;
      width: number;
    };
  };
  locatorParams: LocatorParams[]; <2>
}

interface BaseParamsPNGV2 {
  layout: {
    id: string; <3>
    dimensions: {
      height: number;
      width: number;
    };
  };
  locatorParams: LocatorParams; <4>
}
----
<1> The available `layout.id` options for PDF exports are `preserve_layout`, `print`, and `canvas`. These control how dashboard
panels are captured and positioned into pages in the PDF file. 
<2> The `locatorParams` value is controlled by the application loaded in the browser for which a screenshot will be captured. The
parameters to generate a PDF report allow an array of `locatorParams` to support multi-page PDF reports.
<3> The only available `layout.id` option for PNG exports is `preserve_layout`.
<4> The parameters to generate a PNG report allow a single value for `locatorParams`.

[float]
==== How applications make themselves screenshot-capable
When generating the PDF, the headless browser launched by the Reporting export type runs a script that looks for a number of
attributes in the DOM to determine which elements should have their screenshot taken and when the Visualizations are done
rendering.

The print layout takes a screenshot of every element with the `data-shared-item` attribute and includes the
individual screenshots in the PDF. The print layout also uses the `data-title` and `data-description`
attributes on the same HTMLElement as the `data-shared-item` to specify the title and description.

The preserve layout takes a screenshot of the element with the `data-shared-items-container` attribute. Additionally,
reporting will resize the element with the `data-shared-items-container` to be the size specified in the layout dimensions.
The preserve layout also uses the `data-title` and `data-description` attributes on the HTMLElement with the
`data-shared-items-container` attribute to specify the title/description for the entire PDF.

Reporting needs to determine when all of the visualizations have completed rendering, so that it can begin taking screenshots. If
there are multiple visualizations, the `data-shared-items-count` attribute should be specified to let Reporting know how many
Visualizations to look for. Reporting will look at every element with the `data-shared-item` attribute and use the corresponding
`data-render-complete` attribute and `renderComplete` events to listen for rendering to complete. When rendering is complete for a
visualization the `data-render-complete` attribute should be set to "true" and it should dispatch a custom DOM `renderComplete`
event.

If the reporting job uses multiple URLs, before looking for any of the `data-shared-item` or `data-shared-items-count` attributes,
it waits for a `data-shared-page` attribute that specifies which page is being loaded.