.. _quickstart:

Quickstart Guide
================

This guide assumes that you already have a `Django
<http://www.djangoproject.com/>`_ installation up and running. If this is not
the case, you should work through the `Django tutorial
<http://docs.djangoproject.com/en/dev/intro/install/#intro-install>`_ 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 <http://www.last.fm/api/account>`_ – it’s free for non-commercial use.


Installation
------------

This app requires `Setuptools <http://pypi.python.org/pypi/setuptools>`_ for
installation. Optionally, If you want to run the tests, you need to install
`Mock <http://www.voidspace.org.uk/python/mock/>`_.

You can either `download a stable version
<http://bitbucket.org/scherfke/django-lastfm/downloads/>`_ or use the latest
version from the `repository <http://bitbucket.org/scherfke/django-lastfm/src/>`_.

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:

.. sourcecode:: bash

    $ 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:

.. sourcecode:: bash

    $ 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:

.. sourcecode:: bash

   $ 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``:
   
.. sourcecode:: python

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

.. 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 ``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:

.. sourcecode:: html

    <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:

.. 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
-----------------

*TODO*


That’s it!
----------

Reload your webserver and that’s it!
