django-lastfm / docs / quickstart.txt

.. _quickstart:

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 API key

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


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* ```` and execute it as

.. sourcecode:: bash

    $ cd where/you/put/django-lastfm/
    $ sudo python 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:

.. sourcecode:: bash

    $ hg clone
    $ cd django-lastfm/
    $ sudo python develop
With this done, all you need to do to upgrade your installation of 
*django-lastfm* is to type:

.. sourcecode:: bash

   $ hg pull -u

Add ``'lastfm'`` to your ``INSTALLED_APPS`` within your 
```` and add the following line to your project’s ````:
.. sourcecode:: python

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


Add the following variables to your ````::

    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'
    # 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``):

.. sourcecode:: html+django

    {% 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 ````;
``content`` contains a ``<div>`` container and some AJAX code that retrieves the data from the corresponding view and creates something like this:

.. sourcecode:: html

    <div class="lastfm">
        <div><a><img /></a></div>
        <div><a><img /></a></div>
        <!-- ... -->
The surrounding ``<div>`` has the CSS class *lastfm*. You can use this to
customize the style of the widget. Here is an example:

.. sourcecode:: css

    #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 profile doesn’t update very often and the ` terms of
service <>`_ prohibit more than five requests per
second. Thus, you really should use caching!

The :func:`~lastfm.views.lastfm_data`-view is already wrapped with Django’s 
<>`_. You 
only need to enable caching in your ````:

#. Install ``memcached`` and ``python-memcache`` (e.g. with ``sudo apt-get
   install python-memcache memcached``)
#. Add the following line to your ````:

   .. sourcecode:: python
    CACHE_BACKEND = 'dummy:///' if DEBUG else 'memcached://'
Django’s documentation describes `caching 
<>`_ in more detail.

That’s it!

Reload your webserver and that’s it!