Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A generic view- and popularity tracking pluggable for Django.
Python
branch: master

Merge pull request #6 from subsume/master

DATABASE_ENGINE will fail in 1.4, now using DATABASES.
latest commit 029f60aa27
Mathijs de Bruin authored

README.rst

Django Popularity

Generic view- and popularity tracking pluggable for Django

What is it?

The pluggable django-popularity makes it very easy to track the amount of views for objects, and generate (generic) popularity listings based upon that.

Right now it has a measure for view counts, relative view counts, novelty and popularity for ''all'' possible objects.

Status

This app is currently being used in several small-scale production environments. However, it is probably that it still has a few kinks here and there and a fair bit of functionality is still undocumented.

Requirements

Short answer: MySQL >= 4.1.1, Django >= 1.1

Long answer: Currently, this has only been tested for MySQL, thought it might work for Postgres and others as well (though SQLite might make some trouble out of it). If you do manage to get it to work (with or without modifications), please let me know so other users can profit from it as well.

In time, I am planning to migrate most of the functionality to pure-Django QuerySet babble. Sadly enough, the required functionality in the Django API is as of now not yet mature enough.

Installation

  1. Get it from the Cheese Shop:

    easy_install django-popularity
    

    Or get the latest & greatest from Github and link it to your application tree:

    git clone git://github.com/dokterbob/django-popularity.git
    ln -s django-popularity/popularity $PROJECT_DIR/popularity
    

    (Here $PROJECT_DIR is your project root directory.)

  2. Add popularity to INSTALLED_APPS in settings.py:

    INSTALLED_APPS = (
        ...
        'popularity',
        ...
    )
    

    Optionally, use the variable POPULARITY_CHARAGE to the characteristic number of seconds after which an object grows 'twice as old'.

    There is also a configuration variable POPULARITY_LISTSIZE to set the default number of 'popular' items returned.

  3. Create required data structure:

    cd $PROJECT_DIR
    ./manage.py syncdb
    
  4. Run the tests to see if it all works:

    ./manage.py test
    

    If this fails, please contact me! If it doesn't: that's a good sign, chap! Go on to the next step.

  5. Register the model you want to track by placing the following code somewhere, preferably in models.py:

    import popularity
    popularity.register(<mymodel>)
    

    This will assure that a ViewTracker gets created for each object that is created and that it is deleted when that particular object is deleted as well. Also, this keeps track of add dates of objects.

  6. Next, make sure that for every method where you view an object you add the following code (replace <viewed_object> by whatever you are viewing):

    from popularity.models import ViewTracker
    ...
    ViewTracker.add_view_for(<viewed_object>)
    

    If you want to make sure that your application also works when django_popularity is not present, use the following code for importing:

    import logging
    
    from django.conf import settings
    
    if 'popularity' in settings.INSTALLED_APPS:
       logging.debug('Django_popularity found and will be used.')
       from popularity.models import ViewTracker
       add_view_for = ViewTracker.add_view_for
    
    else:
       logging.warn('Django_popularity not found, creating a bogus function.')
       # If popularity does not exist, create a bogus function.
       def add_view_for(*args, **kwargs):
           pass
        `demo/testapp/views.py`.
    

    Alternatively, you can also use signals to register the viewing of instances:

    from popularity.signals import view
    ...
    view.send(<myinstance>)
    

    As there are multiple methods to do this, just pick one. They should be equally good. If you have a preference for either one, please let me know because two options to do exactly the same sounds like overhead to me.

    Lastly, django-popularity has recently been extended with a beautiful AJAX way to register views for an object. This is useful for interactive scripted ways of viewing objects, for instance for registering views of movies. As of now it is still very much a work in progress but it seems to work quite well. (But are, however, much welcomed by the author.)

    To use this, add the following to your urls.py:

    urlpatterns += patterns('',
        ...
        (r'^viewtracker/', include('popularity.urls')),
        ...
    )
    

    You can now register views by requesting the url /viewtracker/<content_type_id>/<object_id>/ which is facilitated by two lines of JavaScript (using something like jQuery):

    function add_view_for(content_type_id, object_id) {
        $.get('/viewtracker/' + content_type_id + '/' + object_id+'/')
    }
    

    To facilitate the useage of this there is a template tag:

    {% load popularity_tags %}
    ...
    <img onclick="{{ object|viewtrack }}" />
    

    This will render as:

    <img onclick="add_view_for(<nn>,<nn>)" />
    

    WARNING: If you use the latter method, please be aware that it becomes tremendously easier for anyone on the web to register 'fake' views for objects. Hence, this might be considered a security risk.

  7. Now if you want to use the information you've just gathered, the easiest way is to use the included RequestContextProcessors. To do this, include the following in your settings.py:

    TEMPLATE_CONTEXT_PROCESSORS = (
        ...
        'popularity.context_processors.most_popular',
        'popularity.context_processors.most_viewed',
        'popularity.context_processors.recently_viewed',
        'popularity.context_processors.recently_added',
    )
    

    Here, the first processors are Django's default. The latter respectively add most_popular, most_viewed, recently_viewed and recently_added to the RequestContext.

    (If you don't know what a RequestContext is, do not pity yourself. Visit http://docs.djangoproject.com/en/dev/ref/templates/api/#id1.)

    A second way is to use template tags. As with all sets of custom tags you must first call {% load popularity_tags %} in your template. There 6 template tags you can use which are described below.

    Tag: views_for_object
    Usage: {% views_for_object widget as views %}
    Description: Retrieves the number of views for and stores them in a context variable.
    Tag: views_for_objects
    Usage: {% views_for_objects widget_list as view_count %}
    Description: Retrieves the number of views for each object and stores them in an attribute. After using this tag the views for each widget in the widget_list can be accessed through widget_list.view_count.
    Tag: most_popular_for_model
    Usage: {% most_popular_for_model main.model_name as popular_models %} or {% most_popular_for_model main.model_name as popular_models limit 20 %}
    Description: Retrieves the ViewTrackers for the most popular instances of the given model. If the limit is not given it will use settings.POPULARITY_LISTSIZE. The model should be given by the app name followed by the model name such as comments.Comment or auth.User.
    Tag: most_viewed_for_model
    Usage: {% most_viewed_for_model main.model_name as viewed_models %} or {% most_viewed_for_model main.model_name as viewed_models limit 20 %}
    Description: Retrieves the ViewTrackers for the most viewed instances of the given model. If the limit is not given it will use settings.POPULARITY_LISTSIZE. The model should be given by the app name followed by the model name such as comments.Comment or auth.User.
    Tag: recently_viewed_for_model
    Usage: {% recently_viewed_for_model main.model_name as recent_models %} or {% recently_viewed_for_model main.model_name as recent_models limit 20 %}
    Description: Retrieves the ViewTrackers for the most recently viewed instances of the given model. If the limit is not given it will use settings.POPULARITY_LISTSIZE. The model should be given by the app name followed by the model name such as comments.Comment or auth.User.
    Tag: recently_added_for_model
    Usage: {% recently_added_for_model main.model_name as recent_models %} or {% recently_added_for_model main.model_name as recent_models limit 20 %}
    Description: Retrieves the ViewTrackers for the most recently added instances of the given model. If the limit is not given it will use settings.POPULARITY_LISTSIZE. The model should be given by the app name followed by the model name such as comments.Comment or auth.User.
  8. Now you're done. Go have beer. Or a whiskey. Or coffee. Suit yourself. If you're still not done learning, try reading through the many methods described in popularity/models.py as they are to be documented later.

Credits

Django-popularity was initially developed by Mathijs de Bruin <mathijs@mathijsfietst.nl> while working for Visualspace <info@visualspace.nl>.

Major and minor contributions to this project were made by:

License

This application is released under the GNU Affero General Public License version 3.

Something went wrong with that request. Please try again.