Activity Stream Documentation
==============================

:Authors:
   Justin Quick <justquick@gmail.com>,
   Aaron Williamson,
   Jordan Reiter,
   Manuel Aristaran,
   Darrell Hoy,
   Josh Ourisman,
   Trever Shick
:Version: 0.3


::

    pip install django-activity-stream==0.3.4

Django Activity Stream is a way of creating activities generated by the actions on your site.
Action events are categorized by four main components.

 * ``Actor``. The object that performed the action.
 * ``Verb``. The verb phrase of the action performed.
 * ``Action Object``. *(Optional)* The object linked to the action itself.
 * ``Target``. *(Optional)* The object that the verb is enacted on.
 
``Actor``, ``Action Object`` and ``Target`` are ``GenericForeignKeys`` to any arbitrary Django object.
An action is a description of an action that was performed (``Verb``) at some instant in time by some ``Actor``, with some optional ``Target`` that results in some ``Action Object`` getting created/updated/deleted.

For example: ``<justquick>`` *(actor)* ``<closed>`` *(verb)* ``<issue 1>`` *(object)* on ``<activity-stream>`` *(target)* 12 hours ago

Nomenclature of this specification is based on the `Atom Activity Extension <http://martin.atkins.me.uk/specs/activitystreams/atomactivity>`_


Example Project
================

Download the most recent sourcecode and start up the development server. Make sure you have the most recent version of Django::

    git clone git://github.com/justquick/django-activity-stream.git
    cd django-activity-stream
    python setup.py install # sudo this
    pip install django # and this
    cd example_project
    python manage.py runserver
    
If all goes well it will be available at http://127.0.0.1:8000/. Use the demo login already filled in and try tinkering with the site and following users/groups. Some sample data is provided.
    
To test the activity-stream app, stop the server and run this::

    python manage.py test actstream
    

Install
========

Add ``actstream`` to your ``INSTALLED_APPS``::
    
    INSTALLED_APPS = (
        ...
        'actstream',
        ...
    )
   
Add the activity urls::

    urlpatterns = patterns('',
        ...
        ('^activity/', include('actstream.urls')),
        ...
    )



Generating Actions
===================

Generating actions is probably best done in a separate signal::
    
    from django.db.models.signals import post_save
    from actstream import action
    from myapp.models import MyModel
    
    def my_handler(sender, instance, created, **kwargs):
        action.send(instance, verb='was saved')
    
    post_save.connect(my_handler, sender=MyModel)

To generate an action anywhere in your code, simply import the action signal and send it with your actor, verb, and target::

    from actstream import action
    
    action.send(request.user, verb='reached level 10')
    action.send(request.user, verb='joined', target=group) 
    action.send(request.user, verb='created comment', action_object=comment, target=group) 

Following Actors
=================

Generating the link between a ``User`` and any particular ``Actor`` is as easy as calling a function::

    from actstream.models import follow, unfollow
    
    follow(request.user, group)
   
You can also just make a ``GET`` request to the ``actstream_follow`` view::

    GET /activity/follow/<content_type_id>/<object_id>/?next=/blog/
   
Then the current logged in user will follow the actor defined by ``content_type_id`` & ``object_id``. Optional ``next`` parameter is URL to redirect to.

There is also a function ``actstream.unfollow`` which removes the link and takes the same arguments as ``actstream.follow``

Action Feeds
===============

Listings of actions are available for several points of view. All return a ``QuerySet`` of ``Action`` items sorted by ``-timestamp``::

    from actstream.models import actor_stream, user_stream, model_stream

Actions by a given actor::

    actor_stream(actor)
   
Actions by any given Django ``Model``::

    model_stream(model)
   
Actions from actors that a particular user is folowing::

    user_stream(user)
