DOCSEARCHbyAlgolia
Submit Docs

TPPDF Documentation

repository·main·Indexed 21 days ago

https://github.com/techprimate/tppdf

A fast PDF builder for iOS and macOS featuring a command-based API. TPPDF supports complex layouts, including multi-column sections, tables with cell merging, images with captions, and advanced pagination. It provides tools for creating structured documents with headers, footers, and dynamic groups while minimizing memory usage by generating files directly.

Tokens
5.1K
Snippets
20
Records
23
Agent score
74%

What's inside TPPDF

  1. Overview of TPPDF features

    main

    TPPDF is a fast PDF builder for iOS and macOS. Key features include:

    • Layout & Structure: Page headers and footers, dynamic content layout with page alignment, multi-column sections, and pagination.
    • Content Types: Support for tables (with cell merging, alignment, and automatic page breaking), attributed strings, images (with support for captions, compression, and custom size fitting), and hyperlinks.
    • Styling: Custom spacing, indentation, top offsets (for layered rendering), and custom table styling.
    • Advanced Capabilities: Horizontal line separators (in content and headers/footers), PDF metadata support, and native progress tracking using Foundation.Progress.
    • Performance: Ability to generate PDF files directly to handle large files and minimize memory climb.

  2. How Containers and Alignment work in TPPDF

    main

    TPPDF is an element-based builder where every piece of content is an element placed within a specific container.

    There are three primary containers:

    1. header
    2. content
    3. footer

    Each container supports three alignments:

    • left
    • center
    • right

    When adding an element, you provide a container/alignment combination (e.g., .contentCenter, .footerLeft). If no container is specified, the default is .contentLeft. During the rendering process, TPPDF calculates the correct frame for the element based on its container and alignment.

    Elements added to the header or footer containers are repeated on every page (unless the page is entirely empty).

    let document = PDFDocument(format: .a4)
// Adds text to the footer of all pages
document.add(.footerCenter, text: "Created using TPPDF for iOS.")

  3. Quickstart: Create a PDF document with TPPDF

    main

    To build a PDF document, follow these three steps: 1. Initialize a PDFDocument with a PDFPageFormat. 2. Add content using the add(_:text:) method, specifying a container and alignment. 3. Use PDFGenerator to render the document to a URL.

    // 1. Create a document with a paper format
let document = PDFDocument(format: .a4)

// 2. Add information to a container
document.add(.contentCenter, text: "Create PDF documents easily.")

// 3. Render the document
let generator = PDFGenerator(document: document)
let url = try generator.generateURL(filename: "Example.pdf")
    let document = PDFDocument(format: .a4)
document.add(.contentCenter, text: "Create PDF documents easily.")
let generator = PDFGenerator(document: document)
let url  = try generator.generateURL(filename: "Example.pdf")

  4. Install TPPDF via CocoaPods

    main

    To integrate TPPDF using CocoaPods, first ensure CocoaPods is installed on your system. Then, add pod 'TPPDF' to your project's Podfile and run the installation command.

    # Install CocoaPods
gem install cocoapods

# After updating Podfile, run:
pod install
    # Podfile example
source 'https://cdn.cocoapods.org/'
platform :ios, '10.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'TPPDF'
end

  5. Install TPPDF via Swift Package Manager

    main

    TPPDF is supported on iOS via Swift Package Manager. Note that macOS support is currently a work-in-progress and Linux support is unavailable because UIKit is required. To add TPPDF, include it in the dependencies array of your Package.swift file.

    // Package.swift example
dependencies: [
    .package(url: "https://github.com/techprimate/TPPDF", .upToNextMajor(from: "2.0.0"))
]

  6. Enable debug overlay for element outlines

    main

    To visualize the layout and boundaries of elements within your document, you can enable a debug overlay. Setting the debug flag to true on a PDFGenerator instance will add colored outlines around the elements in your document during the generation process.

    let document: PDFDocument
let generator = PDFDocumentGenerator(document: document)
generator.debug = true

  7. Install TPPDF via Carthage

    main

    To use Carthage, install it via Homebrew, add the TPPDF repository to your Cartfile, and run the update command. Finally, manually drag the resulting TPPDF.framework into your Xcode project.

    # Install Carthage
brew update
brew install carthage

# Update dependencies
carthage update
    # Cartfile example
github "techprimate/TPPDF" ~> 1.4

  8. Configure Page Layout and Margins

    main

    You can define the page structure using either a predefined PDFPageFormat or a custom PDFPageLayout.

    When using a custom PDFPageLayout, you can configure the following properties (all values are in dots at 72 DPI):

    • size: The width and height of the page.
    • margin: The content inset on each side of the page.
    • space.header: The space between the header and content elements. This is only applied if the header container contains at least one element.
    • space.footer: The space between the footer and content elements. This is only applied if the footer container contains at least one element.
    • landscapeSize: Use this variable if you require the page in landscape format.

    If no header or footer elements are provided, it is recommended to increase the margin values instead of using space.header or space.footer.

    // Using a predefined format
let document = PDFDocument(format: .a4)

// Using a custom layout
let layout = PDFPageLayout()
let document = PDFDocument(layout: layout)

  9. Observe PDF generation progress

    main

    TPPDF uses native Apple Progress handling to track generation status. You can observe the overall progress of a single document generation using the progress property on a PDFDocumentGenerator.

    If you are using PDFMultiDocumentGenerator to render multiple documents at once, you can track the progress of each individual document via the progresses array, which contains a Progress object for each document in the input list.

    // Observing a single document generator
let generator = PDFDocumentGenerator(document: document)
generator.progress.observe(\.fractionCompleted) { (p, _) in
    print(p.localizedDescription ?? "")
}

// Observing individual documents in a multi-document generator
let generator = PDFMultiDocumentGenerator(documents: [document1, document2])
generator.progresses[0].observe(\.fractionCompleted) { (p, _) in
    print(p.localizedDescription ?? "")
}

  10. Check TPPDF version compatibility and requirements

    main

    As of TPPDF 2.0 and Swift 5.2, older Swift versions are no longer actively supported on the main branch. If your project requires an older Swift version, you must use the corresponding legacy branch. The develop branch contains the latest bleeding-edge development version.

    LanguageBranchPod versionXcode versioniOS version
    Swift 4.2swift-4.2>= 1.3.xXcode 10.0+iOS 8.3+
    Swift 4.1swift-4.1>= 1.0.xXcode 9.3iOS 8.3+
    Swift 3.0swift-3.0>= 0.2.xXcode 8iOS 8.0+
    Swift 2.3swift-2.30.1.5Xcode 8, Xcode 7.3.xiOS 8.0+
    Swift 2.2swift-2.20.1.4Xcode 7.3.xiOS 8.0+

  12. Add a Line Separator

    main

    You can add a horizontal line to a specific container using addLineSeparator. The line's width is affected by the current indentation settings of the container. You can adjust the width by setting left and right indentations before adding the separator.

    let style = PDFLineStyle(type: .full, color: .darkGray, width: 0.5)
document.addLineSeparator(PDFContainer.contentLeft, style: style)