Quickstart Guide — django-lastfm v0.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- django-lastfm v0.1 documentation »

# 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!

### Navigation

- index
- modules |
- next |
- previous |
- django-lastfm v0.1 documentation »