src/qbe/README.rst

   1 Django Query by Example (QBE)
   2 =============================
   3
   4 :synopsis: Admin tool in order to get custom reports.
   5
   6 The objective of django-qbe is provide a assited and interactive way of making
   7 complex queries with no technical knowledge (or minimal) to get custom reports
   8 from the objects of Django models.
   9
  10 Based on QBE_ proposal from IBM®, django-qbe is intended to remove the
  11 limitations of Django QuerySets objects and to use the whole expresive power of
  12 the subjacent SQL.
  13
  14
  15 Installation
  16 ------------
  17
  18 Using the Python Package Index (PyPI_) and easy_install script::
  19
  20   $ easy_install django_qbe
  21
  22 Or through pip::
  23
  24   $ pip install django_qbe
  25
  26 But you also can download the *django_qbe* directory using git::
  27
  28   $ git clone git://github.com/versae/qbe.git
  29   $ cp -r qbe/django_qbe /path/to/your/project
  30
  31 Adding to the project settings::
  32
  33   INSTALLED_APPS = (
  34       # [...] django builtins applications
  35       'django_qbe',
  36       # [...] Any other application
  37   )
  38
  39 And adding the urlconf in your project urls.py::
  40
  41     # qbe
  42     url(r'^qbe/', include('django_qbe.urls')),
  43
  44 If you are using Django 1.2 or any previous version you must link or copy the
  45 *django_qbe/static/django_qbe* directory in your project media directory::
  46
  47   $ ln -s django_qbe/static/django_qbe /path/to/your/project/media/
  48
  49 And enable the context processor *django.core.context_processors.media*::
  50
  51   TEMPLATE_CONTEXT_PROCESSORS = (
  52       # [...] django context processors
  53       'django.core.context_processors.media',
  54       # [...] Any other context processors
  55   )
  56
  57 But if you're using Django 1.3 or later the static files will be found and served
  58 automatically, you don't need to do anything except adding the context processor
  59 *django.core.context_processors.static*::
  60
  61   TEMPLATE_CONTEXT_PROCESSORS = (
  62       # [...] django context processors
  63       'django.core.context_processors.static',
  64       # [...] Any other context processors
  65   )
  66
  67 See the `Django documentation on static files`__ for details.
  68
  69 __ staticfiles_
  70
  71 That's all. Then you can access to http://host:port/qbe
  72 However, you can add a link from your admin page changing the admin index
  73 template fo your AdminSite::
  74
  75   class AdminSite(admin.AdminSite):
  76       index_template = "qbe_index.html"
  77
  78 Or adding in your custom admin index template the next javascript::
  79
  80   <script type="text/javascript" src="{% url qbe_js %}"></script>
  81
  82
  83 Settings
  84 --------
  85
  86 The next lines show de available settings and its default values.
  87
  88 Enable autocompletion tool (work in progress, not enabled yet)::
  89
  90   QBE_AUTOCOMPLETE = True
  91
  92 Enable an Exhibit faceted navigation for results (not yet implemented)::
  93
  94   QBE_EXHIBIT = False
  95
  96 Admin module name to add admin urls in results::
  97
  98   QBE_ADMIN = "admin"
  99
 100 Set your own admin site if it's different to usual *django.contrib.admin.site*::
 101
 102   QBE_ADMIN_SITE ="admin.admin_site"
 103
 104 Function to control to users with access to QBE::
 105
 106   QBE_ACCESS_FOR = lambda user: user.is_staff
 107
 108 Path to QBE formats export file, in order to add custom export formats::
 109
 110   QBE_FORMATS_EXPORT = "qbe_formats"
 111
 112
 113 .. _QBE: http://www.google.com/url?sa=t&source=web&ct=res&cd=2&ved=0CB4QFjAB&url=http%3A%2F%2Fpages.cs.wisc.edu%2F~dbbook%2FopenAccess%2FthirdEdition%2Fqbe.pdf&ei=_UD5S5WSBYP5-Qb-18i8CA&usg=AFQjCNHMv-Pua285zhWT8DevuZFj2gfYKA&sig2=-sTEDWjJhnTaixh2iJfsAw
 114 .. _PyPI: http://pypi.python.org/pypi/django_qbe/
 115 .. _staticfiles: http://docs.djangoproject.com/en/dev/howto/static-files