ORKConsentDocument Class Reference

Inherits from	NSObject
Conforms to	NSCopying NSSecureCoding
Declared in	ORKConsentDocument.h

The ORKConsentDocument class represents the content of an informed consent document, which is a document that’s used to obtain informed consent from participants in a medical or other research study. The ResearchKit framework uses an ORKConsentDocument object to provide content for visual consent steps (ORKVisualConsentStep) and for consent review steps (ORKConsentReviewStep).

The sections of an ORKConsentDocument object are instances of ORKConsentSection. When an ORKConsentDocument object is attached to an visual consent step, these sections provide the content for the visual consent screens, and for the Learn More pages that are accessible from them. When attached to an consent review step, the sections can provide the content for the consent document to be reviewed.

If the consent document is simple, each section may be able to map to a visual consent screen. And in some cases, the formatting of the consent document may be sufficiently simple that it can be presented using only section headers and simple formatting. If your consent document uses simple formatting, you might be able to generate a document to sign by specifying the sections and the signatures. In a case like this, you don’t need to provide a value for the htmlReviewContent property, and when the consent review step is completed, the signatures can be placed into a copy of the document and a PDF can be generated.

In more complex cases, the visual consent sections may bear little relation to the formal consent document. In a situation like this, place the formal consent document content in the htmlReviewContent property. Doing this overrides all content that would otherwise be generated from the consent sections.

The document should be in the user’s language, and all the content of the document should be appropriately localized.

Properties

`title`

The document’s title in a localized string.

@property (nonatomic, copy, nullable) NSString *title

Discussion

The title appears only in the generated PDF for review; it is not used in the visual consent process.

Declared In

ORKConsentDocument.h

Visual consent sections

`sections`

The sections to be in printed in the PDF file and or presented in the visual consent sequence.

@property (nonatomic, copy, nullable) NSArray<ORKConsentSection*> *sections

Discussion

All sections appear in the animated process, except for those sections of the type ORKConsentSectionTypeOnlyInDocument.

If the htmlReviewContent property is not set, this content is also used to populate the document for review in the consent review step.

The PDF file contains all sections.

Declared In

ORKConsentDocument.h

Signatures for consent review

`signaturePageTitle`

The title to be rendered on the signature page of the generated PDF in a localized string.

@property (nonatomic, copy, nullable) NSString *signaturePageTitle

Discussion

The title is ignored for visual consent. The title is also ignored if you supply a value for the htmlReviewContent property.

Declared In

ORKConsentDocument.h

`signaturePageContent`

The content to be rendered below the title on the signature page of the generated PDF in a localized string.

@property (nonatomic, copy, nullable) NSString *signaturePageContent

Discussion

The content is ignored for visual consent. The content is also ignored if you supply a value for the htmlReviewContent property.

Declared In

ORKConsentDocument.h

`signatures`

The set of signatures that are required or prepopulated in the document.

@property (nonatomic, copy, nullable) NSArray<ORKConsentSignature*> *signatures

Discussion

To add a signature to the document after consent review, the signatures array needs to be modified to incorporate the new signature content prior to PDF generation. For more information, see [ORKConsentSignatureResult applyToDocument:].

Declared In

ORKConsentDocument.h

`– addSignature:`

Adds a signature to the array of signatures.

- (void)addSignature:(ORKConsentSignature *)signature

Parameters

`signature`	The signature object to add to the document.

Declared In

ORKConsentDocument.h

Alternative content provision

`htmlReviewContent`

Override HTML content for review.

@property (nonatomic, copy, nullable) NSString *htmlReviewContent

Discussion

Typically, the review content is generated from the values of the sections and signatures properties.

When this property is set, the review content is reproduced exactly as provided in the property in the consent review step, and the sections and signatures properties are ignored.

Declared In

ORKConsentDocument.h

PDF generation

`– makePDFWithCompletionHandler:`

Writes the document’s content into a PDF file.

- (void)makePDFWithCompletionHandler:(void ( ^ ) ( NSData *_Nullable PDFData , NSError *_Nullable error ))handler

Parameters

`handler`	The handler block for generated PDF data. When successful, the returned data represents a complete PDF document that represents the consent.

Discussion

The PDF is generated in a form suitable for printing. This is done asynchronously, so the PDF data is returned through a completion block.

Declared In

ORKConsentDocument.h

`– makeCustomPDFWithRenderer:completionHandler:`

Writes the document’s content into a PDF file using the specified renderer.

- (void)makeCustomPDFWithRenderer:(ORKHTMLPDFPageRenderer *)renderer completionHandler:(void ( ^ ) ( NSData *_Nullable PDFData , NSError *_Nullable error ))handler

Parameters

`handler`	The handler block for generated PDF data. When successful, the returned data represents a complete PDF document that represents the consent.
`render`	The PDF renderer.

Discussion

The PDF is generated in a form suitable for printing. This is done asynchronously, so the PDF data is returned through a completion block.

Declared In

ORKConsentDocument.h

Extension Methods

`– initWithHTMLPDFWriter:consentSectionFormatter:consentSignatureFormatter:`

Initializer with ORKHTMLPDFWriter parameter. Allows for injecting mock dependency for the purposes of isolated unit testing.

- (instancetype)initWithHTMLPDFWriter:(ORKHTMLPDFWriter *)writer consentSectionFormatter:(ORKConsentSectionFormatter *)sectionFormatter consentSignatureFormatter:(ORKConsentSignatureFormatter *)signatureFormatter

Parameters

`writer`	The instance of the ORKHTMLPDFWriter upon which the class depends.
`sectionFormatter`	An instance of ORKConsentSectionFormatter
`signatureFormatter`	An instance of ORKConsentSignatureFormatter

Declared In

ORKConsentDocument_Private.h