Doc++

README.md

@@ -1,25 +1,27 @@
 Native Keyboard
 ===============
 
-TODO niceify
+> Every mobile app attempts to expand until it includes chat. Those applications which do not are replaced by ones which can.
+>
+> -- _[Luke Wroblewski](http://www.lukew.com/ff/entry.asp?1696)_
 
-This plugin aims to solve common keyboard problems encountered with Cordova / PhoneGap apps.
-The messenger component (see screenshots) is ready for production, but this plugin will have
-more tricks up its sleeve. I'll document those once they're ready for primetime as well.
 
-## Screenshots
-Messenger component
+<img src="media/videos/iOS/messenger.gif" height="716px"/>&nbsp;&nbsp;&nbsp;
+<img src="media/videos/Android/messenger.gif" height="716px"/>
 
-### iOS
-<img src="screenshots/iOS/messenger-1.png?v=2" width="350px"/>&nbsp;&nbsp;&nbsp;
-<img src="screenshots/iOS/messenger-2.png?v=2" width="350px"/>
+_Video's of iOS and Android running the included demo app._
 
-### Android
-<img src="screenshots/Android/messenger-1.png?v=2" width="350px"/>&nbsp;&nbsp;&nbsp;
-<img src="screenshots/Android/messenger-2.png?v=2" width="350px"/>
+## So it's just a fancy keyboard?
+You're damn right it is! 👍
 
+A cross platform WhatsApp / Messenger / Slack -style keyboard even. For _your_ Cordova app.
+
+## Cool, but does it scale?
+Lol wut?
+
+## OK, let me try this..
+Open a command prompt and do:
 
-## I wanna try it!
 ```
 $ cordova create nativekeyboardtest
 $ cd nativekeyboardtest
@@ -33,17 +35,84 @@ $ cordova run ios
 $ cordova run android
 ```
 
-ALL features are available, but you'll be restricted to 5 minutes of usage.
-Just kill and relaunch the app if you need more time ;)
+## I'm no dummy, gimme details man!
+ok ok OK! The plugin is currently entirely focused on the messenger component, but this will extend into [other areas](https://github.com/EddyVerbruggen/cordova-plugin-native-keyboard/issues/1) in the future. With that being said, this is the current awesome API:
+
+### `showMessenger`
+The bare minimum you need to show the messenger and do something useful with the text a user typed is this (make sure you wait for `deviceready` to fire):
+
+```js
+NativeKeyboard.showMessenger({
+  onSubmit: function(text) {
+    console.log("The user typed: " + text);
+  }
+});
+```
+
+There are however __many__ options you can pass in to tweak the appearance and behavior:
+
+TABEL HIER, met iOS/Android checkbox kolommen
+
+
+|option|default|iOS|Android|description
+|---|---|---|---|---
+|`onSubmit`||[x]|[x]|A function invoked when the user submits his input. Receives the text as a single property. Make sure your page is UTF-8 encoded so Chinese and Emoji are rendered OK.
+|`onKeyboardDidShow`||[x]|[x]|A function invoked when the keyboard popped up. Receives the height as a single property.
+|`onKeyboardDidHide`||[x]|[x]|A function invoked when the keyboard closed.
+|`autoscrollElement`||[x]|[x]|Highly recommended to pass in if you want to replicate the behavior of the video's above (scroll down when the keyboard opens). Pass in the scrollable DOM element containing the messages, so something like `document.getElementById("messageList")`.
+|`scrollToBottomAfterMessengerShows`||[x]|[x]|If `autoscrollElement` was set you can also make the list scroll down initially, when the messenger bar (without the keyboard popping up) is shown.
+|`keepOpenAfterSubmit`|`false`|[x]|[x]|Setting this to `true` is like the video's above: the keyboard doesn't close upon submit.
+|`animated`|`false`|[x]|[x]|Makes the messenger bar slide in from the bottom.
+|`textColor`|`#444444`|[x]|[x]|The color of the typed text.
+|`placeholder`||[x]|[x]|Like a regular HTML input placeholder.
+|`placeholderColor`|`#CCCCCC`|[x]|[x]|The color of the placeholder text.
+|`backgroundColor`|`#F6F6F6`|[x]|[x]|The background color of the messenger bar.
+|`textViewBackgroundColor`|`#F6F6F6`|[x]|[x]|The background color of the textview. Looks nicest on Android if it's the same color as the `backgroundColor` property.
+|`maxChars`|unlimited|[x]|[x]|Setting this > 0 will make a counter show up on iOS (and ignore superfluous input on Android, for now)
+|`counterStyle`|"none"|[x]|[ ]|Options are: "none", "split", "countdown", "countdownreversed". Note that if `maxChars` is set, "none" will still show a counter.
+|`leftButton`||[x]|[x]|See below
+|`rightButton`||[x]|[x]|See below
 
-Tweak the `showMessenger()` method to play with its behavior and appearance.
+#### leftButton
+The button on the left is optional and can be used to for instance make a picture, grab a picture from the camera role, shoot a video, .. whatever you fancy, really as the implementation is entirely up to you.
+
+As shown in the video's it's common to present these options as an ActionSheet, either [native](https://github.com/EddyVerbruggen/cordova-plugin-actionsheet) or a [HTML widget](https://ionicframework.com/docs/api/service/$ionicActionSheet/).
+
+|option|default|iOS|Android|description
+|---|---|---|---|---
+|`type`||[x]|[x]|Either "text" (Android only currently), "fontawesome" or "ionicon".
+|`value`||[x]|[x]|Depends on the `type`. Examples: for "text" use "Send", for "fontawesome" use "fa-battery-quarter", for "ionicon" use "\uf48a" (go to http://ionicons.com, right-click and inspect the icon and use the value you find in `:before`). Note that some fonticons are not supported as the embedded fonts in the plugin may lag behind a little. So try one of the older icons first.
+|`textStyle`|"normal"|[x]|[x]|If `type` is "text" you can set this to either "normal", "bold" or "italic".
+|`disabledWhenTextEntered`|`false`|[x]|[x]|Set to `true` to disable the button once text has been entered.
+|`onPress`||[x]|[x]|A function invoked when the button is pressed. Use this button to prompt the user what he wants to do next by for instance rendering an ActionSheet.
+
+#### rightButton
+The button on the right is used to submit the entered text. You don't need to configure this at all if you're happy with the default "Send" label as the entered text itself will be emitted through the `onSubmit` callback.
+
+|option|default|iOS|Android|description
+|---|---|---|---|---
+|`type`|"text"|[x]|[x]|Either "text", "fontawesome" or "ionicon".
+|`value`|"Send"|[x]|[x]|See the description of `leftButton.value`.
+|`textStyle`|"normal"|[x]|[x]|See the description of `leftButton.textStyle`.
+|`onPress`||[x]|[x]|A function invoked when the button is pressed. Use this to for instance hide the messenger entirely after text was entered by calling `NativeKeyboard.hideMessenger()`.
+
+
+### `hideMessenger`
+It's likely your app only has 1 one page where you want to show the messenger, so you want to hide it when the user navigates away. You can choose to do this either animated (a quick slide down animation) or not.
+
+```js
+NativeKeyboard.hideMessenger({
+  animated: true // default false
+});
+```
 
 ## I like it, hook me up!
-This plugin has been a BEAST to implement and its maintenance is killing me already
-so I need to make this a commercial offering to keep it afloat. If you have a compelling
-reason to not pay for an unlocked version let me know and we'll try to work out something.
+This plugin has been a BEAST to implement and its maintenance is killing me already so I need to make this a commercial offering to keep it afloat. If you have a compelling reason to not pay for an unlocked version let me know and we'll work something out.
 
 * Look up the ID of the app you want to use the plugin with - you can find it at the top of config.xml and is something like `io.cordova.hellocordova`.
 * Send a __one-time__ fee of $ 199 to [my PayPal account](https://www.paypal.me/EddyVerbruggen/199usd) and make sure to include your app ID.
 * You'll quickly receive a license key (and instructions) which you can use to install the plugin.
-* You can now forever use this version and any future version of this plugin for this app without restrictions.
+* You can now forever use this version and any future version of this plugin for this app without restrictions.
+
+## I heard about a trial!?
+ALL features are available without a license, but you'll be restricted to 5 minutes of usage. Just kill and relaunch the app if you need more time ;)