Merge branch 'release/0.9.5'

.editorconfig

@@ -24,4 +24,4 @@ trim_trailing_whitespace = true
 [*.json]
 indent_style = space
 indent_size = 2
-trim_trailing_whitespace = true
+trim_trailing_whitespace = true

.gitattributes

@@ -0,0 +1 @@
+* text=auto

.htaccess

@@ -2,7 +2,6 @@
 AddOutputFilterByType DEFLATE text/html text/event-stream text/xml text/css text/javascript application/javascript application/json
 
 # Set cache lifetime for these files as a week
-# <FilesMatch ".(js|css)$">
-#     Header set Cache-Control "max-age=604800, public"
-# </FilesMatch>
-
+<FilesMatch ".(js|css)$">
+    Header set Cache-Control "max-age=604800, public"
+</FilesMatch>

.jshintrc

@@ -13,14 +13,11 @@
     "strict"        : true,     // true: Requires all functions run in ES5 Strict Mode
     "trailing"      : true,     // true: Prohibit trailing whitespaces
 
+    // Predefined stuff
+    "predef"        : ["define", "module"],
+
     // Environments
     "browser"       : true,     // Web Browser (window, document, etc)
-    "jquery"        : false,    // jQuery
+    "node"          : true      // Node.js
 
-    // Custom Globals
-    "globals"       : {         // additional predefined global variables
-        "define"    : "false",
-        "JS"        : "false",
-        "emojify"   : "false"
-    }
 }

CONTRIBUTING.md

@@ -1,30 +1,39 @@
 Contributing
 ===
 
+This project follows [Git-Flow](http://nvie.com/posts/a-successful-git-branching-model/), and as such has ``master`` and ``develop`` branches.
+
 ## Prerequisites
 
-1. Install the appropriate [EditorConfig](http://editorconfig.org) plugin for your IDE / editor. This helps keep the code style consistent.
+1. Install the appropriate [EditorConfig](http://editorconfig.org) plugin for your IDE/editor. This helps keep the code style consistent.
 2. Install [PhantomJS](http://phantomjs.org). Make sure it's on your path / available when calling `phantomjs` from the command line.
 2. `npm install -g grunt-cli`
 3. `npm install`
 
 ## Running the tests
 
 - All tests: `npm test`
-- Just the browser ones: `phantomjs phantom.js`
+- Just the browser ones: `phantomjs tests/phantom.js`
 - Just the Node ones: `grunt test-node`
 
-## Before creating the pull-request
+## Before creating a pull request
 
 Make sure you do the following:
 
 - Run `grunt`
 
 Note: The build script will generate new `*.min.{css,js}` files. If, for example, you only changed the JavaScript then don't bother committing `emojify.min.css`.
 
-## Publishing
+## Releasing & Publishing
+
+Before a release, generate a commit log:
+
+```
+git log --pretty=format:"- %s" >> log.md
+```
 
 If you have rights to publish to npm, do the following first:
 
-- Run `update.sh`. This will update the project with the latest emoji from [emoji-cheat-sheet.com](http://www.emoji-cheat-sheet.com). 
-- Run `grunt`
+- Run `update.sh`. This will update the project with the latest emoji from [emoji-cheat-sheet.com](http://www.emoji-cheat-sheet.com).
+- Run `grunt`
+- Run `npm publish`

Gruntfile.js

@@ -10,7 +10,10 @@ module.exports = function (grunt) {
             ' */'
         },
         jshint : {
-            files        : ['emojify.js']
+            files: [ 'emojify.js' ],
+            options: {
+                jshintrc: '.jshintrc'
+            }
         },
         uglify : {
             options : {

README.md

@@ -1,75 +1,133 @@
-#emojify.js v0.9.4
+# emojify.js
 
-[![Master branch build status][ico-build]][travis]
-[![NPM version][ico-npm]][package-npm]
+[![npm version][ico-npm]][package-npm]
 [![Bower version][ico-bower]][package-bower]
 [![MIT Licensed][ico-license]][license]
 [![Gitter chat][ico-gitter]][gitter]
 
-==========
+---
+
+Master | Develop
+--- | ---
+[![Master branch build status][ico-build]][travis] | [![Develop branch build status][ico-build-dev]][travis]
 
 [![Browser Results](https://ci.testling.com/hassankhan/emojify.js.png)](https://ci.testling.com/hassankhan/emojify.js)
 
-A Javascript module to convert emoji keywords to images. Used by [Gitter](https://gitter.im/)
+A swiss-army-knife for all emoji, in Javascript. Used by [Gitter](https://gitter.im/)
 
 The emoji keywords are as described by [emoji-cheat-sheet.com](http://www.emoji-cheat-sheet.com).
 
-Go to this project's [GitHub pages](http://hassankhan.github.com/emojify.js) to see the module in action.
+Go to this project's [GitHub pages](http://hassankhan.github.com/emojify.js) to see the code in action.
+
+## Features
+
+- Fast
+- Awesome
+- Made from unicorn blood
+- Available on a CDN **(gasp)**
+- Converts emoticons like `:) :( :'(`
+- Allows customisation of processed emoji
+- Includes a [sample `.htaccess` file](.htaccess) for caching Javascript and CSS
+- Switchable emoji sets **(SOON!)**
+
+## Installation
+
+### Via cdnjs **[SOON]**
+
+Add this to the rest of your stylesheet imports:
+Then add this to your Javascript code:
+
+### Via Bower
+
+`bower install emojify.js#~1.0 --save`
+
+### Via npm
+
+`npm install emojify.js#~1.0  --save`
+
+## API
+
+### setConfig([object])
+
+*This works in the browser and on Node*
+
+#### Parameters
+- `object` - Optional JSON object with any of the following attributes:
+
+Option | Default | Description
+--- | --- | ---
+`emojify_tag_type` | `null` | When set, emojify uses this element with the class `emoji emoji-#{emojiname}` instead of an `img` with a `src` attribute.  Example valid values: `div`, `span`
+`only_crawl_id` | `null` | Restricts searching for emojis to a specified element & it's children. If null, and no object is passed to `run()`, `document.body` is used
+`img_dir` | `'images/emoji'` | Defines the path to the emoji images
+`ignore_emoticons` | `false` | If `true`, only convert emoji like `:smile:` and ignore emoticons like `:)`
+`ignored_tags` | `{'SCRIPT': 1,'TEXTAREA': 1,'A': 1,'PRE': 1,'CODE': 1}` | A list of elements that you don't want emojified
+
+#### Usage
+```js
+emojify.setConfig({emojify_tag_type : 'div'});
+```
+
+---
+
+### run([element])
+
+*This only works in the browser*
+
+#### Parameters
+- `element` - Optional HTML element to restrict the emojification to.
+
+#### Usage
+```js
+emojify.run();
+// OR
+emojify.run(document.getElementById('my-element'))
+```
+
+---
+
+### replace(string, [callback])
 
+*This works in the browser and on Node*
 
-## Rationale
-I wanted [my blog](http://hassankhan.me) to display smileys nicely, decided to use Emojis because they look nice. [GitterHQ](https://github.com/gitterHQ) wanted to use it in [Gitter](https://gitter.im/), so they very kindly rewrote it and here we are.
+#### Parameters
+- `string` - String to emojify
+- `callback` - Optional callback function to output emoji with
 
+#### Usage
 
-## Usage
-Add the following line to your HTML:
+By default, emojify.js uses the internal function `defaultReplacer()` to replace emoji. You can override this behaviour by supplying your own callback function.
 
-    <script src="emojify.js"></script>
+Your callback function will receive two parameters, the emoji pattern found (`emoji`), and the emoji name (`name`). In the case of emoticons, for example, `emoji = ':)'` and `name = 'smile'`.
 
-Now type in an emoji keyword in your HTML, for example ``:smile:``
-Now run emojify using ``emojify.run()``.
-To exclude tags from being emojified, add ``no-emojify`` to their ``class`` attributes.
+The context in which your replacer function is run will have the config available. So you can access properties such as `img_dir` at `this.config.img_dir`.
 
-You can optionally pass an object to ``emojify.run()`` to restrict the **emojification** to that object only: ``emojify.run(document.getElementById('my-element'))``
+```js
+emojify.replace('I am happy :)');
+// OR
+replacer = function(emoji, name) {
+    // Customise output here
+    return emojifiedString;
+}
 
-You can also use ``emojify.replace()`` method to emojify a string directly:
+emojify.replace('I am happy :)', replacer);
+```
 
-### Configuration
-To set configuration options, use `emojify.setConfig()` and a JSON object as a parameter with the following attributes:
-* ``emojify_tag_type``: Set to `null` by default. When set, emojify uses this `emojify_tag_type` element with the class `emoji emoji-#{emojiname}` instead of an `img` with a `src` attribute.  Example valid values: `div`, `span`
-* ``only_crawl_id``: Set to `null` by default. Restricts searching for emojis to a specified element & it's children. If null, and no object is passed to ``run()``, `document.body` is used.
-* ``img_dir`` defines the path to the emoji images.
-* ``ignore_emoticons`` Set to `false` by default. If `true`, only convert :emoji: and ignore emoticons like :-) and ;D.
-* ``ignored_tags`` should be a list of elements that you don't want emojified.
+### Excluding elements from being processed
 
-### Code Example
+To exclude tags from being emojified, add `no-emojify` to their `class` attributes.
 
-    emojify.setConfig({
-        emojify_tag_type : 'div',           // Only run emojify.js on this element
-        only_crawl_id    : null,            // Use to restrict where emojify.js applies
-        img_dir          : 'images/emoji',  // Directory for emoji images
-        ignore_emoticons : false            // If true, only convert :emoji: and ignore :-)
-        ignored_tags     : {                // Ignore the following tags
-            'SCRIPT'  : 1,
-            'TEXTAREA': 1,
-            'A'       : 1,
-            'PRE'     : 1,
-            'CODE'    : 1
-        }
-    });
-    emojify.run();
-
-## Contributing
+## Contributing changes
 
-See our [CONTRIBUTING.md](CONTRIBUTING.md).
+Please read [CONTRIBUTING.md](CONTRIBUTING.md).
 
 [travis]: https://travis-ci.org/hassankhan/emojify.js
 [package-bower]: http://bower.io/search/?q=emojify.js
 [package-npm]: https://www.npmjs.org/package/emojify.js
-[ico-build]: http://img.shields.io/travis/hassankhan/emojify.js.svg?style=flat
-[ico-bower]: http://img.shields.io/badge/bower-0.9.4-blue.svg?style=flat
-[ico-npm]: http://img.shields.io/npm/v/emojify.js.svg?style=flat
-[ico-license]: http://img.shields.io/npm/l/emojify.js.svg?style=flat
+[ico-build]: http://img.shields.io/travis/hassankhan/emojify.js.svg?style=flat-square
+[ico-build-dev]: http://img.shields.io/travis/hassankhan/emojify.js/develop.svg?style=flat-square
+[ico-bower]: http://img.shields.io/badge/bower-0.9.4-blue.svg?style=flat-square
+[ico-npm]: http://img.shields.io/npm/v/emojify.js.svg?style=flat-square
+[ico-license]: http://img.shields.io/npm/l/emojify.js.svg?style=flat-square
 [ico-gitter]: https://badges.gitter.im/hassankhan/emojify.js.png
 [license]: http://hassankhan.mit-license.org/
-[gitter]: https://gitter.im/hassankhan/emojify.js
+[gitter]: https://gitter.im/hassankhan/emojify.js

bower.json

@@ -1,7 +1,7 @@
 {
   "name": "emojify.js",
   "main": "emojify.js",
-  "version": "0.9.2",
+  "version": "0.9.5",
   "homepage": "https://github.com/hassankhan/emojify.js",
   "authors": [
     "Hassan Khan (hassankhan)"
@@ -14,9 +14,6 @@
   "ignore": [
     "**/.*",
     "node_modules",
-    "bower_components",
-    "/vendor/",
-    "test",
     "tests"
   ]
 }