From 193d12b4066db0d9db148fa570d9908abc4aa135 Mon Sep 17 00:00:00 2001 From: Kevin Chabowski Date: Sat, 4 Sep 2010 23:58:05 +0200 Subject: More documentation. - Added a 'Documentation.html'. This is the HTML documentation which can also be seen in the 'Help' section of the installed plugin. - Added a small README file because github.org complained about the absence of this file. --- Documentation.html | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ INSTALL | 3 +- README | 15 +++++++++ 3 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 Documentation.html create mode 100644 README diff --git a/Documentation.html b/Documentation.html new file mode 100644 index 0000000..1db7bd7 --- /dev/null +++ b/Documentation.html @@ -0,0 +1,94 @@ + + + + kch_lastfm_recently documentation + + +

kch_lastfm_recently

+ +

Returns a unsorted list of your recently listened songs.

+ +

Usage

+ +

Insert this txp tag to your template:
+<txp:kch_lastfm_recently />

+ +

Here is a table of parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter	Needed	Default	Explanation
name	Yes		Your last.fm account name
count	No	3	How many songs should be listed
cover	No	1	Whether album covers should be displayed, or not
track_format	No	{ar} – {s} ({t})	Format of track information (See beyond)
date_format	No	%d %h %Y %H:%M:%S	Time/Date format as used by strftime¹
caching	No	1	Should we enable caching? (See section caching)

+ +

And here is a list of track_format tokens (case sensitive): +

{ar} – Artist
{s} – Song name
{al} – Album name ( will turn to “(?)”, if Album is unknown)
{t} – The Time, you’ve listened to the song

+ +

Output

+ +

The output will be a unsorted list (<ul> ... </ul>) with the CSS class kch_lastfm_recently .
+The single list elements have this format:

+ +

<li>
+  <img src="http://lastfm-or-amazon-server.foo/path/to/image" alt="Album cover" style="width:60px;height:60px;" />
+  <a href="http://last.fm/path/to/song/informations">The parsed track_format</a></li>";
+</li>
+

+ +

Hidden errors

+ +

If something went wrong, <txp:kch_lastfm_recently /> will not displaying anything, but it will write an HTML comment with an errormessage. So if you can not see anything, first check the returned HTML code, if there is a comment with an error message.

+ +

Caching

+ +

If you have enabled caching, kch_lastfm_recently will save the results to “/my/textpattern/installation/textpattern/cache”.
+So if you want to use caching, you have to create a directory called “caching” inside the textpattern directory and the HTTP server must have write permission to it.
+Results are cached for one minute. If you have multiple <txp:kch_lastfm_recently /> tags with different configurations, this is not a problem, because the cache file gets a unique identifier based on the parameters.
+If you have the possibility to create the cache directory and set the required permissions, you really should use this feature, because the last.fm API calls can generate a lot of traffic, if your website has much hits.

+ +

¹ Documentation of strftime

+ diff --git a/INSTALL b/INSTALL index 6f8342b..dcf8b70 100644 --- a/INSTALL +++ b/INSTALL @@ -8,4 +8,5 @@ How to install kch_lastfm_recently: 5. Activate the Plugin by clicking the 'No' in the column 'Active' in the row of the kch_lastfm_recently plugin. 6. Read the Help of the plugin (there is a 'help' link in the 'Manage' column) - to learn how to integrate the plugin into your site. + or the 'Documentation.html' in this directory to learn how to integrate the + plugin into your site. diff --git a/README b/README new file mode 100644 index 0000000..8b86194 --- /dev/null +++ b/README @@ -0,0 +1,15 @@ +kch_lastfm_recently v.0.5.1 +=========================== + +A simple Textpattern plugin, which will return a list of recently listened +songs. + +How to Install +-------------- + +See 'INSTALL'. + +Documentation +------------- + +See 'Documentation.html' -- cgit v1.2.3-54-g00ecf