{"body": "<div class=\"section\" id=\"quickstart-guide\">\n<span id=\"quickstart\"></span><h1>Quickstart Guide<a class=\"headerlink\" href=\"#quickstart-guide\" title=\"Permalink to this headline\">\u00b6</a></h1>\n<p>This guide assumes that you already have a <a class=\"reference external\" href=\"http://www.djangoproject.com/\">Django</a> installation up and running. If this is not\nthe case, you should work through the <a class=\"reference external\" href=\"http://docs.djangoproject.com/en/dev/intro/install/#intro-install\">Django tutorial</a> first.</p>\n<div class=\"section\" id=\"get-a-last-fm-api-key\">\n<h2>Get a Last.fm API key<a class=\"headerlink\" href=\"#get-a-last-fm-api-key\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>In order to use the Last.fm web services, you\u2019ll need an API key. You can get\none <a class=\"reference external\" href=\"http://www.last.fm/api/account\">here</a> \u2013 it\u2019s free for non-commercial use.</p>\n</div>\n<div class=\"section\" id=\"installation\">\n<h2>Installation<a class=\"headerlink\" href=\"#installation\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>This app requires <a class=\"reference external\" href=\"http://pypi.python.org/pypi/setuptools\">Setuptools</a> for\ninstallation. Optionally, If you want to run the tests, you need to install\n<a class=\"reference external\" href=\"http://www.voidspace.org.uk/python/mock/\">Mock</a>.</p>\n<p>You can either <a class=\"reference external\" href=\"http://bitbucket.org/scherfke/django-lastfm/downloads/\">download a stable version</a> or use the latest\nversion from the <a class=\"reference external\" href=\"http://bitbucket.org/scherfke/django-lastfm/src/\">repository</a>.</p>\n<p>If you downloaded the stable version, unpack it and open a terminal. Change to\nthe directory that contains <em>django-lastfm\u2019s</em> <tt class=\"docutils literal\"><span class=\"pre\">setup.py</span></tt> and execute it as\nfollows:</p>\n<div class=\"highlight-bash\"><div class=\"highlight\"><pre><span class=\"nv\">$ </span><span class=\"nb\">cd </span>where/you/put/django-lastfm/\n<span class=\"nv\">$ </span>sudo python setup.py install\n</pre></div>\n</div>\n<p>If you want the bleeding edge, clone the repository and install it in\ndevelopment mode. This will create just a link in your <tt class=\"docutils literal\"><span class=\"pre\">site</span> <span class=\"pre\">packages</span></tt> that\npoints to your local repository:</p>\n<div class=\"highlight-bash\"><div class=\"highlight\"><pre><span class=\"nv\">$ </span>hg clone http://bitbucket.org/scherfke/django-lastfm/\n<span class=\"nv\">$ </span><span class=\"nb\">cd </span>django-lastfm/\n<span class=\"nv\">$ </span>sudo python setup.py develop\n</pre></div>\n</div>\n<p>With this done, all you need to do to upgrade your installation of <em>django-lastfm</em> is to type:</p>\n<div class=\"highlight-bash\"><div class=\"highlight\"><pre><span class=\"nv\">$ </span>hg pull -u\n</pre></div>\n</div>\n</div>\n<div class=\"section\" id=\"setup\">\n<h2>Setup<a class=\"headerlink\" href=\"#setup\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>Add <tt class=\"docutils literal\"><span class=\"pre\">'lastfm'</span></tt> to your <tt class=\"docutils literal\"><span class=\"pre\">INSTALLED_APPS</span></tt> within your\n<tt class=\"docutils literal\"><span class=\"pre\">settings.py</span></tt> and add the following line to your project\u2019s <tt class=\"docutils literal\"><span class=\"pre\">urls.py</span></tt>:</p>\n<div class=\"highlight-python\"><div class=\"highlight\"><pre><span class=\"n\">url</span><span class=\"p\">(</span><span class=\"s\">r&#39;^lastfm/&#39;</span><span class=\"p\">,</span> <span class=\"s\">&#39;lastfm.views.lastfm_data&#39;</span><span class=\"p\">,</span> <span class=\"n\">name</span><span class=\"o\">=</span><span class=\"s\">&#39;lastfm&#39;</span><span class=\"p\">),</span>\n</pre></div>\n</div>\n</div>\n<div class=\"section\" id=\"configuration\">\n<h2>Configuration<a class=\"headerlink\" href=\"#configuration\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>Add the following variables to your <tt class=\"docutils literal\"><span class=\"pre\">settings.py</span></tt>:</p>\n<div class=\"highlight-python\"><div class=\"highlight\"><pre><span class=\"n\">LASTFM_USER</span> <span class=\"o\">=</span> <span class=\"s\">&#39;your_lastfm_username&#39;</span>\n<span class=\"n\">LASTFM_API_KEY</span> <span class=\"o\">=</span> <span class=\"s\">&#39;your_api_key&#39;</span>\n<span class=\"c\"># Available types: recent_tracks, weekly_top_artists, top_artists</span>\n<span class=\"n\">LASTFM_CHART_TYPE</span> <span class=\"o\">=</span> <span class=\"s\">&#39;top_artists&#39;</span>\n<span class=\"n\">LASTFM_WIDGET_TITLE</span> <span class=\"o\">=</span> <span class=\"s\">&#39;Weekly Top Artists&#39;</span>\n<span class=\"n\">LASTFM_NUM_IMAGES</span> <span class=\"o\">=</span> <span class=\"s\">&#39;12&#39;</span>\n<span class=\"n\">LASTFM_TOP_ARTISTS_PERIOD</span> <span class=\"o\">=</span> <span class=\"s\">&#39;7day&#39;</span>\n<span class=\"c\"># Available sizes: small, medium, large, extralarge</span>\n<span class=\"n\">LASTFM_IMG_SIZE</span> <span class=\"o\">=</span> <span class=\"s\">&#39;large&#39;</span>\n</pre></div>\n</div>\n<p>Most of them should be very self-explanatory. <tt class=\"docutils literal\"><span class=\"pre\">LASTFM_TOP_ARTISTS_PERIOD</span></tt> is\nonly required for the <tt class=\"docutils literal\"><span class=\"pre\">top_artist</span></tt> chart type.</p>\n</div>\n<div class=\"section\" id=\"add-the-widget-to-your-templates\">\n<h2>Add the widget to your templates<a class=\"headerlink\" href=\"#add-the-widget-to-your-templates\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p><em>Django-lastfm</em> provides a template tag that inserts the widget to the context\nof your template (e.g. <tt class=\"docutils literal\"><span class=\"pre\">base.html</span></tt>):</p>\n<div class=\"highlight-html+django\"><div class=\"highlight\"><pre><span class=\"cp\">{%</span> <span class=\"k\">load</span> <span class=\"nv\">lastfm_widget</span> <span class=\"cp\">%}</span>\n\n<span class=\"c\">&lt;!-- ... --&gt;</span>\n\n<span class=\"cp\">{%</span> <span class=\"k\">get_lastfm_widget</span> <span class=\"k\">as</span> <span class=\"nv\">lastfm_widget</span> <span class=\"cp\">%}</span>\n<span class=\"nt\">&lt;h2&gt;</span><span class=\"cp\">{{</span> <span class=\"nv\">lastfm_widget.title</span> <span class=\"cp\">}}</span><span class=\"nt\">&lt;/h2&gt;</span>\n<span class=\"cp\">{{</span> <span class=\"nv\">lastfm_widget.content</span> <span class=\"cp\">}}</span>\n\n<span class=\"c\">&lt;!-- ... --&gt;</span>\n</pre></div>\n</div>\n<p>The template tag <tt class=\"docutils literal\"><span class=\"pre\">get_lastfm_widget</span></tt> creates a new context variable whose name\ncan be chosen as you want (e.g. <tt class=\"docutils literal\"><span class=\"pre\">lastfm_widget</span></tt>). It has two attributes:\n<tt class=\"docutils literal\"><span class=\"pre\">title</span></tt> contains the string, that you specified in your <tt class=\"docutils literal\"><span class=\"pre\">settings.py</span></tt>;\n<tt class=\"docutils literal\"><span class=\"pre\">content</span></tt> contains a <tt class=\"docutils literal\"><span class=\"pre\">&lt;div&gt;</span></tt> container and some AJAX code that retrieves the\nLast.fm data from the corresponding view and creates something like this:</p>\n<div class=\"highlight-html\"><div class=\"highlight\"><pre><span class=\"nt\">&lt;div</span> <span class=\"na\">class=</span><span class=\"s\">&quot;lastfm&quot;</span><span class=\"nt\">&gt;</span>\n    <span class=\"nt\">&lt;div&gt;&lt;a&gt;&lt;img</span> <span class=\"nt\">/&gt;&lt;/a&gt;&lt;/div&gt;</span>\n    <span class=\"nt\">&lt;div&gt;&lt;a&gt;&lt;img</span> <span class=\"nt\">/&gt;&lt;/a&gt;&lt;/div&gt;</span>\n    <span class=\"c\">&lt;!-- ... --&gt;</span>\n<span class=\"nt\">&lt;/div&gt;</span>\n</pre></div>\n</div>\n<p>The surrounding <tt class=\"docutils literal\"><span class=\"pre\">&lt;div&gt;</span></tt> has the CSS class <em>lastfm</em>. You can use this to\ncustomize the style of the widget. Here is an example:</p>\n<div class=\"highlight-css\"><div class=\"highlight\"><pre><span class=\"nf\">#sidebar</span> <span class=\"o\">&gt;</span> <span class=\"nf\">#lastfm</span> <span class=\"p\">{</span>\n    <span class=\"k\">min-height</span><span class=\"o\">:</span> <span class=\"m\">225px</span><span class=\"p\">;</span> <span class=\"c\">/* required due to &quot;float: left&quot; in the next sec. */</span>\n<span class=\"p\">}</span>\n\n<span class=\"nf\">#sidebar</span> <span class=\"nf\">#lastfm</span> <span class=\"nt\">div</span> <span class=\"p\">{</span>\n    <span class=\"k\">width</span><span class=\"o\">:</span> <span class=\"m\">54px</span><span class=\"p\">;</span>\n    <span class=\"k\">height</span><span class=\"o\">:</span> <span class=\"m\">39px</span><span class=\"p\">;</span>\n    <span class=\"k\">overflow</span><span class=\"o\">:</span> <span class=\"k\">hidden</span><span class=\"p\">;</span>\n    <span class=\"k\">float</span><span class=\"o\">:</span> <span class=\"k\">left</span><span class=\"p\">;</span>\n    <span class=\"k\">border</span><span class=\"o\">:</span> <span class=\"m\">1px</span> <span class=\"k\">solid</span> <span class=\"nb\">white</span><span class=\"p\">;</span>\n    <span class=\"o\">-</span><span class=\"n\">moz</span><span class=\"o\">-</span><span class=\"k\">border</span><span class=\"o\">-</span><span class=\"n\">radius</span><span class=\"o\">:</span> <span class=\"m\">2px</span><span class=\"p\">;</span>\n    <span class=\"o\">-</span><span class=\"n\">khtml</span><span class=\"o\">-</span><span class=\"k\">border</span><span class=\"o\">-</span><span class=\"n\">radius</span><span class=\"o\">:</span> <span class=\"m\">2px</span><span class=\"p\">;</span>\n    <span class=\"k\">border</span><span class=\"o\">-</span><span class=\"n\">radius</span><span class=\"o\">:</span> <span class=\"m\">2px</span><span class=\"p\">;</span>\n    <span class=\"k\">margin</span><span class=\"o\">:</span> <span class=\"m\">0px</span> <span class=\"m\">2px</span> <span class=\"m\">4px</span> <span class=\"m\">2px</span><span class=\"p\">;</span>\n<span class=\"p\">}</span>\n\n<span class=\"nf\">#sidebar</span> <span class=\"nf\">#lastfm</span> <span class=\"nt\">div</span><span class=\"nd\">:active</span><span class=\"o\">,</span> <span class=\"nf\">#sidebar</span> <span class=\"nf\">#lastfm</span> <span class=\"nt\">div</span><span class=\"nd\">:hover</span> <span class=\"p\">{</span>\n    <span class=\"k\">border-color</span><span class=\"o\">:</span> <span class=\"m\">#9FC765</span><span class=\"p\">;</span>\n<span class=\"p\">}</span>\n\n<span class=\"nf\">#sidebar</span> <span class=\"nf\">#lastfm</span> <span class=\"nt\">img</span> <span class=\"p\">{</span>\n    <span class=\"k\">width</span><span class=\"o\">:</span> <span class=\"m\">54px</span><span class=\"p\">;</span>\n    <span class=\"k\">min-height</span><span class=\"o\">:</span> <span class=\"m\">39px</span><span class=\"p\">;</span>\n<span class=\"p\">}</span>\n</pre></div>\n</div>\n</div>\n<div class=\"section\" id=\"a-word-on-caching\">\n<h2>A word on caching<a class=\"headerlink\" href=\"#a-word-on-caching\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p><em>TODO</em></p>\n</div>\n<div class=\"section\" id=\"thats-it\">\n<h2>That\u2019s it!<a class=\"headerlink\" href=\"#thats-it\" title=\"Permalink to this headline\">\u00b6</a></h2>\n<p>Reload your webserver and that\u2019s it!</p>\n</div>\n</div>\n", "display_toc": true, "title": "Quickstart Guide", "sourcename": "quickstart.txt", "customsidebar": null, "current_page_name": "quickstart", "next": {"link": "../ref/", "title": "API-Reference"}, "rellinks": [["genindex", "General Index", "I", "index"], ["py-modindex", "Python Module Index", "", "modules"], ["ref/index", "API-Reference", "N", "next"], ["index", "Welcome to django-lastfm&#8217;s documentation!", "P", "previous"]], "meta": {}, "parents": [], "sidebars": null, "toc": "<ul>\n<li><a class=\"reference internal\" href=\"#\">Quickstart Guide</a><ul>\n<li><a class=\"reference internal\" href=\"#get-a-last-fm-api-key\">Get a Last.fm API key</a></li>\n<li><a class=\"reference internal\" href=\"#installation\">Installation</a></li>\n<li><a class=\"reference internal\" href=\"#setup\">Setup</a></li>\n<li><a class=\"reference internal\" href=\"#configuration\">Configuration</a></li>\n<li><a class=\"reference internal\" href=\"#add-the-widget-to-your-templates\">Add the widget to your templates</a></li>\n<li><a class=\"reference internal\" href=\"#a-word-on-caching\">A word on caching</a></li>\n<li><a class=\"reference internal\" href=\"#thats-it\">That\u2019s it!</a></li>\n</ul>\n</li>\n</ul>\n", "prev": {"link": "../", "title": "Welcome to django-lastfm&#8217;s documentation!"}, "metatags": ""}