Quickstart Guide

This guide assumes that you already have a Django installation up and running. If this is not the case, you should work through the Django tutorial first.

Get a Last.fm API key

In order to use the Last.fm web services, you’ll need an API key. You can get one here – it’s free for non-commercial use.

Installation

This app requires Setuptools for installation. Optionally, If you want to run the tests, you need to install Mock.

You can either download a stable version or use the latest version from the repository.

If you downloaded the stable version, unpack it and open a terminal. Change to the directory that contains django-lastfm’s setup.py and execute it as follows:

$ cd where/you/put/django-lastfm/
$ sudo python setup.py install

If you want the bleeding edge, clone the repository and install it in development mode. This will create just a link in your site packages that points to your local repository:

$ hg clone http://bitbucket.org/scherfke/django-lastfm/
$ cd django-lastfm/
$ sudo python setup.py develop

With this done, all you need to do to upgrade your installation of django-lastfm is to type:

$ hg pull -u

Setup

Add 'lastfm' to your INSTALLED_APPS within your settings.py and add the following line to your project’s urls.py:

url(r'^lastfm/', 'lastfm.views.lastfm_data', name='lastfm'),

Configuration

Add the following variables to your settings.py:

LASTFM_USER = 'your_lastfm_username'
LASTFM_API_KEY = 'your_api_key'
# Available types: recent_tracks, weekly_top_artists, top_artists
LASTFM_CHART_TYPE = 'top_artists'
LASTFM_WIDGET_TITLE = 'Weekly Top Artists'
LASTFM_NUM_IMAGES = '12'
LASTFM_TOP_ARTISTS_PERIOD = '7day'
# Available sizes: small, medium, large, extralarge
LASTFM_IMG_SIZE = 'large'

Most of them should be very self-explanatory. LASTFM_TOP_ARTISTS_PERIOD is only required for the top_artist chart type.

Add the widget to your templates

Django-lastfm provides a template tag that inserts the widget to the context of your template (e.g. base.html):

{% load lastfm_widget %}

<!-- ... -->

{% get_lastfm_widget as lastfm_widget %}
<h2>{{ lastfm_widget.title }}</h2>
{{ lastfm_widget.content }}

<!-- ... -->

The template tag get_lastfm_widget creates a new context variable whose name can be chosen as you want (e.g. lastfm_widget). It has two attributes: title contains the string, that you specified in your settings.py; content contains a <div> container and some AJAX code that retrieves the Last.fm data from the corresponding view and creates something like this:

<div class="lastfm">
    <div><a><img /></a></div>
    <div><a><img /></a></div>
    <!-- ... -->
</div>

The surrounding <div> has the CSS class lastfm. You can use this to customize the style of the widget. Here is an example:

#sidebar > #lastfm {
    min-height: 225px; /* required due to "float: left" in the next sec. */
}

#sidebar #lastfm div {
    width: 54px;
    height: 39px;
    overflow: hidden;
    float: left;
    border: 1px solid white;
    -moz-border-radius: 2px;
    -khtml-border-radius: 2px;
    border-radius: 2px;
    margin: 0px 2px 4px 2px;
}

#sidebar #lastfm div:active, #sidebar #lastfm div:hover {
    border-color: #9FC765;
}

#sidebar #lastfm img {
    width: 54px;
    min-height: 39px;
}

A word on caching

Your last.fm profile doesn’t update very often and the last.fm terms of service prohibit more than five requests per second. Thus, you really should use caching!

The lastfm_data()-view is already wrapped with Django’s cache-decorator. You only need to enable caching in your settings.py:

  1. Install memcached and python-memcache (e.g. with sudo apt-get install python-memcache memcached)

  2. Add the following line to your settings.py:

    CACHE_BACKEND = 'dummy:///' if DEBUG else 'memcached://127.0.0.1:11211/'
    

Django’s documentation describes caching in more detail.

That’s it!

Reload your webserver and that’s it!

Table Of Contents

Previous topic

Welcome to django-lastfm’s documentation!

Next topic

API-Reference

This Page