farshadmb / Pageboy

A simple, highly informative page view controller.

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.

Installation

CocoaPods

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

pod 'Pageboy'

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" 

Requirements

Pageboy requires iOS 8.0 or above.

Usage

Getting Started

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

class PageViewController: PageboyViewController, PageboyViewControllerDataSource {

	override func viewDidLoad() {
		super.viewDidLoad()

		self.dataSource = self
	}
}

2. Implement the PageboyViewControllerDataSource functions.

func viewControllers(forPageboyViewController pageboyViewController: PageboyViewController) -> [UIViewController]? {
	// return array of view controllers
	return [viewController1, viewController2]
}

func defaultPageIndex(forPageboyViewController pageboyViewController: PageboyViewController) -> PageboyViewController.PageIndex? {
	// use default index
	return nil
}

3. 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,
                             willScrollToPageAtIndex 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,
                             didScrollToPosition position: CGPoint,
                             direction: PageboyViewController.NavigationDirection)

didScrollToPage

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

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

didReload

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

func pageboyViewController(_ pageboyViewController: PageboyViewController,
                             didReload viewControllers: [UIViewController],
                             currentIndex: 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

AutoScrolling

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.

Properties

View Controller Management

• viewControllers: [UIViewController]? - The view controllers that are displayed in the page view controller.
• currentViewController: UIViewController? - The view controller that the page view controller is currently at.

Positional Data

• currentIndex: Int? - The page index that the page view controller is currently at.
• currentPosition: CGPoint? - The relative page position that the page view controller is currently at.

Interaction

• isScrollEnabled: Bool - Whether scroll is enabled on the page view controller.
• isDragging: Bool - Whether the page view controller is currently being dragged.
• isScrollingAnimated: Bool - Whether the page view controller is currently animating a scroll between pages.
• isUserInteractionEnabled: Bool - Whether user interaction is enabled on the page view controller.
• navigationOrientation: UIPageViewControllerNavigationOrientation - The orientation that the page view controller transitions on.
• isInfiniteScrollEnabled: Bool - Whether the page view controller should infinitely scroll between page limits (i.e. able to continuously scroll to first page from last).

About

• Created by Merrick Sapsford (@MerrickSapsford)

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.