Merge pull request #38 from nodes-ios/release/2.0.0

Release/2.0.0
ml-opensource · Apr 22, 2020 · e4883d5 · e4883d5
2 parents 56b4395 + 4dc06e6
commit e4883d5
Show file tree

Hide file tree

Showing 157 changed files with 768 additions and 14,147 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Rye
+# 🍞 Rye
 
 [![Carthage Compatible](https://img.shields.io/badge/carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)
 ![Plaforms](https://img.shields.io/badge/platforms-iOS%20-lightgrey.svg)
@@ -7,15 +7,16 @@
 
 ## Intro
 
-Rye allows you to present non intrusive alerts to your users of both "Toast" and "Snack Bar" types.
+Rye allows you to present non intrusive alerts to your users.
+
 You can choose to display the default Rye alert type or go fully custom and display your own `UIView`.
 
 ### Examples
 
 
 | ![](ExampleImages/example1.png) | ![](ExampleImages/example2.png)  | ![](ExampleImages/example3.png)  |
 |----------------|---|---|
-|      <center>Custom Rye with Image</center>      |  <center>Custom Rye with Button</center>  |  <center>Default Rye</center> |
+|      <center>Custom Rye alert with Image</center>      |  <center>Custom Rye alert with Button</center>  |  <center>Default Rye alert</center> |
 
 ## 📝 Requirements
 
@@ -36,75 +37,190 @@ pod 'nodes-ios/Rye'
 
 ## 💻 Usage
 
+### Principles
+
+To display a Rye alert you declare a new `RyeViewController` and then call:
+
+- `show`: to show the alert
+- `dismiss`: to dismiss the alert
+
+**Note:** Depending on which `dismissMode` you have selected, you may not need to dismiss the alert yourself, see the section about [`displayModes`](#display-modes) below for more information.
+
+At the very minimum you need to consider:
+
+- which text to show
+- whether to show a standard alert or bring your own custom view to the party
+- where to show the text (`top` or `bottom`)
+
+#### Show Text
+
+To show a text using a Rye alert you need to create a `RyeConfiguration`. This is a dictionary allowing you to configure various UI related aspects of your Rye alert. For more information on available keys, please refer to the section: [Possible Rye Configuration Values](#possible-rye-configuration-values) below.
+
+One of the values you can add to a `RyeConfiguration` is a text to show in your alert.
+
 ```swift
-import Rye
+let ryeConfiguration: RyeConfiguration = [Rye.Configuration.Key.text: "Message for the user"]
 ```
 
-### Display Default Rye
+#### Alert Type
+
+You can use the default Rye alert or you can create your own view and use that instead. To determine which to use, you use the `Rye.ViewType` enum defined like so:
 
 ```swift
+public enum ViewType {
+    case standard(configuration: RyeConfiguration?)
+    case custom(UIView, animationType: AnimationType = .slideInOut)
+}
+```
 
-let ryeConfiguration: RyeConfiguration = [Rye.Configuration.Key.text: "Message for the user"]
+As you can see, the `standard` ViewType takes an optional `RyeConfiguration` as a parameter. This means that you don't _have_ to provide a `RyeConfiguration` in which case default values will be used for all parameters including the text (but you probably don't want an alert showing the text "Add a message", do you?).
+
+ The `custom` ViewType takes the view you would like to use and a `Rye.AnimationType` (with a default value already provided). For more on the `AnimationType` please refer to the section [Animation Type](#animation-type) below.
+
+#### Where To Show the Alert?
+
+Where to show a Rye alert is determined by a `Rye.Position` enum which is defined like so:
+
+```swift
+public enum Position {
+    case top(inset: CGFloat)
+    case bottom(inset: CGFloat)
+}
+```
+
+For more on the `Rye.Position` please refer to the section [Position](#position) below.
+
+### Display a Default Rye
+
+Following these principles, we are now ready to show our first Rye alert.
 
-let rye = RyeViewController.init(alertType: .toast,
-                                viewType: .standard(configuration: ryeConfiguration),
-                                at: .bottom(inset: 16),
-                                timeAlive: 2)
+```swift
+import Rye
+...
+let ryeConfiguration: RyeConfiguration = [Rye.Configuration.Key.text: "Message for the user"]
+let rye = RyeViewController.init(viewType: .standard(configuration: ryeConfiguration),
+                                 at: .bottom(inset: 16))
 rye.show()
+```
+
+This will result in a Rye alert with the text "Message for the user" appearing at the bottom at the screen and then disappearing automatically after 2.5 seconds.
 
+### Control the Dismiss Type
+
+If you would like the Rye alert to disappear in a different way, you can pass a `dismissMode` parameter when creating the `RyeViewController`
+
+```swift
+import Rye
+...
+let ryeConfiguration: RyeConfiguration = [Rye.Configuration.Key.text: "Message for the user"]
+let rye = RyeViewController.init(dismissMode: .gesture,
+                                 viewType: .standard(configuration: ryeConfiguration),
+                                 at: .bottom(inset: 16))
+rye.show()
 ```
 
+The alert will now stay on the screen until the user taps or swipes at it.
+
 ### Display Default Rye with Custom Configuration
 
-```swift
+If you want to have more control of the alert view you can add keys and values to the `RyeConfiguration` as shown here.
 
+```swift
+import Rye
+...
 let ryeConfiguration: RyeConfiguration = [
     Rye.Configuration.Key.text: "Error message for the user",
     Rye.Configuration.Key.backgroundColor: UIColor.red.withAlphaComponent(0.4),
-    Rye.Configuration.Key.animationType: Rye.AnimationType.fadeInOut]
+    Rye.Configuration.Key.animationType: Rye.AnimationType.fadeInOut
 ]
 
-let rye = RyeViewController.init(alertType: .toast,
-                                viewType: .standard(configuration: ryeConfiguration),
-                                at: .bottom(inset: 16),
-                                timeAlive: 2)
+let rye = RyeViewController.init(viewType: .standard(configuration: ryeConfiguration),
+                                 at: .bottom(inset: 16))
 rye.show()
 
 ```
 
 ### Display Rye with a Custom `UIView`
 
-```swift
+For even more control you can create your own subclass of `UIView` and use `.custom` for the `viewType` parameter
 
-let customRyeView = RyeView()
+```swift
+import Rye
+...
 
-let rye = RyeViewController.init(alertType: .toast,
-                                viewType: .custom(customRyeView),
-                                at: .bottom(inset: 16),
-                                timeAlive: 2)
+let customView = YourCustomViewHere()
+let rye = RyeViewController.init(viewType: .custom(customView),
+                                 at: .bottom(inset: 16))
 rye.show()
 
 ```
 
-### Alert Type
+### Dismiss Completion
+If you would like to execute some code when the Rye alert is dismissed you can pass a `dismissCompletion` code block when calling `show` like so:
+
+```swift
+import Rye
+...
+let ryeConfiguration: RyeConfiguration = [Rye.Configuration.Key.text: "Message for the user"]
+let rye = RyeViewController.init(viewType: .standard(configuration: ryeConfiguration),
+                                 at: .bottom(inset: 16))
+rye.show(withDismissCompletion: {
+    print("Goodbye from Rye, time to dy..die")  
+})
+```
+
+### Dismiss Rye Alerts Manually
+
+If you have selected to show a Rye alert as `.nonDismissable` you have to dismiss it yourself. Keep a reference to the `RyeViewController` and call `dismiss` when you are ready to let go.
+
+```swift
+import Rye
+...
+var rye: RyeViewController?
+
+let ryeConfiguration: RyeConfiguration = [Rye.Configuration.Key.text: "Message for the user"]
+rye = RyeViewController.init(dismissMode: .nonDismissable,
+                             viewType: .standard(configuration: ryeConfiguration),
+                             at: .bottom(inset: 16))
+rye?.show()
+
+...at a later point in time
+rye?.dismiss()
+```
+
+### Descriptions of Parameters
 
-Rye allows you to define the alert type you want to display to your user. Possible alert types are:
+Below you can find descriptions of the various parameters used to control a Rye alert.
 
-- snackBar which is displayed at applications UIWindow level and allows interaction with the presented UIView
-- toast which is displayed at applications alert UIWindow level and doesn't allows interaction with the presented UIView
+#### Display Modes
 
-###  Position
+Rye supports three different `displayMode` values which can be passed when creating a new `RyeViewController`:
+
+- `automatic`: The alert appears and disappears automatically after a specified interval.
+- `gesture`: To dismiss the alert you can tap or swipe it.
+- `nonDismissable`: The alert will stay permanently on the screen until it is dismissed by calling `dismiss()` on your `RyeViewController` instance.
+
+If you do not pass this value when creating a new `RyeViewController`, a default value of `automatic` with a default interval of 2.5 seconds is used (the default interval is defined in `Rye.defaultDismissInterval`)
+
+#### Position
+
+With Rye, you can specify the position where the Rye alert will be displayed on the screen via the `position` parameter, which takes an associated value that allows you to specify the inset.
 
-With Rye you can specify the position where the Rye view will be displayed on screen via the `position` parameter, which takes an associated value that allows you to specify the inset.
 By default Rye will calculate the safe area insets for you, so be sure to specify only the extra desired inset.
 
-If you decide to not provide a value for this parameter, you will be in charge of dismissing the Rye when you think it is appropriate.
 
-### Time Used
+#### Animation Type
+
+Rye provides two animation types:
 
-When creating an instance of  `RyeViewController` you can choose to provide a value for  the `timeAlive` parameter during initialisation. The value provided will be the time in seconds the Rye view will be presented on screen to the user.
+- `slideInOut`: slides the view in from either top or bottom (depending on which `Position` you have selected). When dismissed the view slides out in the same direction.
+- `fadeInOut`: fades the view in and out again when dismissed.
 
-### Possible Rye Configurations
+To control how long the animation will take when using a `.standard` view, please use the `animationDuration` key of the `RyeConfiguration` and provide a `TimeInterval` value.
+
+In case you are using a `.custom` view or you _do not_ provide a value for `animationDuration`, a standard value of 0.3 seconds is used.
+
+#### Possible Rye Configuration Values
 
 The following keys can be used in the configuration dictionary when presenting a default type Rye:
 
@@ -118,8 +234,32 @@ The following keys can be used in the configuration dictionary when presenting a
 
 If configuration is set to nil, a default configuration will be used. Any options set, will override the default state.
 
+## ⚠️ Gotchas
+
+In order to display a Rye message a `parentView` is needed to determine _in relation to what_ the Rye message is positioned.
+
+If you try to display a Rye message before a `parentView` can be obtained, you will see this warning in the console of your IDE.
+
+> A parentView could not be found to display the Rye message on. Are you trying to show a Rye message before the view lifecycle is ready to display views?
+
+This can be seen if you try to call `show()` on a `RyeViewController` in `viewDidLoad()` of a `UIViewController` for instance.
+
+
 ## Example Project
-To learn more, please refer to the example project contained in this repository.
+To learn more, please refer to the RyeExample project contained in this repository.
+
+## ⬆️ Updating from v1.x.x to v2.0.0
+In version 2.0.0 of Rye we changed the way you display messages.
+
+Gone is the distinction between `.toast` and `.snackBar`. Instead, every message is now displayed in a separate `UIWindow` at the very top level of your view stack and you must decide how to dismiss the message with the previously described [`displayModes`](#display-modes).
+
+This also means that the previous init method: `RyeViewController.init(alertType:viewType:at:timeAlive:)` has been deprecated. If you use this init method with version 2.0.0 you will receive a deprecation warning during compilation.
+
+You can - if you stubbornly insist - still use the now old `init` method. Behind the scenes Rye will create a new `RyeViewController` for you and set the `displayMode` based on these rules:
+
+_If_ you have added a `timeAlive` value, that `timeAlive` will be used to create a `displayMode` with a value of `.automatic(interval: timeAlive)`
+
+_If_ you have _not_ added a `timeAlive` value, the `displayMode` will be `.nonDismissable`.
 
 ## 👥 Credits
 Made with ❤️ at [Nodes](http://nodesagency.com).

diff --git a/Rye.podspec b/Rye.podspec
@@ -3,8 +3,8 @@
 Pod::Spec.new do |spec|
 
   spec.name         = "Rye"
-  spec.version      = "1.1.9"
-  spec.summary      = "Rye allows you to present non intrusive alerts to your users of both \"Toast\" and \"Snack Bar\" types. You can choose to display the default Rye alert type or go fully custom and display your own UIView."
+  spec.version      = "2.0.0"
+  spec.summary      = "Rye allows you to present non intrusive alerts to your users. You can choose to display the default Rye alert type or go fully custom and display your own UIView."
   spec.homepage     = "https://github.com/nodes-ios/Rye"
 
   spec.author       = { "Nodes Agency - iOS" => "[email protected]" }

diff --git a/Rye/Podfile b/Rye/Podfile
diff --git a/Rye/Podfile.lock b/Rye/Podfile.lock
diff --git a/Rye/Pods/Manifest.lock b/Rye/Pods/Manifest.lock