Merge branch 'release/v1.0'

.coveragerc

@@ -1,8 +1,9 @@
 [run]
-source		= emoticons
-omit		= emoticons/tests*
+source          = emoticons
+omit            = emoticons/tests*
+                  emoticons/demo/*
 
 [report]
-exclude_lines	=
+exclude_lines   =
     pragma: no cover
 show_missing    = True

MANIFEST.in

@@ -0,0 +1,7 @@
+include README.rst
+include LICENSE.txt
+include versions.cfg
+include buildout.cfg
+include bootstrap.py
+recursive-include emoticons *.html
+recursive-include emoticons/static *

README.rst

@@ -5,23 +5,24 @@ django-emoticons |mrgreen|
 |travis-develop| |coverage-develop|
 
 Django-emoticons is a django application providing utilities to add
-*emoticons* in your templates.
+*emoticons* in your templates. Pretty incredible no?
 
 .. contents::
 
 Install
 =======
 
-Install the package in your *PYTHON_PATH* by getting the sources and run
-**setup.py** or use *pip*::
+Once you have installed the package in your *PYTHON_PATH*, register the
+**emoticons** app in your *INSTALLED_APPS* project's section. ::
 
-  $ pip install -e git://github.com/Fantomas42/django-emoticons.git#egg=django-emoticons
+  INSTALLED_APPS = (
+    ...
+    'emoticons',
+    ...
+  )
 
-Then register the **emoticons** app in your *INSTALLED_APPS* project's
-section.
-
-Examples
-========
+Usage
+=====
 
 Filter Usage
 ------------
@@ -31,10 +32,10 @@ a model, this field has this value: ::
 
   Coding is fun and sexy :D
 
-So in our templates we will load the **emoticon_tags** library and use the
+So in our templates we will load the **emoticons_tags** library and use the
 **emoticons** filter: ::
 
-  {% load emoticon_tags %}
+  {% load emoticons_tags %}
 
   {{ object.content|emoticons }}
 
@@ -48,7 +49,7 @@ Tag Usage
 The emoticons app also provides a tag named **emoticons** for converting raw
 text. ::
 
-  {% load emoticon_tags %}
+  {% load emoticons_tags %}
   {% emoticons %}
   Documenting is boring but usefull :p
   {% endemoticons %}
@@ -57,44 +58,40 @@ Which will render :
 
   Documenting is boring but usefull |razz|
 
-So cool, no ?
+Index
+-----
+
+If you want to retrieve a list of all availables emoticons you can use the
+**emoticons_index** tag. ::
+
+  {% load emoticons_tags %}
+  {% emoticons_index as emoticons_list %}
+  {% for emoticons in emoticons_list %}
+  <p>{{ emoticons.0|emoticons }}: {{ emoticons|join:" " }}</p>
+  {% endfor %}
 
 Settings
 ========
 
 You can use differents settings for customizing the application:
 
-* EMOTICONS_URL
+* EMOTICONS_DIRECTORY
 
-  The url where the emoticons files are located, use this as default.::
+  The directory where the emoticons files are located, use ``'emoticons'``
+  as default.
 
-    os.path.join(settings.MEDIA_URL, 'emoticons/'))
-
-* EMOTICONS_CLASS
+* EMOTICONS_LIST
 
-  The class wo will be applied to the *img* markup of the emoticons.
+  The list of the emoticons used by the application, something like this: ::
 
-* EMOTICONS_LIST
+    (('(devil)', 'devil.gif'),
+     ('(angel)', 'angel.gif'),
+     ((':)', ':-)', ':=)', '(smile)'), 'smile.gif'),
+     ((':(', ':-(', ':=(', '(sad)'), 'sadsmile.gif'),
+    )
 
-  The list of the emoticons who will be converted. It's something like that: ::
-
-    ((':)', 'smile.gif'),
-     (':D', 'mrgreen.gif'),
-     (':(', 'sad.gif'),
-     (':|', 'neutral.gif'),
-     (';)', 'wink.gif'),
-     (':p', 'razz.gif'),
-     (':P', 'razz.gif'),
-     (':o', 'surprised.gif'),
-     (':O', 'surprised.gif'),
-     (':s', 'confused.gif'),
-     (':S', 'confused.gif'),
-     (':$', 'confused.gif'),
-     ('o_O', 'eek.gif'),
-     )
-
-Of course the package does not provide the images, is your job to find and
-set them in your project.
+If the HTML code of the emoticons does not fit to your needs, you can
+override the ``'emoticons/emoticon.html'`` template to adjust it.
 
 .. |razz| image:: http://static.fache.fr/img/smileys/razz.gif
 .. |smile| image:: http://static.fache.fr/img/smileys/smile.gif

buildout.cfg

@@ -1,6 +1,7 @@
 [buildout]
 extends                 = versions.cfg
-parts                   = test
+parts                   = demo
+                          test
                           test-and-cover
                           flake8
                           evolution
@@ -10,6 +11,12 @@ eggs                    = django
                           django-emoticons
 show-picked-versions    = true
 
+[demo]
+recipe                  = djangorecipe
+projectegg              = emoticons.demo
+settings                = settings
+eggs                    = ${buildout:eggs}
+
 [test]
 recipe                  = pbp.recipe.noserunner
 eggs                    = nose
@@ -48,4 +55,4 @@ recipe                  = zc.recipe.egg
 eggs                    = python-coveralls
 
 [testenv]
-DJANGO_SETTINGS_MODULE  = emoticons.testsettings
+DJANGO_SETTINGS_MODULE  = emoticons.tests.settings

emoticons/__init__.py

@@ -1,5 +1,5 @@
 """django-emoticons"""
-__version__ = '0.1.1'
+__version__ = '1.0'
 __license__ = 'BSD License'
 
 __author__ = 'Fantomas42'

emoticons/demo/__init__.py

@@ -0,0 +1 @@
+"""Demo of the emoticons app"""

emoticons/demo/demo.html

@@ -0,0 +1,60 @@
+{% load emoticons_tags %}
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="author" content="Fantomas42">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Django-Emoticons</title>
+    <link href="//netdna.bootstrapcdn.com/bootstrap/3.0.1/css/bootstrap.min.css" rel="stylesheet">
+    <style type="text/css">
+      body { background-color: #eee; }
+      .container .row div { background-color: white; }
+    </style>
+  </head>
+  <body>
+    <div class="container">
+      <div class="row">
+        <div class="col-md-6 col-md-offset-3">
+          {% emoticons %}
+          <h1>Django-Emoticons<br />
+            <small>A usefull and incredible Django application that allow
+              you to use <strong>emoticons</strong> in your templates :).</small>
+          </h1>
+          {% endemoticons %}
+          <h2>Index of the emoticons</h2>
+          {% emoticons_index as emoticons_list %}
+          <table class="table table-striped table-bordered table-condensed table-hover">
+            <thead>
+              <tr>
+                <th class="text-center">
+                  Emoticon
+                </th>
+                <th>
+                  Aliases
+                </th>
+              </tr>
+            </thead>
+            <tbody>
+              {% for emoticons in emoticons_list %}
+              <tr>
+                <td class="text-center">
+                  {{ emoticons.0|safe|emoticons }}
+                </td>
+                <td>
+                  {% for emoticon in emoticons %}<code>{{ emoticon }}</code> {% endfor %}
+                </td>
+              </tr>
+              {% endfor %}
+            </tbody>
+          </table>
+          <footer>
+            <p class="text-right">
+              Demo made by <a href="https://github.com/Fantomas42">Fantomas42</a>.
+            </p>
+          </footer>
+        </div>
+      </div>
+    </div>
+  </body>
+</html>

emoticons/demo/settings.py

@@ -0,0 +1,27 @@
+"""Settings for the emoticons demo"""
+import os
+
+PROJECT_ROOT = os.path.abspath(os.path.dirname(__file__))
+
+DEBUG = True
+TEMPLATE_DEBUG = DEBUG
+
+STATIC_URL = '/static/'
+
+SECRET_KEY = 'secret-key'
+
+ROOT_URLCONF = 'emoticons.demo.urls'
+
+TEMPLATE_LOADERS = (
+    'django.template.loaders.filesystem.Loader',
+    'django.template.loaders.app_directories.Loader',
+)
+
+TEMPLATE_DIRS = (
+    PROJECT_ROOT,
+)
+
+INSTALLED_APPS = (
+    'emoticons',
+    'django.contrib.staticfiles'
+)

emoticons/demo/urls.py

@@ -0,0 +1,11 @@
+"""Urls for the emoticons demo"""
+from django.conf.urls import url
+from django.conf.urls import patterns
+from django.views.generic import TemplateView
+
+
+urlpatterns = patterns(
+    '',
+    url(r'^$', TemplateView.as_view(
+        template_name='demo.html')),
+    )