Ray's Widget Exchange
=====================

Ray's Widget Exchange is a project exploring the client-side of Django
website development. The intention is to provide tools, widgets, views
and other services that aren't appropriate for the Django core, but are
still essential for website development.

Initial goals:

We aim to provide a simple set of widgets that can be easily integrated into a
Django form:

* A calendar widget

* A numerical range widget

* A time widget

* An AJAX autocomplete widget

* A color palette

  - full RGB selection

  - selection from subset of colors


Longer term goals:

* Handle compression and aggregation of CSS and JavaScript artefacts. (Note by
  Reinout: probably not, as an app should do only one thing:
  compression/aggregation can be done by other apps).

* Client-side input validation (possibly by Ajax callback?)


Installation
------------

Ray's widget exchange depends on `django-staticfiles
<http://pypi.python.org/pypi/django-staticfiles>`_ as that's the best way at
the moment to handle css and javascript files.  It is also, probably, going to
end up in one form or the other in Django 1.3.

- django-rays' ``setup.py`` has an automatic dependency on django-staticfiles,
  so installing django-rays automatically brings in django-staticfiles.

- Add both ``rays`` and ``staticfiles`` to your settings file's
  ``INSTALLED_APPS``.

Django-staticfiles needs a bit of boilerplate. Django 1.3 ought to make this
unnecessary, btw.  The `official django-staticfiles documentation
<http://pypi.python.org/pypi/django-staticfiles>`_ has more elaborate
information and there's also a `blog post
<http://reinout.vanrees.org/weblog/2010/05/19/django-css-javascript-files.html>`_
with a more narrative explanation and example snippets.

- In sites where you use django-rays, you will need to add a little bit of
  django-staticfiles boiler plate code to your settings file ::

    # Used for django-staticfiles
    STATIC_URL = '/static_media/'
    TEMPLATE_CONTEXT_PROCESSORS = (
        # Default items.
        "django.core.context_processors.auth",
        "django.core.context_processors.debug",
        "django.core.context_processors.i18n",
        "django.core.context_processors.media",
        # Needs to be added for django-staticfiles to allow you to use
        # {{ STATIC_URL }}myapp/my.css in your templates.
        'staticfiles.context_processors.static_url',
        )

- And in your urlconf, add something like this to the end of your
  ``urls.py``::

    if settings.DEBUG:
        # Add this also to the projects that use this application.
        # It allows django-staticfiles to serve up the /media files
        # in DEBUG mode.
        urlpatterns += patterns('',
            (r'', include('staticfiles.urls')),
        )

- In production, use the ``build_static`` management command to prepare all
  static files for apache.


The css/js inclusion is happening by using `Django's form media handling
<http://docs.djangoproject.com/en/1.2/topics/forms/media/>`_.  So don't forget
to add your equivalent of::

    {{ form.media }}

somewhere in the head of your templates.


Development
-----------

The source code is `on bitbucket
<http://bitbucket.org/freakboy3742/django-rays>`_.  The `bug tracker
<http://bitbucket.org/freakboy3742/django-rays/issues?status=new&status=open>`_
is also there.

For developers that want to use buildout, a small ``buildout.cfg`` that sets
up a development and testing environment is provided.  Otherwise use your
regular virtualenv/pip setup, of course.

Run ``python bootstrap.py`` and ``bin/buildout`` to initialize the buildout
environment and to fetch all dependencies.  Now you can check run tests with
``bin/test``.
You can setup a simple example project with ``bin/django syncdb``.  Now run
``bin/django runserver`` to start the development server and point your
browser to ``http://localhost:8000/``.
