Metadata-Version: 1.0
Name: django-trackable
Version: 0.1.2
Summary: Provides infrastructure to easily implement functionality that captures arbitrary tracking data out-of-band.
Home-page: http://github.com/yorkedork/django-trackable/tree/master
Author: Thom Linton
Author-email: thom.linton@gmail.com
License: BSD
Description: ================
        django-trackable
        ================
        
        ``Django-trackable`` attempts to be a reusable Django application that provides
        infrastructure to easily implement the functionality required to capture
        arbitrary tracking data out-of-band. This documentation assumes a basic 
        familiarity with `Django`_ and the `Celery`_ package. For usage and installation 
        instructions, please review the documentation.
        
        
        Defining tracking datasets
        --------------------------
        
        For developers already accustomed to Django, ``Django-trackable`` employs an 
        interface identical to ``django.contrib.admin``. It provides basic scaffolding
        with which to construct more complex tracking datasets; for example, time-series 
        data is supported out-of-the-box. To construct your own tracking dataset models 
        simple define your object, providing the proper incantations::
        
            from django.contrib import admin
            from my_app.models import MyObject
            import trackable
        
            class MyObjectTrackableData(trackable.TrackableTimeSeriesData):
                impressions = models.PositiveIntegerField(default=0)
                click_throughs = models.PositiveIntegerField(default=0)
        
                class Meta(trackable.TrackableTimeSeriesData.Meta):
                    app_label = 'my_app'
                    verbose_name_plural = _('My object trackable data')
        
        Similar to ``django.contrib.admin``, you must register your models::
        
            trackable.site.register(MyObject, MyObjectTrackableData)
        
        For convenience, you can supply your own ``ModelAdmin`` class in the same call::
        
            class MyObjectTrackableDataAdmin(admin.ModelAdmin):
                list_display = ('parent','collected_during', 'impressions','click_throughs',)
        
            trackable.site.register(MyObject, MyObjectTrackableData, MyObjectTrackableDataAdmin)
        
        Please note that for convenience, ``Django-trackable`` will only actually register the 
        ``ModelAdmin`` class when ``DEBUG`` is set; in other words, it's unlikely of much use 
        unless you are debugging your application.
        
        Emitting tracking events
        ------------------------
        
        In order to interact with these datasets, you'll need broadcast builtin or user-defined 
        messages (events) when encountering an event of interest within a, e.g., a view. For more 
        information on extending ``Django-trackable`` by defining your own messages please consult 
        the documentation.
        
        Continuing the previous example::
        
            from django.shortcuts import get_object_or_404
            from django import http
            from my_app.models import MyObject
            from trackable.messaging import send_increment_message
        
            def someone_looked_at_my_object( request, slug ):
                my_object = get_object_or_404(MyObject, slug=slug)
        	send_increment_message(request,my_object,'impressions')
        	return http.HttpResponse("My object, how does it work?",status=418)
        
        Notice that you pass the object to which the tracking data will be attached as well as 
        the field you wish to signal (in this case, the ``impressions`` field on 
        ``MyObjectTrackingData``).
        
        Collecting tracking data
        ------------------------
        
        In order to collect and process these events, you may utilize the utility 
        ``trackable.messaging.process_messages'. As a convenience, a Django-celery task has been 
        provided (``trackable.tasks.CollectTrackingData``) and is enabled by default. To adjust 
        the collection period::
        
            # in your django settings
            TRACKABLE_COLLECTION_PERIOD = N seconds [1800]
        
        To disable the collection task completely::
        
            TRACKABLE_DISABLE_COLLECTION_TASK = True [False]
        
        Alternatively, you may trigger this function from the builtin Django shell by using the 
        management command ``fold_trackable_messages``. 
        
        To enable the capture of connection errors (when connecting to the messaging broker) to avoid 
        e.g., HTTP 500::
        
            TRACKABLE_CAPTURE_CONNECTION_ERRORS = True [False]
        
        Any exception caught while this configuration setting is enabled with be emailed to the 
        addresses listed in ``ADMINS``.
        
        For convenience, a tracking data migration command is provided; your mileage may vary::
        
            ./manage.py convert_tracking_data --help
        
        Some nonzero interval of time -- varying on the developer in question -- you might manage 
        to create 'malformed' messages for a variety of reasons; to prevent the collection tasks 
        from continually revisiting the same broken messages::
        
             TRACKABLE_REMOVE_MALFORMED_MESSAGES = True [False]
        
        ``Django-trackable`` includes an optional, primitive spider-filtering mechanism that is 
        disabled by default. To enable it::
        
            TRACKABLE_USER_AGENT_FILTERTING = True [False]
        
        A poorly-fashioned dataset of spiders is provided as a fixture which you are welcome to 
        use with the knowledge that you'll likely need to craft a means of generating your own.
        
        
        .. _Django: http://djangoproject.org
        .. _Celery: http://celeryproject.org
        
Keywords: django tracking
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: BSD License
