From 89e182038140f10a8b61c0aa2da7927a1c1e8e16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20P=C3=A9ters?= <fpeters@entrouvert.com>
Date: Thu, 4 Sep 2014 10:50:53 +0200
Subject: [PATCH] README: add general description and documentation

---
 README.txt | 52 ++++++++++++++++++++++++++++++++++++++++++++++------
 setup.py   |  2 +-
 2 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/README.txt b/README.txt
index d06601d..e349c3e 100644
--- a/README.txt
+++ b/README.txt
@@ -1,5 +1,18 @@
-Configuration
-=============
+=====
+Gadjo
+=====
+
+Gadjo is a base template for Django applications, tailored for
+management interfaces, built to provide a nice and modern look, while
+using progressive enhancement and responsive designs to adapt to
+different environments.
+
+
+Usage
+=====
+
+Make your application base template {% extends "gadjo/base.html" %}.
+
 
 You should add gadjo.finders.XStaticFinder to STATICFILES_FINDERS,
 
@@ -14,13 +27,40 @@ tuples; for example:
   CDNS = [('google', 'https')]
 
 
-Usage
-=====
-
-Make your application base template {% extends "gadjo/base.html" %}.
+Additional static files
+------------------------
 
 Additional static files libraries can be added via INSTALLED_APPS,
 for example 'xstatic.pkg.jquery_tablesorter'; its static files can
 then be referred in a template using the xstatic template tag:
 
   {% xstatic 'jquery_tablesorter' 'jquery.tablesorter.js' %}
+
+
+Progressive enhancement -- Dialogs
+----------------------------------
+
+Links marked with rel="popup" will be opened into dialog boxes.
+
+The dialog title is extracted from "#appbar h2" (this selector can be
+changed with a @data-title-selector attribute on the anchor tag).
+
+The dialog content is extracted from "form" (this selector can be
+changed with a @data-selector attribute).
+
+Buttons (both <button> and <a>) are extracted from the content and
+converted into proper dialog buttons.  A button with "cancel" as its
+class will have its action changed to simply close the dialog, without
+server processing.
+
+After loading the dialog content, a gadjo:dialog-loaded event is
+triggered on the anchor with the dialog content as argument.
+
+Alternatively the server may notice the ajax request and answer with
+an appropriate JSON response. In that case it should have a 'content'
+attribute with the HTML content, or a 'location' attribute in case of
+a redirect.
+
+In case of such a redirect, a gadjo:dialog-done event is triggered on
+the anchor and can be cancelled to prevent the default redirect
+behaviour.
diff --git a/setup.py b/setup.py
index e91ee08..cac46ba 100644
--- a/setup.py
+++ b/setup.py
@@ -53,7 +53,7 @@ def get_version():
 setup(
     name='gadjo',
     version=get_version(),
-    description='Base templates for management interfaces',
+    description='Django base template tailored for management interfaces',
     author='Frederic Peters',
     author_email='fpeters@entrouvert.com',
     packages=find_packages(),
-- 
2.1.0