Commit 180e4085 authored by Alan Trick's avatar Alan Trick

Add documentation for query fields and registrations

parent f0067763
Pipeline #37460912 passed with stage
in 1 minute and 33 seconds
......@@ -16,26 +16,81 @@ Features
``Registration`` subclass.
* Nice JavaScript charts with c3, falls back to a plain table without
JavaScript.
* Add filters & group data by setting query parameters on the criteria
Limitations
-----------
* One dimension/axis of the chart is always the date. There's no way to
specify a chart that isn’t “by date”.
* There’s no way to add filters to criteria on charts. The recommended
workaround is to use trackstats and store those stats separately.
Installation
------------
Installation is straightforward. Install ``django-adminstats`` with pip, and
then add ``'django_adminstats',`` to your ``INSTALLED_APPS`` setting. You’ll
also want to register some models or trackstat metrics (see Example Code).
then add ``'django_adminstats',`` to your ``INSTALLED_APPS`` setting.
Example Code
------------
Registering Statistics
----------------------
In order to do anything, you'll need register some models or trackstats
metrics. You can find examples of this in ``tests/models.py``, but the short
of it looks like this:
.. code-block:: python
from django_adminstats.registry import register_model
class Currency(models.Model):
slug = models.CharField(max_length=10)
name = models.CharField(max_length=100)
current_usd_rate = models.DecimalField()
sign = models.CharField(max_length=10, default='$')
class Transaction(models.Model):
amount = models.DecimalField()
currency = models.Foreignkey(to=Currency)
date = models.DateTimeField(auto_now_add=True)
django_adminstats.register_model(Transaction)
By default, we look for a field called ‘date’ on the model, and it should be
either a ``DateField`` or ``DateTimeField``. If you want to use a different,
field (for example if you’re using Django’s default user and you want to chart
by ‘joined_at’) you need to create a registration subclass.
.. code-block:: python
from django_adminstats.registry import registry, register
class UserRegistration(ModelRegistration):
date_field = 'joined_at'
register(UserRegistration())
Creating Charts
---------------
You can add charts in the admin. In order for the chart to show anything, you
need to add criteria. By default, it will just show a count of all the items
charted by the date field, if you to change this, you need to add things in
the filter spec, axis spec, and group spec fields.
First The content of these fields is formatted like a URL querystring,
for example a filter spec of ``message=Hello%20World&x=y`` is equivalent to
``.filter(message='Hello World', x='y')``. Note that you only use the
``key0=value0&key1=value1`` form in the filter spec, the axis and group
specs are just ``key0&key2``.
Second, you can use lookups and relations just like in a normal django
query (e.g. ``field__gt=2`` or ``field__related_field``).
Finally, you can also specify functions to use on the field by doing
``field:function``. For example ``id:count`` is the default axis spec when
the field is left blank.
See ``tests/models.py``.
Demo
----
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment