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

TODO

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