diff --git a/README.md b/README.md index 841c814..7dff5d5 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,11 @@ While using this module you don't need to handle messages view on your own. You' ## Getting started In order to start using this framework you need to: -1. Embed this framework into your project using carthage -2. Create example ViewController From example below. ViewController has to conform protocols `MessagesViewDataSource` and `MessagesViewDelegate`. +1. Embed this framework +2. Style your view +3. Communicate with view via ViewController + + ### 1. Embedding framework @@ -40,7 +43,7 @@ to embed this project as source code you need to: *NOTE: To be able to track changes from storyboard at design time, you need to embed framework in non-standard way as described in 1b.* -### 2. Using framework +### 2. Styling your View Let's design! @@ -58,10 +61,154 @@ Example: ![styling input field background and text field rounding](https://cloud.githubusercontent.com/assets/16896355/24654216/10f95768-1939-11e7-9163-79acc0753d62.gif) You can find full list of customizable properties in the Wiki. This will be prepared soon. +### 3. Communicating with View via ViewController + +Create example ViewController From example below. ViewController has to conform protocols `MessagesViewDataSource` and `MessagesViewDelegate`. + +In order to communicate with MessagesView, your ViewController should contain: +- `MessagesViewDelegate` to take action when user taps a button +- `MessagesViewDataSource` to feed the view +- `IBOutlet MessagesView` to read information from view + +##### Don't forget do connect MessagesView to its `MessagesViewDataSource` and `MessagesViewDelegate`! + +#### 3.1 MessagesViewDelegate + + +```swift +public protocol MessagesViewDelegate { + func didTapLeftButton() + func didTapRightButton() +} +``` + +Your viewController need to implement actions taken after user taps left or right button + +#### 3.2 MessagesViewDataSource + +To feed view with intormation, your datasource have to provide two sets of information: *peers* and *messages* + +```swift +public protocol MessagesViewDataSource { + var messages : [MessagesViewChatMessage] {get} + var peers : [MessagesViewPeer] {get} +} +``` + +As you can see objects that carry messages have to conform to `MessagesViewChatMessage` protocol and objects that carry peers have to conform to `MessagesViewPeer`protocol. These are listed below: + +```swift +public protocol MessagesViewChatMessage { + var text : String {get} + var sender: MessagesViewPeer {get} + var onRight : Bool {get} +} + +public protocol MessagesViewPeer { + var id : String {get} +} +``` + +In the demo app we created extension to ViewController class that makes it compliant to `MessagesViewDataSource` protocol. In this case the limitation was that extension cannot contain stored properties so we decided to provide information via computed variables only but you can do as you wish in your own project. You need only to have object which is `MessagesViewDataSource` compliant. This is how we dealt with it in demo app: + +```swift +extension ViewController: MessagesViewDataSource { + struct Peer: MessagesViewPeer { + var id: String + } + + struct Message: MessagesViewChatMessage { + var text: String + var sender: MessagesViewPeer + var onRight: Bool + } + + var peers: [MessagesViewPeer] { + return TestData.peerNames.map{ Peer(id: $0) } + } + + var messages: [MessagesViewChatMessage] { + return TestData.exampleMessageText.enumerated().map { (index, element) in + let peer = self.peers[index % peers.count] + return Message(text: element, sender: peer, onRight: index%2 == 0) + } + } +} +``` + +In this example, we have converted on the fly our stored `TestData` information into *Messages* and *Peers*. No other class in the project have to be aware of `MessagesView`. Only `ViewController` is interested. + +#### 3.3 Create IBOutlet messagesView +Create IBOutlet in standard way +![creating IBOutlet for messagesView](https://cloud.githubusercontent.com/assets/16896355/24657607/2cff52f6-1947-11e7-8840-a6c2bb3d44fb.gif) -### Contributing development +Having your ViewController know about messagesView presence enables it to use view's public API. + +#### 3.4 Connecting delegate and data source + +In our example it is when ViewController loads: + +```swift + override func viewDidLoad() { + super.viewDidLoad() + // Do any additional setup after loading the view, typically from a nib. + messagesView.delegate = self + messagesView.dataSource = self + } +``` + +#### 3.5 Custom behaviours + +Additional behaviours that may be useful to you. + +- hiding buttons +```swift +leftButton(show: Bool, animated: Bool) +rightButton(show: Bool, animated: Bool) +``` + +This way you can show or hide button. Animated or not - as you wish. + +### Stay in touch +If you have any ideas how this project can be developed - do not hesitate to contact us at: + +dkanak@pgs-soft.com + +mgocal@pgs-soft.com + +bdudar@pgs-soft.com + +kszwaba@pgs-soft.com + +You are now fully aware of MessagesView capabilities. Good luck! + +### Contributing to development When contributing to MessagesView you may need to run it from within another project. Embedding this framework as described in paragraph 1.1b will help you work on opened source of this project. +Made with love in PGS ♥ __Please Use develop branch and fork from there!__ + +### License ### +MIT License + +Copyright (c) 2016 PGS Software SA + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.