Struct PdfFromUrlRequest 

pub struct PdfFromUrlRequest {
    pub url: String,
    pub filename: Option<String>,
    pub waitsecs: Option<u64>,
    pub landscape: Option<bool>,
    pub download: Option<bool>,
    pub print_background: Option<bool>,
}

Request parameters for converting a URL to PDF.

This struct represents the query parameters or request body for the URL-to-PDF endpoint. All fields except url are optional with sensible defaults.

Required Fields

Field	Type	Description
url	String	The URL to convert (must be a valid HTTP/HTTPS URL)

Optional Fields

Field	Type	Default	Description
filename	Option<String>	"document.pdf"	Output filename for Content-Disposition header
waitsecs	Option<u64>	5	Seconds to wait for JavaScript execution
landscape	Option<bool>	false	Use landscape page orientation
download	Option<bool>	false	Force download vs inline display
print_background	Option<bool>	true	Include background colors/images

JavaScript Wait Behavior

The waitsecs parameter controls how long to wait for JavaScript to complete. The service polls for window.isPageDone === true every 200ms. If your page sets this flag, rendering completes immediately; otherwise, it waits the full duration.

// In your web page, signal when rendering is complete:
window.isPageDone = true;

Examples

Basic URL conversion

use html2pdf_api::service::PdfFromUrlRequest;

let request = PdfFromUrlRequest {
    url: "https://example.com".to_string(),
    ..Default::default()
};

assert_eq!(request.filename_or_default(), "document.pdf");
assert_eq!(request.wait_duration().as_secs(), 5);

Landscape PDF with custom filename

use html2pdf_api::service::PdfFromUrlRequest;

let request = PdfFromUrlRequest {
    url: "https://example.com/report".to_string(),
    filename: Some("quarterly-report.pdf".to_string()),
    landscape: Some(true),
    waitsecs: Some(10), // Complex charts need more time
    ..Default::default()
};

assert!(request.is_landscape());
assert_eq!(request.wait_duration().as_secs(), 10);

Force download (vs inline display)

use html2pdf_api::service::PdfFromUrlRequest;

let request = PdfFromUrlRequest {
    url: "https://example.com/invoice".to_string(),
    filename: Some("invoice-2024.pdf".to_string()),
    download: Some(true), // Forces "Content-Disposition: attachment"
    ..Default::default()
};

assert!(request.is_download());

HTTP API Usage

As Query Parameters (GET request)

GET /pdf?url=https://example.com&filename=report.pdf&landscape=true&waitsecs=10

As JSON Body (POST request, if supported)

{
    "url": "https://example.com",
    "filename": "report.pdf",
    "landscape": true,
    "waitsecs": 10,
    "download": false,
    "print_background": true
}

Fields

url: String

The URL to convert to PDF.

Must be a valid HTTP or HTTPS URL. Relative URLs are not supported.

Validation

The URL is validated using the url crate before processing. Invalid URLs result in a PdfServiceError::InvalidUrl error.

Examples

Valid URLs:

• https://example.com
• https://example.com/path?query=value
• http://localhost:3000/report

Invalid URLs:

• example.com (missing scheme)
• /path/to/page (relative URL)
• `` (empty string)

filename: Option<String>

Output filename for the generated PDF.

This value is used in the Content-Disposition header. If not provided, defaults to "document.pdf".

Notes

• The filename should include the .pdf extension
• Special characters are not escaped; ensure valid filename characters
• The browser may modify the filename based on its own rules

waitsecs: Option<u64>

Seconds to wait for JavaScript execution before generating the PDF.

Many modern web pages rely heavily on JavaScript for rendering content. This parameter controls the maximum wait time for the page to become ready.

Behavior

1. After navigation completes, the service waits up to waitsecs seconds
2. Every 200ms, it checks if window.isPageDone === true
3. If the flag is set, PDF generation begins immediately
4. If timeout is reached, PDF generation proceeds anyway

Default

5 seconds - suitable for most pages with moderate JavaScript.

Recommendations

Page Type	Recommended Value
Static HTML	1-2
Light JavaScript	3-5
Heavy SPA (React, Vue)	5-10
Complex charts/graphs	10-15

landscape: Option<bool>

Use landscape page orientation.

When true, the PDF is generated in landscape mode (wider than tall). When false or not specified, portrait mode is used.

Default

false (portrait orientation)

Use Cases

• Wide tables or spreadsheets
• Horizontal charts and graphs
• Timeline visualizations
• Presentation slides

download: Option<bool>

Force download instead of inline display.

Controls the Content-Disposition header behavior:

Value	Header	Browser Behavior
false (default)	inline; filename="..."	Display in browser
true	attachment; filename="..."	Force download dialog

Default

false - PDF displays inline in the browser’s PDF viewer.

Notes

Browser behavior may vary. Some browsers always download PDFs regardless of this setting, depending on user preferences.

print_background: Option<bool>

Include background colors and images in the PDF.

When true, CSS background colors, background images, and other background graphics are included in the PDF output.

Default

true - backgrounds are included by default.

Notes

Setting this to false can reduce file size and is useful for print-friendly output where backgrounds are not desired.

Implementations

impl PdfFromUrlRequest

pub fn filename_or_default(&self) -> String

Returns the filename, using "document.pdf" as the default.

Examples

use html2pdf_api::service::PdfFromUrlRequest;

let request = PdfFromUrlRequest::default();
assert_eq!(request.filename_or_default(), "document.pdf");

let request = PdfFromUrlRequest {
    filename: Some("report.pdf".to_string()),
    ..Default::default()
};
assert_eq!(request.filename_or_default(), "report.pdf");

pub fn wait_duration(&self) -> Duration

Returns the JavaScript wait duration.

Defaults to 5 seconds if not specified.

Examples

use html2pdf_api::service::PdfFromUrlRequest;
use std::time::Duration;

let request = PdfFromUrlRequest::default();
assert_eq!(request.wait_duration(), Duration::from_secs(5));

let request = PdfFromUrlRequest {
    waitsecs: Some(10),
    ..Default::default()
};
assert_eq!(request.wait_duration(), Duration::from_secs(10));

pub fn is_download(&self) -> bool

Returns whether download mode is enabled.

When true, the response includes Content-Disposition: attachment to force a download. When false, uses inline for in-browser display.

Examples

use html2pdf_api::service::PdfFromUrlRequest;

let request = PdfFromUrlRequest::default();
assert!(!request.is_download()); // Default is inline

let request = PdfFromUrlRequest {
    download: Some(true),
    ..Default::default()
};
assert!(request.is_download());

pub fn is_landscape(&self) -> bool

Returns whether landscape orientation is enabled.

Examples

use html2pdf_api::service::PdfFromUrlRequest;

let request = PdfFromUrlRequest::default();
assert!(!request.is_landscape()); // Default is portrait

let request = PdfFromUrlRequest {
    landscape: Some(true),
    ..Default::default()
};
assert!(request.is_landscape());

pub fn print_background(&self) -> bool

Returns whether background printing is enabled.

Examples

use html2pdf_api::service::PdfFromUrlRequest;

let request = PdfFromUrlRequest::default();
assert!(request.print_background()); // Default is true

let request = PdfFromUrlRequest {
    print_background: Some(false),
    ..Default::default()
};
assert!(!request.print_background());

Trait Implementations

impl Clone for PdfFromUrlRequest

fn clone(&self) -> PdfFromUrlRequest

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PdfFromUrlRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PdfFromUrlRequest

fn default() -> PdfFromUrlRequest

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for PdfFromUrlRequest

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for PdfFromUrlRequest

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.