Dash Enterprise PDF Service

This documentation is for Dash Enterprise,
Plotly’s commercial platform for managing and improving
Dash applications in your organization.
View the docs or
request a trial.

The Dash Enterprise platform has an API endpoint for creating PDF exports
of your Dash applications. The API is simple: pass in the URL of your
Dash app and the sizing parameters and get back a PDF print out. You can
automate PDF generation with
<dccLink>
or you can generate these PDFs on-the-fly.

This API endpoint is used by the Dash Enterprise Snapshot Engine library.
Refer to the
Snapshot Engine documentation
for more examples.


API Parameters

POST <a href="https://&lt;your-dash-enterprise&gt;/Manager/api/generate_report">https://&lt;your-dash-enterprise&gt;/Manager/api/generate_report</a>
content-type: application/json
plotly-client-platform: dash
Authorization: Basic ...

{
    "url": "...",
    "appname": os.environ.get('DASH_APP_NAME'),
    "secret_key": os.environ.get('DASH_SECRET_KEY'),
    "pdf_options": {
        "pageSize": "Letter",
        "marginsType": 1
    },
    "wait_selector": "body"
}
  • url - The URL to download
  • appname - Your app’s name.
  • secret_key - Your app’s secret key. This is needed for authorizing the pdf generation.
  • wait_selector - A string that specifies a
    CSS selector.
    The API will wait until an element that matches this CSS selector
    appears on the screen before taking a screenshot. This ensures that
    the page has finished loading before taking a screenshot.
    In general, we recommend:
  • If there are no graphs on the page, then embed an
    html.Div(id='waitfor') in your app.layout or return it from
    the callback that gets executed last. With the id waitfor, the
    wait_selector would be "#waitfor".
  • If the page has dcc.Graph elements on it, then you’ll want
    to wait until these graphs have finished renderering. To do this,
    set the wait_selector to be #graph_id .svg-container where
    "graph_id" corresponds to the ID of the dcc.Graph component.
    .svg-container refers to a CSS class of an element that plotly
    inserts in the graph when it has finished rendering.
  • pdf_options - PDF sizing options. These options are similar to the
    options that you see when you print a web page using your web browser.
    They include:
  • pageSize: Predefined page size of the generated PDF. Available options:
    A3, A4, A5, Legal, Tabloid. Custom page sizes can be
    provided with the top level page_size property (see below).

  • marginsType: Specifies the type of margins to use. 0 for
    default margin, 1 for no margin, and 2 for minimum margin. We
    recommend using 1 and controlling the margins yourself through
    your app’s CSS.

  • landscape (optional): True for landscape, False for portrait.
  • ‘page_size’ (optional): A dict specifying width & height
    in microns, e.g. {‘width’: 296700, ‘height’: 209900}.

Basic Example

This example provides a simple UI around the PDF API. You can run this
example locally or you can deploy this example to Dash Enterprise.
A few things to note:

  • If you’re testing locally, you will have to specify default values for your
    DASH_DOMAIN_BASE, DASH_APP_NAME and DASH_SECRET_KEY. You can find them in the list of your app’s
    environment variables. See our doc on environment variables
    for more details.

import dash
from dash.dependencies import Input, Output, State
import dash_core_components as dcc
import dash_html_components as html

import base64
import os
import requests

app = dash.Dash(__name__)
server = app.server


app.layout = html.Div([
    html.Label('Website URL'),
    dcc.Input(
        id='website',
        value='https://dash.plotly.com'
    ),

    html.Div(html.B('CSS Selector')),
    html.Div(
        'Wait until an element targeted by this selector appears '
        'before taking a snapshot. These are standard CSS query selectors'.
    ),
    dcc.Input(
        id='wait_selector',
        value='#wait-for-layout'
    ),

    html.Button(id='run', children='Snapshot', n_clicks=0),

    html.Div(id='output'),

])


@app.callback(Output('output', 'children'),
              [Input('run', 'n_clicks')],
              [State('website', 'value'),
               State('wait_selector', 'value')])
def snapshot_page(n_clicks, url, wait_selector):
    if n_clicks == 0:
        return ''
    payload = {
        'url': url,
        "appname": os.environ.get('DASH_APP_NAME', 'your-dash-app-name'),
        "secret_key": os.environ.get('DASH_SECRET_KEY', 'your-dash-app-secret-key'),
        'pdf_options': {
            'pageSize': 'Letter',
            'marginsType': 1
        },
        'wait_selector': wait_selector
    }

    res = requests.post(
        'https://{}/Manager/api/generate_report'.format(
            os.environ.get('DASH_DOMAIN_BASE', 'your-dash-domain-base')
        ),
        json=payload
    )
    if res.status_code == 200:
        return html.A(
            'Download',
            href='data:application/pdf;base64,{}'.format(
                base64.b64encode(res.content).decode('utf-8')
            ),
            download='dash.pdf',
            target='_blank'
        )

    return html.Pre('Status: {}, Response: {}'.format(
        res.status_code, res.content
    ))


if __name__ == '__main__':
    app.run_server(debug=True)

Custom Reporting Solutions

Plotly helps companies modernize their reporting infrastructure with
Dash. In particular, we help organizations with:
- Our modules for saving and loading reports in Dash Enterprise
- Converting existing PDF reports into Dash application code
- Creating high-quality, branded PDF templates

Get in touch with your sales rep or
reach out to us directly
to learn more.