Updated Getting Started Guide

Author: marbetschar

Guides/Getting Started.md

@@ -2,37 +2,11 @@
 
 These instructions will get you a up and running to use `ProgressKit` in your own app.
 
-## Prerequisites
-
-Make sure you have the following installed on your system to kick things off:
-
-- [Xcode 10.2+](https://developer.apple.com/xcode/)
-- iOS 12+
-- [Swift 5+](https://swift.org/getting-started/)
-- [Carthage](https://github.com/Carthage/Carthage#installing-carthage) 
-- [Jazzy](https://github.com/realm/jazzy)
-
 ## Installation
 
-To add `ProgressKit` as Carthage dependency insert the following line to your `Cartfile`:
-
-```
-github "Progress4Apple/ProgressKit" ~> 1.0
-```
-
-Let `Carthage` download and compile the library by executing the following command:
-
-```
-carthage bootstrap --platform iOS
-```
+See the Getting Started section of the README for how to install `ProgressKit`.
 
-As last step add the built libraries in Xcode. See ["Adding frameworks to an application" in the Carthage documentation for further details](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application):
-
-- `ProgressKit.framework`
-- `FLAnimatedImage.framework`
-- `GiphyCoreSDK.framework`
-
-## Usage
+## Configuration
 
 Import `ProgressKit` and call `Progress.configure(...)` in `application(_:didFinishLaunchingWithOptions:)` of your AppDelegate.swift for initialization:
 
@@ -53,3 +27,140 @@ func application(_ application: UIApplication,
         giphyApiKey: "your-giphy-api-key"
     )
 ```
+
+## Create a ViewController
+
+To render the progress bars for the available reports, create a new `UICollectionViewController` in your app and subclass the `ProgressCollectionViewController`:
+
+```
+import UIKit
+import ProgressKit
+
+class ViewController: ProgressCollectionViewController {
+    ...
+}
+````
+
+## Set delegate and dataSource
+
+Make sure you set the ViewController's delegate and dataSource objects In your `viewDidLoad`. To begin with, we set both to `self`:
+
+```
+import UIKit
+import ProgressKit
+
+class ViewController: ProgressCollectionViewController {
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        
+        delegate = self
+        dataSource = self
+    }
+}
+```
+
+Then we make sure our ViewController conforms to `ProgressCollectionViewControllerDelegate`:
+
+```
+import UIKit
+import ProgressKit
+import EventKit
+
+class ViewController: ProgressCollectionViewController, ProgressCollectionViewControllerDelegate {
+    ...
+    
+    // MARK: ProgressCollectionViewControllerDelegate
+
+    func progressCollection(
+        _ viewController: ProgressCollectionViewController,
+        handleAuthorizationStatusNotSufficient status: EKAuthorizationStatus
+    ) {
+    // TODO: Insert your implementation here.
+    }
+
+
+    func progressCollection(
+        _ viewController: ProgressCollectionViewController,
+        didSelectReport report: PKReport
+    ) {
+        // TODO: Insert your implementation here.
+    }
+
+
+    func progressCollection(
+        _ viewController: ProgressCollectionViewController,
+        handleError error: Error
+    ) {
+        // TODO: Insert your implementation here.
+    }
+
+
+    func progressCollection(
+        _ viewController: ProgressCollectionViewController,
+        openPreferencesAtURL url: URL,
+        completionHandler: @escaping ((Bool) -> Void)
+    ) {
+        UIApplication.shared.open(url, options: [:], completionHandler: completionHandler)
+    }
+}
+```
+
+... and finally, our ViewController should also conform to `ProgressCollectionViewControllerDataSource`:
+
+```
+import UIKit
+import ProgressKit
+import EventKit
+
+class ViewController: ProgressCollectionViewController, ProgressCollectionViewControllerDelegate, ProgressCollectionViewControllerDataSource {
+    ...
+
+    // MARK: ProgressCollectionViewControllerDataSource
+
+    func progressCollection(
+        _ viewController: ProgressCollectionViewController,
+        loadReports completionHandler: ([[PKReport]]?, Error?) -> Void
+    ) {
+        let report = PKReport(
+            identifier: "1234",
+            displayStyle: .progress,
+            listIdentifier: nil,
+            searchTerm: nil,
+            isPriorityBased: false,
+            timeRange: nil,
+            deadline: nil,
+            goal: nil,
+            showInTodayScreen: false,
+            notificationsEnabled: false
+        )
+        let reportSection = [report]
+        
+        var allReports = [[PKReport]]()
+        allReports.append(reportSection)
+        
+        completionHandler(allReports, nil)
+    }
+
+
+    func progressCollection(
+        _ viewController: ProgressCollectionViewController,
+        shouldReload completionHandler: ((Bool) -> Void)
+    ) {
+        completionHandler(true)
+    }
+
+
+    func progressCollection(
+        _ viewController: ProgressCollectionViewController,
+        saveReports reports: [[PKReport]],
+        completionHandler: ((Bool, Error?) -> Void)
+    ) {
+        // TODO: Insert your implementation here.
+    }
+}
+```
+
+## Next steps
+
+There you go. That's the bare minimum you need to render reports. As next step you may want to add your implementation for saving and loading reports so the user is able to configure those. For this have a look at `PKReportStore.standard` which makes it easy to persist and query reports to/from disk.

ProgressKit/ProgressCollectionViewController/ProgressCollectionViewController.swift

@@ -32,14 +32,21 @@ import NotificationCenter
  */
 open class ProgressCollectionViewController: UICollectionViewController, UICollectionViewDelegateFlowLayout, UICollectionViewDataSourcePrefetching {
 
+    /// All currently loaded `PKReport`s provided by the dataSource, grouped by section.
     private (set) public var allReports: [[PKReport]] = []
+    
+    /// The `PKReport` currently selected by the user if any.
     private (set) public var selectedReport: PKReport?
 
+    /// `ProgressCollectionViewControllerDataSource` for the ViewController.
     public var dataSource: ProgressCollectionViewControllerDataSource?
+    
+    /// `ProgressCollectionViewControllerDelegate` for the ViewController.
     public var delegate: ProgressCollectionViewControllerDelegate?
 
     private var notificationToken: PKNotification.Token?
 
+    /// Helper function which determines the desired `PKLayoutStyle` based upon a given [`UITraitCollection`](https://developer.apple.com/documentation/uikit/uitraitcollection).
     public func layoutStyle(for traitCollection: UITraitCollection) -> PKLayoutStyle {
         return traitCollection.horizontalSizeClass == .regular ? .grid : .table
     }