Adding a Gallery to Your Document

PSPDFKit has great support for adding interactive content to the PDF. We support local/remote images, video, audio and even YouTube. Content can come from different sources and can be configured both locally and remote via a PDF annotation or a JSON.

While galleries can be added programmatically, the simplest approach is via a link annotation. A link annotation already defines a bounding box for the position, which the gallery will use.

Gallery annotations can be both created and saved in the file, or in code. Here's an example how to create this in code:

Copy
1
2
3
4
5
6
7
// Dynamically add gallery annotation.
let galleryAnnotation = PSPDFLinkAnnotation(url: URL(string: "pspdfkit://localhost/Bundle/sample.gallery")!)
guard let pageRect = document.pageInfoForPage(at: 0)?.rotatedRect else { return true }
let center = CGPoint(x: pageRect.midX, y: pageRect.midY)
let size = CGSize(width: 400, height: 300)
galleryAnnotation.boundingBox = CGRect(x: center.x - size.width / 2, y: center.y - size.height / 2, width: size.width, height: size.height)
document.add([galleryAnnotation], options: nil)
Copy
1
2
3
4
5
6
7
// Dynamically add gallery annotation.
PSPDFLinkAnnotation *galleryAnnotation = [[PSPDFLinkAnnotation alloc] initWithURL:[NSURL URLWithString:@"pspdfkit://localhost/Bundle/sample.gallery"]];
CGRect pageRect = [document pageInfoForPageAtIndex:0].rotatedPageRect;
CGPoint center = CGPointMake(CGRectGetMidX(pageRect), CGRectGetMidY(pageRect));
CGSize size = CGSizeMake(400, 300);
galleryAnnotation.boundingBox = CGRectMake(center.x - size.width / 2.0f, center.y - size.height / 2.0f, size.width, size.height);
[document addAnnotations:@[galleryAnnotation] options:nil];

The target is a .gallery JSON file which defines the contents and title of each image. It's definition is very simple and looks like this:

Copy
1
2
3
4
5
6
7
8
9
10
[
    {
        "contentURL":"http://www.link-to-image1.com/image1.jpg",
        "caption":"This is a small image."
    },
    {
        "contentURL":"http://localhost/Bundle/gallery-local-image.jpg",
        "caption":"This is a local image. Captions are optional"
    }
]

contentURL can point to a local or remote source, and you can use common tokens like 'Documents' or 'Bundle' which will be resolved if local. Image sources can be jpg, png or gif. The image caption is optional.

You can also define the JSON in the PDF, via using the contents property of the annotation. (The notes field). Since Adobe Acrobat doesn't allow setting or changing the contents field, we've added a second way to configure the gallery via adding the content as a JavaScript action:

Run a JavaScript

The image gallery uses a smart download manager and will cache results (we don't rely on NSURLCache since not all servers are properly configured to send the correct ETag for images). If your images change dynamically, you need to update the URL to the json and use a new image URL. (Adding a timestamp at the end like ?1381917561 is a good way to force cache reloads.)

The gallery also supports videos, YouTube and certain options:

1
2
3
4
5
6
    "caption":"A local audio file",
    "options": {
        "loop":true,
        "autoplay":true,
        "controls":false
    }

Video Item Options

Video items support a wide range of options to control the way the gallery handles them.

Name Type Default Description
loop boolean NO Indicates if the video should loop indefinitely.
autoplay boolean NO Indicates if the video should start playing automatically once it becomes visible.
controls boolean YES Indicates if the playback controls should be visible.
coverMode string preview Defines the cover mode. Possible values are preview, image, clear, and none. A description of these values can be found below.
coverImage string nil Defines the image that should be displayed if coverMode is set to image.
coverPreviewCaptureTime number nil Defines the time in the video that should be used to capture a preview if coverMode is set to preview.
start number nil Defines the start time of the video in seconds. If this property is not set, a start time at the beginning of the video is assumed.
end number nil Defines the end time of the video in seconds. If this property is not set, an end time at the end of the video is assumed.
preferredVideoQualities string ["720p", "360p", "240p"] The preferred video qualities of a video. If a video supports multiple qualities (e.g. a YouTube video), the qualities will be preferred in the given order.

coverMode

The following values are valid cover modes.

Value Description
preview A cover will be visible and the cover will be generated from the video.
image A cover will be visible and the given coverImage will be presented.
clear A cover will be visible but the background is transparent.
none No cover will be visible.

Note: To get a clear cover, you also need to set the backgroundColor of the PSPDFGalleryEmbeddedBackgroundView to UIColor.clearColor. This can be easily done with UIAppearance.

Play button customization

You can change the play button image like this:

1
2
let image = UIImage(named: "someImage.png")
PSPDFMediaPlayerCoverView.appearance().playButtonImage = image
1
2
UIImage *image = [UIImage imageNamed:@"someImage.png"];
[[PSPDFMediaPlayerCoverView appearance] setPlayButtonImage:image];

If you just want to change the color of the play button:

1
PSPDFMediaPlayerCoverView.appearance().playButtonColor = .red
1
[[PSPDFMediaPlayerCoverView appearance] playButtonColor:UIColor.redColor];

Activate-able Content

inline-gallery

By default, the special link annotations mentioned above will show content inline within the annotation's bounding box. This behavior can be changed as well:

  • modal (PSPDFActionOptionModal) Will show the content in a new controller, modally, when tapped.

modal

  • popover (PSPDFActionOptionPopover) Content can also be displayed in a popover. This value is ignored on the iPhone.

popover

  • size (PSPDFActionOptionSize) If this is defined, the modal controller will be presented as a sheet hovering the parent controller. This property also controls the popover target size if set. This will be ignored on iPhone. The minimum size for the sheet is 200x200, a value of 550x550 is recommended for modal sheets.

  • button (PSPDFActionOptionButton) Set this to @YES or to a local/remote destination to show a button instead of directly showing the inline content. This can be used to create multimedia buttons that will show a gallery/web content on tap. This can be combined with modal/popover to create these actions on button tap. For local button URLs, use pspdfkit://localhost/Bundle/image.png or similar.