diff --git a/README.md b/README.md index 6100887..1c2aa5a 100644 --- a/README.md +++ b/README.md @@ -24,28 +24,8 @@ python manage.py migrate django_fsm_log ``` ## Usage -The behaviour of this app changes slightly depending on whether you have set a -cache backend in your project's settings.py file - -#### With cache backend enabled -The app will listen for `django_fsm.signals.pre_transition` to be fired and -create a pending state log cache object for this transition. - -If you need to immediately access this StateLog object, and do not care if -it has been persisted to the database, you can do -```python -from django_fsm_log.models import StateLog -from django.core.cache import cache -cache_key = StateLog.get_pending_cache_key_for_object(yourobject) -pending_statelog = cache.get(cache_key) -``` - -When `django_fsm.signals.post_transition` is fired, the pending StateLog is persisted -to the database, and its cache item is deleted - -#### Without cache backend enabled -StateLog records are written to the database only after -`django_fsm.signals.post_transition` is fired +The app will listen for `django_fsm.signals.post_transition` to be fired and +create a new record for each transition. To query logs simply ```python @@ -94,6 +74,26 @@ article = Article.objects.create() article.submit(by=some_user) # StateLog.by will be some_user ``` + +### Advanced Usage +You can change the behaviour of this app by turning on caching for StateLog records. +Simply add `DJANGO_FSM_LOG_USE_CACHE = True` to your project's settings file. By +default your project's `'default'` cache backend will be used to store this data. If you wish to +use a different cache backend, add `DJANGO_FSM_LOG_CACHE_BACKEND = 'custom_backend'` to your settings file. + +When caching is on, you can access the StateLog record before the transition takes place, +and before it has been persisted to the database. + +```python +from django_fsm_log.models import StateLog +article = Article.objects.get(...) +pending_state_log = StateLog.objects.get_pending_for_object(article) +``` + +This pending StateLog object is available after the `django_fsm.signals.pre_transition` +signal is fired, but is deleted from the cache after `django_fsm.signals.post_transition` +is fired. + ## Running Tests ```