JXPhotoBrowser Documentation

JXPhotoBrowser is designed as a lightweight browser kernel that decouples data management from UI rendering. It uses a protocol-driven approach to allow the host application to provide data, media loading, and custom UI elements.

Core Responsibilities of the Kernel:

1. Pagination & Reuse: Uses UICollectionView to manage paging and cell reuse.
2. Scaling & Centering: Uses UIScrollView to manage single-page zooming and centering.
3. Transitions: Uses independent animators to manage presentation and dismissal.
4. Abstraction: Uses protocols to delegate Cell implementation, Overlays, thumbnail sources, and media content to the business layer.

Key Architectural Layers:

• Host/Business Layer: Provides data and implements the JXPhotoBrowserDelegate.
• JXPhotoBrowserViewController: The central controller managing the UICollectionView, transition animators, and the Overlay plugin system.
• Cell Layer: Implements JXPhotoBrowserCellProtocol (e.g., JXZoomImageCell, JXImageCell, or custom video cells).

To use the photo browser, instantiate JXPhotoBrowserViewController, configure its properties, and implement the JXPhotoBrowserDelegate to provide data and cells. The library does not include a built-in image loading library; you must set the image in the cell using your preferred library (e.g., Kingfisher, SDWebImage).

import JXPhotoBrowser

let browser = JXPhotoBrowserViewController()
browser.delegate = self
browser.initialIndex = indexPath.item
browser.transitionType = .zoom
browser.isLoopingEnabled = true
browser.addOverlay(JXPageIndicatorOverlay())
browser.present(from: self)

extension ViewController: JXPhotoBrowserDelegate {
    func numberOfItems(in browser: JXPhotoBrowserViewController) -> Int {
        items.count
    }

    func photoBrowser(
        _ browser: JXPhotoBrowserViewController,
        cellForItemAt index: Int,
        at indexPath: IndexPath
    ) -> JXPhotoBrowserAnyCell {
        browser.dequeueReusableCell(
            withReuseIdentifier: JXZoomImageCell.reuseIdentifier,
            for: indexPath
        )
    }

    func photoBrowser(
        _ browser: JXPhotoBrowserViewController,
        willDisplay cell: JXPhotoBrowserAnyCell,
        at index: Int
    ) {
        guard let cell = cell as? JXZoomImageCell else { return }
        // Use your preferred image loading library to set cell.imageView.image
    }

    func photoBrowser(
        _ browser: JXPhotoBrowserViewController,
        thumbnailViewAt index: Int
    ) -> UIView? {
        let indexPath = IndexPath(item: index, section: 0)
        return collectionView.cellForItem(at: indexPath)?.contentView
    }
}

To reuse all zoom and gesture behaviors, inherit from JXZoomImageCell. If you implement the protocol directly on a UICollectionViewCell, you must ensure the browser property is a weak reference to avoid retain cycles.

All cells use the full page size of the browser. You must register your custom cell and dequeue it within the delegate methods.

// 1. Define the custom cell
final class MediaCell: UICollectionViewCell, JXPhotoBrowserCellProtocol {
    static let reuseIdentifier = "MediaCell"
    weak var browser: JXPhotoBrowserViewController?
    let imageView = UIImageView()
    var transitionImageView: UIImageView? { imageView }

    override init(frame: CGRect) {
        super.init(frame: frame)
        contentView.addSubview(imageView)
    }

    required init?(coder: NSCoder) {
        super.init(coder: coder)
        contentView.addSubview(imageView)
    }
}

// 2. Register the cell with the browser
browser.register(MediaCell.self, forReuseIdentifier: MediaCell.reuseIdentifier)

To use the browser as an embedded banner (e.g., inside a scroll view), you must use standard View Controller containment and disable the pull-to-dismiss gesture.

Configuration for Banner Mode:

• Set transitionType to .none.
• Set isDismissGestureEnabled to false.
• Enable isAutoPlayEnabled and set autoPlayInterval if desired.

Lifecycle Management:

• To Add: Use addChild(browser), add browser.view to your container, set constraints, and call browser.didMove(toParent: self).
• To Remove: Call willMove(toParent: nil), remove the view, and then call removeFromParent().

let browser = JXPhotoBrowserViewController()
browser.delegate = self
browser.transitionType = .none
browser.isDismissGestureEnabled = false
browser.autoPlayInterval = 3
browser.isAutoPlayEnabled = true

addChild(browser)
containerView.addSubview(browser.view)
// Add constraints to browser.view
browser.didMove(toParent: self)