Welcome to Dolphin's documentation!
***********************************

Dolphin is a feature flagging library for django that also doubles as
an A/B library and geoip based switch. It was heavily inspired by
Gargoyle (https://github.com/disqus/gargoyle).


Features
========

* Basic GeoIP location detection using django's GIS library

* Random A/B testing

* Limits on A/B testing

* Custom flag options

* Limit to or exclude for certain sites

* Set cookies and expiration time so that flag results can be stored in users browsers.

* Expiration warning to notify users that flag has expired.  When the flag expires, you'll see the date in a red font on the change list page.

* Roll out mode - Enable feature gradually to a percentage of users with a percentage slider.

Usage
*****


Python
======

There are multiple ways to use dolphin. The first is with a basic if
statement:

   from dolphin import flipper
   if flipper.is_active("flag_name"):
       do_something()
   else:
       do_something_else

There is also a decorator that allows redirects, other view functions
to be called, or just a 404 by default:

   @flipper.switch_is_active("flag_name")
   def view(request):
       return ...

   @flipper.switch_is_active("flag_name", redirect="/")
   def view2(request):
       return ...

   @flipper.switch_is_active("flag_name", alt=view1)
   def view3(request):
       return ...


Template
========

In a template:

   {% load dolphin_tags %}
   {% ifactive "flag_name" %}
   Active
   {% else %}
   Not active
   {% endifactive %}

There's also a template tag that will list active flags as a comma
delimited list:

   {% active_flags %}


Javascript
==========

For usage in javascript, there are a couple of convenience functions
in dolphin.views that can be added to your urls.py. As an example:

   url(r'^dolphin/js/$', 'dolphin.views.js'),
   url(r'^dolphin/json/$', 'dolphin.views.json'),

The js view provides a flipper object which has a function is_active
that may be used like the python is_active function:

   <script type="text/javascript" src="/dolphin/js/">
   <script type="text/javascript">
       if ( flipper.is_active("flag_name") ) {
           ...
       }
       else {
           ...
       }
   </script>

The flipper object also has the active flags in an array called
flipper.active_flags.

The json function returns a structure as follows:

   {"active_flags": ["enabled", "ab_random", "max"]}

All processing is done in python with the javascript views. If any
frontend caching would cache this view, you may want to add never
cache if you're utilizing geolocation, random, max, or date based
flags.

Custom Tests
************

Dolphin can also support custom tests. They are simply functions by
the form of:

   def test_func(key, **kwargs):
       return True or False

kwargs will contain the backend which can be used to get the request
object if necessary (though depending on how the test is called, it
may be passed as a keyword argument).

Setup
*****

1. Install geoposition if necessary (pip install django-geoposition)

2. Add "dolphin.middleware.LocalStoreMiddleware" to your
   MIDDLEWARE_CLASSES. This allows per-request random testing and per-
   request caching.

3. Add "dolphin" and "geoposition" to INSTALLED_APPS

4. Ensure that REMOTE_ADDR is pointing to the correct IP address. If
   not, you will have to otherwise patch dolphin.utils.get_ip to use
   geoip.

5. Load database table using manage.py, either via syncdb or migrate
   dolphin if using south.

6. If you wish to use geoip based flags, your GEOIP_PATH and GIS
   library must be set up correctly.

7. If you wish to use the javascript options, add dolphin.views.js and
   dolphin.views.json to your urls.py.

8. If you wish to use the dolphin test page, add
   dolphin.views.dolphin_test to your views and enable the flag either
   from your settings.DOLPHIN_TEST_FLAG or "dolphin_test".

Settings
********


Functionality Options
=====================

DOLPHIN_USE_GIS
   Boolean (Default True). Use geolocation based flags. True enables
   this, False disables the option in the admin.

DOLPHIN_LIMIT_TO_SESSION
   Boolean (Default True). Limits a/b switching (max/current views and
   random) to the session of the user. This prevents the same user
   from seeing different flags on the site.

DOLPHIN_STORE_FLAGS
   Boolean (Default True). Store flag results for the entire request
   without recalculating them. Can speed up flag calculation

DOLPHIN_CACHE
   Boolean (Default True). Cache the get() queries in the django cache
   backend with prefix of dolphin

DOLPHIN_AUTOCREATE_MISSING
   Boolean (Default False). Create settings that are missing but used
   with is_active with enabled=False.

DOLPHIN_TEST_FLAG
   String (Default "dolphin_test"). The name of the flag for the
   dolphin_test url to return a valid page rather than a 404.


Backend Options
===============

DOLPHIN_BACKEND
   A dictionary that sets the backend options. The default is to use
   the DjangoBackend.

Default:

   {
       'BACKEND': 'dolphin.backends.djbackend.DjangoBackend'
       #The backend to use. should inherit from dolphin.backends.base.Backend
       #Builtin options are dolphin.backends.djbackend.DjangoBackend and
       #dolphin.backends.redisbackend.RedisBackend
   }

Redis Backend Defaults (must specify the BACKEND as RedisBackend):

   {
       'BACKEND': 'dolphin.backends.redisbackend.RedisBackend', #the backend
       'DATABASE': 0, #the redis database to use
       'HOST' :'localhost', #the hostname to connect to
       'PORT': 6397, #the port to connect to
       'REDISENGINE': 'dolphin.backends.redisbackend.DefaultRedisEngine',
                      #the redis engine to use, subclass of redis.Redis.
                      #The default has a connection pool to connec to
                      #HOST and PORT.
       'TESTDB': 'featureflag_test'
   }