Pageboy: A Swift repository from haarismuneer

TL;DR UIPageViewController done properly.

Pageboy is a simple, highly informative page view controller.

Features

Simplified data source management.
Enhanced delegation; featuring exact relative positional data and reliable updates.
Infinite scrolling support.
Automatic timer-based page transitioning.
Support for custom page transitions.

Requirements

Pageboy requires iOS 8.0 / tvOS 10.0 and Swift 4.0 or above.

For Swift 3.x support, please use the latest 1.x release (For 1.x legacy API docs, see here).

Installation

CocoaPods

Pageboy is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'Pageboy', '~> 2.0'

And run pod install.

Carthage

Pageboy is available through Carthage. Simply install carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

Add Pageboy to your Cartfile:

github "uias/Pageboy" ~> 2.0

Usage

Getting Started

Create an instance of a PageboyViewController and provide it with a PageboyViewControllerDataSource.

class PageViewController: PageboyViewController, PageboyViewControllerDataSource {

	override func viewDidLoad() {
		super.viewDidLoad()

		self.dataSource = self
	}
}

Implement the PageboyViewControllerDataSource functions.

func numberOfViewControllers(in pageboyViewController: PageboyViewController) -> Int {
    return viewControllers.count
}
    
func viewController(for pageboyViewController: PageboyViewController,
                    at index: PageboyViewController.PageIndex) -> UIViewController? {
    return viewControllers[index]
}
    
func defaultPage(for pageboyViewController: PageboyViewController) -> PageboyViewController.Page? {
    return nil
}

Enjoy.

Delegation

UIPageViewController doesn't provide the most useful delegate methods for detecting where you are when paging; this is where Pageboy comes in. PageboyViewControllerDelegate provides a number of functions for being able to detect where the page view controller is, and where it's headed.

willScrollToPageAtIndex

Called when the page view controller is about to embark on a transition to a new page.

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                           willScrollToPageAt index: Int,
                           direction: PageboyViewController.NavigationDirection,
                           animated: Bool)

didScrollToPosition

Called when the page view controller was scrolled to a relative position along the way transitioning to a new page. Also provided is the direction of the transition.

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                           didScrollTo position: CGPoint,
                           direction: PageboyViewController.NavigationDirection,
                           animated: Bool)

didScrollToPage

Called when the page view controller did successfully complete a scroll transition to a page.

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                           didScrollToPageAt index: Int,
                           direction: PageboyViewController.NavigationDirection,
                           animated: Bool)

didReload

Called when the page view controller reloads its child view controllers.

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                           didReloadWith currentViewController: UIViewController,
                           currentPageIndex: PageboyViewController.PageIndex)

Additional functionality

reloadPages - Reload the view controllers in the page view controller. (Refreshes the data source).
```
 public func reloadPages()
```

scrollToPage - Scroll the page view controller to a new page programatically.

 public func scrollToPage(_ pageIndex: PageIndex,
                            animated: Bool,
                            completion: PageTransitionCompletion? = nil)

Transitioning

Pageboy also provides custom animated transition support. This can be customised via the .transition property on PageboyViewController.

pageboyViewController.transition = Transition(style: .push, duration: 1.0)

The following styles are available:

.push
.fade
.moveIn
.reveal

Auto Scrolling

PageboyAutoScroller is available to set up timer based automatic scrolling of the PageboyViewController:

pageboyViewController.autoScroller.enable()

Support for custom intermission duration and other scroll behaviors is also available.

About

Created by Merrick Sapsford (@MerrickSapsford)
Contributed to by a growing list of others.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/uias/Pageboy.

License

The library is available as open source under the terms of the MIT License.

haarismuneer/Pageboy