Added algorithm for pagination to PDF export, allowing to export consent forms with more than 1 page (#49)

Sources/SpeziOnboarding/ConsentView/ConsentDocument+Export.swift

@@ -49,14 +49,14 @@ extension ConsentDocument {
     ///
     /// - Returns: The exported consent form in PDF format as a PDFKit `PDFDocument`
     @MainActor
-    func export() async -> PDFKit.PDFDocument? {
+    func export() async throws -> PDFKit.PDFDocument {
         documentExport.signature = signature
         documentExport.name = name
         #if !os(macOS)
         documentExport.signatureImage = blackInkSignatureImage
-        return await documentExport.export()
+        return try await documentExport.export()
         #else
-        return await documentExport.export()
+        return try await documentExport.export()
         #endif
     }
 }

Sources/SpeziOnboarding/ConsentView/ConsentDocument.swift

@@ -154,7 +154,7 @@ public struct ConsentDocument: View {
             .onChange(of: viewState) {
                 if case .export = viewState {
                     Task {
-                        guard let exportedConsent = await export() else {
+                        guard let exportedConsent = try? await export() else {
                             viewState = .base(.error(Error.memoryAllocationError))
                             return
                         }

Sources/SpeziOnboarding/ConsentView/ConsentDocumentExport+Export.swift

@@ -158,7 +158,7 @@
         pdfTextContent: PDFAttributedText,
         signatureFooter: PDFGroup,
         exportTimeStamp: PDFAttributedText? = nil
-    ) async -> PDFKit.PDFDocument? {
+    ) async throws -> PDFKit.PDFDocument {
         let document = TPPDF.PDFDocument(format: exportConfiguration.getPDFPageFormat())
 
         if let exportStamp = exportTimeStamp {
@@ -172,15 +172,13 @@
         // Convert TPPDF.PDFDocument to PDFKit.PDFDocument
         let generator = PDFGenerator(document: document)
 
-        if let data = try? generator.generateData() {
-            if let pdfKitDocument = PDFKit.PDFDocument(data: data) {
-                return pdfKitDocument
-            } else {
-                return nil
-            }
-        } else {
-            return nil
+        let data = try generator.generateData()
+
+        guard let pdfDocument = PDFKit.PDFDocument(data: data) else {
+            throw ConsentDocumentExportError.invalidPdfData("PDF data not compatible with PDFDocument")
         }
+
+        return pdfDocument
     }
 
     #if !os(macOS)
@@ -193,13 +191,13 @@
     ///     - signatureImage: Signature drawn when signing the document.
     /// - Returns: The exported consent form in PDF format as a PDFKit `PDFDocument`
     @MainActor
-    public func export() async -> PDFKit.PDFDocument? {
+    public func export() async throws -> PDFKit.PDFDocument{
         let exportTimeStamp = exportConfiguration.includingTimestamp ? exportTimeStamp() : nil
         let header = exportHeader()
         let pdfTextContent = await exportDocumentContent()
         let signature = exportSignature()
 
-        return await createDocument(
+        return try await createDocument(
             header: header,
             pdfTextContent: pdfTextContent,
             signatureFooter: signature,
@@ -215,13 +213,13 @@
     ///     - personName: A string containing the name of the person who signed the document.
     /// - Returns: The exported consent form in PDF format as a PDFKit `PDFDocument`
     @MainActor
-    public func export() async -> PDFKit.PDFDocument? {
+    public func export() async throws -> PDFKit.PDFDocument {
         let exportTimeStamp = exportConfiguration.includingTimestamp ? exportTimeStamp() : nil
         let header = exportHeader()
         let pdfTextContent = await exportDocumentContent()
         let signature = exportSignature()
 
-        return await createDocument(
+        return try await createDocument(
             header: header,
             pdfTextContent: pdfTextContent,
             signatureFooter: signature,

Sources/SpeziOnboarding/ConsentView/ConsentDocumentExport.swift

@@ -6,7 +6,7 @@
 // SPDX-License-Identifier: MIT
 //
 
 @preconcurrency import PDFKit
 import PencilKit
 import SwiftUI
 
@@ -20,8 +20,8 @@
         public static let documentIdentifier = "ConsentDocument"
     }
 
     let asyncMarkdown: () async -> Data
     let exportConfiguration: ConsentDocument.ExportConfiguration
     var cachedPDF: PDFDocument?
 
     /// An unique identifier for the exported `ConsentDocument`.
@@ -45,14 +45,14 @@
     /// if the `ConsentDocument` has not been previously exported or the `PDFDocument` was not cached.
     /// For now, we always require a PDF to be cached to create a ConsentDocumentExport. In the future, we might change this to lazy-PDF loading.
     @MainActor public var pdf: PDFDocument {
-        get async {
-            if let cached = cachedPDF {
-                return cached
-            } else {
-                cachedPDF = await export()
-                // If the export failed, return an empty document.
-                return cachedPDF ?? .init()
+        get async throws {
+            if let pdf = cachedPDF {
+                return pdf
             }
+
+            let pdf = try await export()
+            cachedPDF = pdf
+            return pdf
         }
     }
 

Sources/SpeziOnboarding/ConsentView/ConsentDocumentExportError.swift

@@ -0,0 +1,27 @@
+//
+// This source file is part of the Stanford Spezi open-source project
+//
+// SPDX-FileCopyrightText: 2024 Stanford University and the project authors (see CONTRIBUTORS.md)
+//
+// SPDX-License-Identifier: MIT
+//
+
+import Foundation
+
+// Error that can occur if PDF export fails in ``ConsentDocumentExport``.
+enum ConsentDocumentExportError: LocalizedError {
+    case invalidPdfData(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidPdfData:
+            String(
+                localized: "Unable to generate valid PDF document from PDF data.",
+                comment: """
+                Error thrown if we generated a PDF document using TPPDF,
+                but were unable to convert the generated data into a PDFDocument.
+                """
+            )
+        }
+    }
+}

Sources/SpeziOnboarding/OnboardingDataSource.swift

@@ -41,7 +41,7 @@
 
 
     public func configure() {
         guard standard is any OnboardingConstraint || standard is any ConsentConstraint else {
             fatalError("A \(type(of: standard).self) must conform to `ConsentConstraint` to process signed consent documents.")
         }
     }
@@ -82,9 +82,9 @@
     public func store(_ consent: ConsentDocumentExport) async throws {
         if let consentConstraint = standard as? any ConsentConstraint {
             try await consentConstraint.store(consent: consent)
         } else if let onboardingConstraint = standard as? any OnboardingConstraint {
-            let pdf = await consent.pdf
+            let pdf = try await consent.pdf
             await onboardingConstraint.store(consent: pdf)
         } else {
             fatalError("A \(type(of: standard).self) must conform to `ConsentConstraint` to process signed consent documents.")
         }

Sources/SpeziOnboarding/Resources/Localizable.xcstrings

@@ -304,6 +304,9 @@
           }
         }
       }
+    },
+    "Unable to generate valid PDF document from PDF data." : {
+      "comment" : "Error thrown if we generated a PDF document using TPPDF,\nbut were unable to convert the generated data into a PDFDocument."
     }
   },
   "version" : "1.0"

Tests/SpeziOnboardingTests/.gitattributes

@@ -1 +1,8 @@
+#
+# This source file is part of the Stanford Spezi open-source project
+#
+# SPDX-FileCopyrightText: 2023 Stanford University and the project authors (see CONTRIBUTORS.md)
+#
+# SPDX-License-Identifier: MIT
+# 
 Resources/*.pdf filter=lfs diff=lfs merge=lfs -text

Tests/SpeziOnboardingTests/SpeziOnboardingTests.swift

@@ -79,8 +79,8 @@
             documentExport.signature = "Stanford"
             #endif
 
-            if let pdf = await documentExport.export() {
+            if let pdf = try? await documentExport.export() {
                 XCTAssert(comparePDFDocuments(pdf1: pdf, pdf2: knownGoodPdf))
             } else {
                 XCTFail("Failed to export PDF from ConsentDocumentExport.")
             }

Tests/UITests/TestApp/ExampleStandard.swift

@@ -24,7 +24,7 @@ extension ExampleStandard: ConsentConstraint {
     func store(consent: ConsentDocumentExport) async throws {
         // Extract data outside of the MainActor.run block
         let documentIdentifier = await consent.documentIdentifier
-        let pdf = await consent.pdf
+        let pdf = try await consent.pdf
 
         // Perform operations on the main actor
         try await MainActor.run {