Migrate HTML to PDF Page Setup and Headers from HiQPdf Classic

HiQPdf Next keeps the names of the HiQPdf Classic converter where the meaning is the same: the HtmlToPdf class, the BrowserWidth, BrowserHeight, BrowserZoom and MediaType properties, the Document property with the page size, orientation and margins, and the ConvertUrlToMemory and ConvertHtmlToMemory methods. Code that only sets these options compiles and runs with small changes. The two areas that work differently are the way the content is fitted on the page and the headers and footers, described in this topic.

The page layouts of Next are described in HTML to PDF Page Setup and Scaling.

Page Setup Options: Classic to Next

In Classic the content was fitted on the page by flags of the Document property. In Next a layout method sets the page, the width at which the HTML is laid out and the scale together, and computes the scale when the PDF is generated. The table maps the Classic settings to Next:

HiQPdf Classic

HiQPdf Next

Notes

BrowserWidth, 1200 by default

BrowserWidth, 1024 by default, or the window width argument of FitBrowserWindowToPage

The width of the browser window in which the HTML is laid out

BrowserHeight, the whole document by default; MinBrowserHeight, StartBrowserHeight

BrowserHeight, 2048 by default

Next always renders the whole content; the window height matters only for content loaded on scroll and for single page layouts

MaxBrowserHeight

MaxBrowserHeight

Same meaning

BrowserZoom, 100 by default

BrowserZoom

Computed by the layout methods; set it only to override them

MediaType

MediaType

Same meaning; PrintLikeChrome selects print

Document.PageSize, PageOrientation, Margins

Document.PageSize, PageOrientation, Margins

Same names and units; the layout methods take the page size and the orientation as arguments

Document.FitPageWidth = true (the default)

FitBrowserWindowToPage(pageSize, orientation, 1200)

The window is scaled to the page width. Next also enlarges a window narrower than the page

Document.ForceFitPageWidth = true

FitBrowserWindowToPage

Next enlarges a narrower window to the page width without another setting

FitPageWidth = false with ResizePageWidth = true (the default)

PageWidthFromBrowserWindow(width)

The page is as wide as the content, drawn 1:1

Document.PostCardMode = true

PageWidthFromBrowserWindow(width, singlePage: true)

One page as wide and as tall as the content, drawn 1:1

Document.FitPageHeight = true

No direct equivalent

Next makes the page as tall as the content with Document.AutoResizePdfPageHeight instead of scaling the content down

TrimToBrowserWidth

No direct equivalent

Content wider than the browser window is laid out at its own width and scaled to the page (AutoResizeBrowserWidth, true by default)

Document.Header.Enabled, Height

Document.PdfHtmlHeader.Html or HtmlSourceUrl, Height

The header exists when it has HTML; the same for the footer

Header.Layout(new PdfHtmlWithPlaceHolders(...)) with {CrtPage} and {PageCount}

PdfHtmlHeader.Html with {page_number} and {total_pages}

Page numbers are variables in the header HTML

PageCreatingEvent to hide the header on a page

PdfHtmlHeader.ShowInFirstPage, ShowInOddPages, ShowInEvenPages

Visibility is set with properties

Why the Text Can Be Small

By default Classic rendered the page in a 1200 pixel browser window and scaled the result down to the page width. On A4 without margins that is a scale of 66.11 percent, so a 16 px font became 7.9 points. Next does the same with a 1024 pixel window by default, a scale of 77.47 percent, so the same font becomes 9.3 points. In both the text is small for the same reason: a desktop layout is wider than a sheet of paper, and keeping it means scaling it.

  • For the Classic output, pass 1200 as the window width: FitBrowserWindowToPage(PdfPageSize.A4, PdfPageOrientation.Portrait, 1200).

  • For the text at the size given in the CSS, call LayoutAtPageWidth(PdfPageSize, PdfPageOrientation, Boolean, String, Double, Boolean): the page is laid out at the width of the paper and drawn 1:1. A responsive page then shows the layout it has at the width of the paper.

  • For a page with a fixed width, give the window that width, for example 1600 pixels for a 1600 pixel page. The window is then scaled to the page as a whole.

Page Setup Code: Classic and Next Side by Side

The Classic default, a 1200 pixel window scaled to an A4 page:

C#
// Classic
HtmlToPdf converter = new HtmlToPdf();
byte[] pdf = converter.ConvertUrlToMemory(url);

// Next: the same output
HtmlToPdf converter = new HtmlToPdf();
converter.FitBrowserWindowToPage(PdfPageSize.A4, PdfPageOrientation.Portrait, 1200);
byte[] pdf = converter.ConvertUrlToMemory(url);

A page as wide as the content, drawn 1:1:

C#
// Classic
converter.Document.FitPageWidth = false;
converter.Document.ResizePageWidth = true;

// Next
converter.PageWidthFromBrowserWindow(1200);

The whole content on one page:

C#
// Classic
converter.Document.PostCardMode = true;

// Next
converter.PageWidthFromBrowserWindow(1200, singlePage: true);
converter.BrowserHeight = 1;

With singlePage the page is as tall as the content.

Headers and Footers

In Classic a header was enabled with Document.Header.Enabled, given a height in points and filled with objects laid out in it, usually a PdfHtml or, for page numbers, a PdfHtmlWithPlaceHolders with the {CrtPage} and {PageCount} placeholders. In Next the header is an HTML document set on PdfHtmlHeader, and the page numbers are the {page_number} and {total_pages} variables in that HTML. The footer works the same way with PdfHtmlFooter. The top and bottom margins of the page are adjusted to the header and footer heights automatically.

C#
// Classic
converter.Document.Header.Enabled = true;
converter.Document.Header.Height = 50;
converter.Document.Header.Layout(new PdfHtmlWithPlaceHolders(0, 0,
    "<b>Report</b> Page {CrtPage} of {PageCount}", null));

// Next
converter.Document.PdfHtmlHeader.Html = "<b>Report</b> Page {page_number} of {total_pages}";
converter.Document.PdfHtmlHeader.Height = 50;

A header hidden on the first page, which in Classic needed the PageCreatingEvent, is set in Next with PdfHtmlHeader.ShowInFirstPage = false; ShowInOddPages and ShowInEvenPages control the other pages. The headers and footers of Next are described in Add HTML in Header and Footer with Page Numbers.

Migration Checklist

  • Replace the Classic package references with the HiQPdf Next package for your platform and the HiQPdf namespace with HiQPdf.Next.

  • Replace the FitPageWidth, ForceFitPageWidth, ResizePageWidth and PostCardMode settings with the layout method from the table.

  • Pass 1200 as the window width where the Classic output must be kept.

  • Move the header and footer content to PdfHtmlHeader and PdfHtmlFooter and replace the page number placeholders.

  • Remove TrimToBrowserWidth, MinBrowserHeight and StartBrowserHeight; give wide content a wider window.

See Also