updated

README.md

-#Angular Emoji Popup
+#Angular Emoji
+
+An angular module to serve multiple purpose:
+
+* A directive to render a comprehensive emoji popup from which user can select an emoji.
+* Filters to encode the message containing emoji to various formats and decode them.
 
 ###[Demo](http://madhur.co.in/angular-emoji-popup)
 
+###Note about encoding and decoding
+There are various standards to encode and decode emojis. Most popular are:
+
+* **Colon:** The emojis are converted to their colon style strings. This is simple to save in the database since its just a string.
+See the mapping at [http://www.emoji-cheat-sheet.com/](http://www.emoji-cheat-sheet.com/)
+
+* **UTF-8 Characters:** Emojis are mapped to their Unicode characters.  The advatage of this method is that some platforms (such as Android, iOS) can render them automatically as emoji unlike colon style encoding which almost always require decoding. On the disadvantage, Saving them in databases require special handling. See [note below](#db)
+
+A comprehensive list of unicode codes can be obtained from [http://apps.timwhitlock.info/emoji/tables/unicode](http://apps.timwhitlock.info/emoji/tables/unicode)
+
+* **HTML:** Emojis are converted to HTML `<img>` tags rendering each emoji as an image either from the single image or a sprite. 
+This is the least useful method to adopt as its not cross platform. There is no standardization of Emoji sprite images and hence you will never be sure that target platform has the same emoji images.
+
+This module contain various filters to encode and decode emojis in the above formats.
+
 ##Installation
 
+Include the JS files
+
+```html
+<script type="text/javascript" src="js/config.js"></script>
+<script type="text/javascript" src="js/emoji.min.js"></script>
+```
+
+Include the CSS file
+```html
+<link type="text/stylesheet" rel="stylesheet" href="css/emoji.min.css" />
+```
+
+Inject the `emojiApp` module to your app
+
+```js
+angular.module("myApp", ['emojiApp']);
+```
+
 ##Usage
 
+The module consists of following components:
+
+* `emojiForm` Directive - Enclose this directive with a textarea and a button named `emojibtn`.
+This directive adds a contenteditable div and hides the textarea. Anything typed into this conteteditable div is synced with the textarea. It also up the button to show an Emoji popup. 
+
+```html
+<div emoji-form emoji-message="emojiMessage">
+    <textarea id="messageInput" ng-model="emojiMessage.messagetext"></textarea>
+
+    <button id="emojibtn">
+        <i class="icon icon-emoji"></i>
+    </button>
+</div>
+```
+
+Make sure to initialize `emojiMessage` inside your controller
+
+```js
+emojiApp.controller('emojiController', ['$scope', '$log', function($scope, $log) {
+
+	$scope.emojiMessage={};
+}]);
+```
+###Encoding
+By default, emoji are encoded to colon style string. Hence `emojiMessage.messagetext` will contain the encoded emoji with colons.
+
+`emojiMessage.rawhtml` will contain the raw html string of the message.
+
+For additional encodings, the following filters can be used
+
+* `colonToCode` : Converts the colon style emoji string to string contaning UTF-8 characters
+
+```html
+<div ng-bind="emojiMessage.messagetext | colonToCode"> </div>
+```
+
+###Decoding
+For decoding the message string containing either colon style emojis or UTF-8 character emojis, following filters can be used:
+
+* `codeToSmiley` : Converts the string containing UTF-8 characters to smiley representation using HTML
+
+```html
+<div ng-bind-html="emojiMessage.encodedtext | codeToSmiley"></div>
+```
+
+* `colonToSmiley` : Converts the string containing colon characters to smiley representation using HTML
+
+```html
+<div ng-bind-html="emojiMessage.encodedtext | colonToSmiley"></div>
+```
+
 ##How it works
 
-## Using MySQL for storage
+Much of the functionality of this module is driven by the map contained in `config.js` file. It contains a mapping of Emoji UTF-8 character and its colon representation. If you encounter any bugs in this mapping, please raise an issue or send a pull request.
 
+## Using MySQL for storage
+<a name="db"></a>
 The following text is taken verbatim from [https://github.com/iamcal/js-emoji](https://github.com/iamcal/js-emoji)
 
 > Some special care may be needed to store emoji in your database. While some characters (e.g. Cloud, U+2601) are