Add custom actions to Switchcraft (#9)

* Add custom actions to Switchcraft

* Bump podspec

* Add example for custom action usage

* Move from callback approach to delegate approach

* Bump podspec to show change is breaking

* Add new delegate method to README

* Remove "Action: " from action labels

* Bump podspec up to 1.0.0

* Remove codable and equatable

* Use enums for clearer handling

* Allow didTapAction to be optional

* Make extension public to allow for optional delegate method

* Adding documentation for custom actions feature

* Fix minor spelling mistake

Author: jacobminer

Example/Pods/Pods.xcodeproj/project.pbxproj

@@ -27,6 +27,15 @@ extension Switchcraft {
             Endpoint(title: nil, url: URL(string: "http://apple.com")!),
             Endpoint(title: "Steamclock", url: URL(string: "http://steamclock.com")!)
         ],
+        actions: [
+            Action(title: "Custom action 1", actionId: Actions.custom1.rawValue),
+            Action(title: "Custom action 2", actionId: Actions.custom2.rawValue)
+        ],
         allowCustom: true
     ))
 }
+
+enum Actions: String {
+    case custom1
+    case custom2
+}

Example/Switchcraft/AppDelegate.swift

@@ -31,4 +31,18 @@ extension ReallySimpleExampleVC: SwitchcraftDelegate {
         currentEndpointLabel.isHidden = endpoint == switchcraft.defaultEndpoint
         currentEndpointLabel.text = "Current Endpoint:\n\(endpoint.name)"
     }
+
+    func switchcraft(_ switchcraft: Switchcraft, didTapAction action: Action) {
+        guard let action = Actions(rawValue: action.actionId) else {
+            return
+        }
+
+        switch action {
+        case .custom1:
+            print("tapped action 1")
+        case .custom2:
+            print("tapped action 2")
+        }
+
+    }
 }

Example/Switchcraft/ReallySimpleExampleVC.swift

@@ -51,7 +51,7 @@ To get updates whenever an endpoint is selected, you've got two options:
 1. Delegation
 
     If you only need to keep track of changes to the current endpoint in a single place, this is probably the way to go.
-    Classes that want to recieve updates only need to register your `viewController` as a delegate and conform to the `SwitchcraftDelegate` protocol.
+    Classes that want to receive updates only need to register your `viewController` as a delegate and conform to the `SwitchcraftDelegate` protocol.
 
     ```
     class MyVC: UIViewController {
@@ -87,6 +87,72 @@ To get updates whenever an endpoint is selected, you've got two options:
         // Handle endpoint selected here
     }
     ```
+
+### Custom Actions
+
+1. Add some custom actions to Switchcraft via the `Config`:
+```swift
+extension Switchcraft {
+    static let shared = Switchcraft(config: Config(
+            defaultsKey: ...,
+            endpoints: ...,
+            actions: [
+                Action(title: "Custom action 1", actionId: "customAction1"),
+                Action(title: "Custom action 2", actionId: "customAction2")
+            ]
+        ))
+}
+```
+
+2. Add the following to your SwitchCraftDelegate:
+```swift
+extension MyVC: SwitchcraftDelegate {
+    ...
+ 
+    func switchcraft(_ switchcraft: Switchcraft, didTapAction action: Action)
+        // Handle custom action selection here
+    }
+}
+```
+
+Note: We recommend using Swift enums for the actionId, like the following example:
+```swift
+enum Actions: String {
+    case custom1
+    case custom2
+}
+
+extension Switchcraft {
+    static let shared = Switchcraft(config: Config(
+            defaultsKey: ...,
+            endpoints: ...,
+            actions: [
+                Action(title: "Custom action 1", actionId: Actions.custom1.rawValue),
+                Action(title: "Custom action 2", actionId: Actions.custom2.rawValue)
+            ]
+        ))
+}
+
+extension MyVC: SwitchcraftDelegate {
+    ...
+
+    func switchcraft(_ switchcraft: Switchcraft, didTapAction action: Action) {
+        guard let action = Actions(rawValue: action.actionId) else {
+            return
+        }
+
+        switch action {
+        case .custom1:
+            // handle the first custom action tapped
+            ...
+        case .custom2:
+            // handle the second custom action tapped
+            ...
+        }
+    }
+}
+
+```
 
 ### Getting Fancy
 

README.md

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'Switchcraft'
-  s.version          = '0.1.2'
+  s.version          = '1.0.0'
   s.summary          = 'Drop and go endpoint selector written in Swift.'
   s.homepage         = 'https://github.com/steamclock/Switchcraft'
   s.license          = { :type => 'MIT', :file => 'LICENSE' }

Switchcraft.podspec

@@ -0,0 +1,34 @@
+//
+//  Actions.swift
+//  Pods-Switchcraft_Example
+//
+//  Created by Jake on 2018-07-05.
+//
+
+import Foundation
+
+/**
+ * Represents an action that can be tapped using the `Switchcraft` picker.
+ */
+public struct Action {
+    /**
+     * A title to be shown for the action.
+     */
+    public let title: String
+
+    /**
+     * A unique ID for the action.
+     */
+    public let actionId: String
+
+    /**
+     * Create a new action.
+     *
+     * - parameter title: The title to show in the endpoint selection menu.
+     * - parameter actionId: The unique identifier for the action.
+     */
+    public init(title: String, actionId: String) {
+        self.title = title
+        self.actionId = actionId
+    }
+}

Switchcraft/Classes/Action.swift

@@ -68,6 +68,11 @@ public struct Config {
      */
     public var endpoints: [Endpoint] = []
 
+    /**
+     * The set of custom actions to be shown in the switcher.
+     */
+    public var actions: [Action] = []
+
     /**
      * The index of the default endpoint in `endpoints`.
      * Default is `0`.
@@ -82,9 +87,10 @@ public struct Config {
      * - parameter endpoints: The set of endpoints to show in the picker.
      * - parameter allowCustom: Whether the switcher allows entering custom endpoints.
      */
-    public init(defaultsKey: String, endpoints: [Endpoint], allowCustom: Bool = false) {
+    public init(defaultsKey: String, endpoints: [Endpoint], actions: [Action] = [], allowCustom: Bool = false) {
         self.defaultsKey = defaultsKey
         self.endpoints = endpoints
         self.allowCustom = allowCustom
+        self.actions = actions
     }
 }

Switchcraft/Classes/Config.swift

@@ -14,6 +14,19 @@ public protocol SwitchcraftDelegate: AnyObject {
      * Called when an endpoint is selected.
      */
     func switchcraft(_ switchcraft: Switchcraft, didSelectEndpoint endpoint: Endpoint)
+
+    /**
+     * Called when an action is tapped.
+     */
+    func switchcraft(_ switchcraft: Switchcraft, didTapAction action: Action)
+}
+
+
+// provides a default extension, so other applications don't have to override the action handling
+public extension SwitchcraftDelegate {
+    func switchcraft(_ switchcraft: Switchcraft, didTapAction action: Action) {
+        // no-op, allowing this method to be optional
+    }
 }
 
 /**
@@ -191,6 +204,19 @@ public class Switchcraft {
             })
         }
 
+        for action in config.actions {
+            alertController.addAction(
+                UIAlertAction(
+                    title: action.title,
+                    style: .default,
+                    handler: { [weak self] _ in
+                        self?.tapped(action: action)
+                        viewController.dismiss(animated: false, completion: nil)
+                    }
+                )
+            )
+        }
+
         alertController.addAction(
             UIAlertAction(
                 title: config.cancelTitle,
@@ -263,6 +289,15 @@ public class Switchcraft {
         NotificationCenter.default.post(name: .SwitchcraftDidSelectEndpoint, object: self, userInfo: [Notification.Key.Endpoint: endpoint])
     }
 
+    /**
+     * Called when an action is tapped.
+     *
+     * - parameter action: The action tapped.
+     */
+    private func tapped(action: Action) {
+        delegate?.switchcraft(self, didTapAction: action)
+    }
+
     /**
      * Create and return the default UITapGestureRecognizer recognizer to attach to a view.
      * The default gesture is a three finger double tap unless built with the simulator,