From 65062de2bd37f7bf4b140e9b8135091764fdf4a6 Mon Sep 17 00:00:00 2001 From: Tom S Date: Wed, 21 Nov 2012 12:43:07 +0000 Subject: [PATCH] add docs - copied from google code --- README.rst | 19 +++++++++++++ docs/index.rst | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 README.rst create mode 100644 docs/index.rst diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..116af3c --- /dev/null +++ b/README.rst @@ -0,0 +1,19 @@ +###################### +django-jqchat +###################### + +A chat client for `Django `_ using the `jQuery `_ library. + +`Try out the demo `_ + +************* +Extensible +************* + +django-jqchat is designed to work in situations where the +chat window is not the only data to be updated by Ajax +calls. It allows extra data to be piggybacked on the +Ajax payloads; for an example, see +`this demo `_ +where a description field can be updated by the user. + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..05ae188 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,73 @@ +#################### +Dependencies +#################### + +* django-timezones +* pytz (used by django-timezones). + +#################### +Installation +#################### + +These instructions assume you have a Django project set up using `virtualenv +`_ and `pip `_ + +install:: + + pip install -e git://github.com/tomscytale/django-jqchat.git#egg=django-jqchat + +* add ``jqchat`` and ``timezones`` to the project's list of applications. +* include jqchat's ``urls.py`` to your main ``urls.py`` file. +* run a ``syncdb`` to add new tables. + +test it. By default the urls.py file supplied adds 2 types of chat +test rooms, you will have to manually create one in the admin before +you can test it. + +#################### +Design philosophy +#################### +Jqchat is built on the assumption that a chat room is an extra feature +on top of an existing object. Hence jqchat is kept very basic and +extensible. + +#################### +Integration +#################### +The easiest way to add a jqchat room to an existing model is to create +a OneToOne field on the existing model. For example:: + + from myapp.models import Room + chat_room = models.OneToOneField(Room, help_text='Chat + room to be used for this lobby.') + +In the jqchat templates folder you will find +chat_test.html; you will have to pull out some code and +add it to your own templates: + +* the header code which initialises the javascript code. +* the chatwindow div and the chatform form. If you decide to rename these elements, you will have to adjust the javascript code accordingly. + +This should be enough to use the supplied chat client; to extend it, please see below. + +There's no chat room members list? +=================================== + +No, not at present; as stated above, jqchat is designed +to be an extension to an existing object. +Patches with a neat and generic way of adding +this to jqchat are welcome + + +#################### +Extending jqchat +#################### +The big feature of jqchat is that it can be extended to +piggyback extra information in the Ajax payloads. +Within the source is an example of +using this to add and change descriptions for the chat +rooms. Things to look at are: + +* template chat_test_with_desc.html: note how the call to the javascript includes a different url for handling the AJAX calls. +* views.py: the normal handler for the Ajax calls has been overridden. The view WindowWithDescriptionAjaxHandler is an instance of the view class DescriptionAjax. This class has its own custom handler - 'ExtraHandling' - that knows what to do with custom actions from the client, and also knows what extra fields to pass back. + -- 2.39.5