Introduction
------------
media hive Badges are images that can be embedded into a web page (or myspace
page, blog, used as a sig, etc.). There are badges that show what just played,
what's playing now, or your favorite artists, albums, or songs. Or, if the stock
badges aren't quite what you are looking for, you can make your own - it's just
like making a web page using HTML. Templates are included to get you started.

Please be aware that when you first install media hive, it has no data about
your usage habits. As you use the system, it collects the information that it
uses to make badges. The only badge that works "out of the box" is the
nowplaying.jsp badge, and for that one to work your playlist must
not be empty. (Actually, it will work if the playlist is empty, but there will
be nothing for it to show.)


Included Badges
---------------
Badges are easy to make, so creating your own is the best way to get a
one-of-a-kind badge. See the "Creating Your Own Badges" section for more
information. But if you're in a hurry, the hive comes with a few standard badges
that you can use. They are:

o top.jsp - Shows your most played stuff (artists, albums, or songs).
o favorites.jsp - Shows a random selection of your five-star catalog entries.
o nowplaying.jsp - Shows the just played entry, the currently playing entry, and
  what's up next.


Using Badges
------------
Embedding a badge into your web site is simple. All you need to do is add an
image tag that looks something like this:

<img src="http://yourserver:8080/mhive/myhive?user=username&w=200&h=200&page=page.jsp" alt=""/>

o Replace "yourserver" with the domain name or ip address of the machine that is
  running the media hive.
o Replace "username" with your mhive user id. This id is how the hive knows
  who's usage data to use when building the badge.
o The "w" and "h" parameters control the size of the image. You can make these
  any size you want. When setting the dimensions of a badge,
  keep in mind that if row content is long, it may wrap, so it's a good idea to
  make your badge tall enough to accommodate this.
o The "page" parameter specifies which badge page to use. Badge pages must be
  located in the mhive/web/my directory. The default badges are listed in the
  previous section.

The parameters that allow you to configure a badge are discussed below. To add a
background image file to the system, put it anywhere in mhive/web/my directory
(preferably in the custom/images directory, so the system can find it when
upgrading).

For security reasons, the stock badges will not let you reference a graphic
resource on a remote system. This restriction does not exist when you are
creating your own badges from scratch.


Configuring the top.jsp Badge
-----------------------------
The following url parameters can be supplied to the top.jsp badge:

what*: What to display. (artists|albums|songs)
count*: The number of rows to show.
preset: The date range to pull top items from. (yesterday|week|month|last#days)
text: The color of the text. Specify '#' as %23 in the url.
bold: Sets text to bold. Just add "&bold" to the url; no value needed.
er/or: Even/odd row color.  Specify '#' as %23 in the url.
bg: The background color.  Specify '#' as %23 in the url.
bgimg: A url to the background image.
bgx: X position of background (#px|#%|left|center|right)
bgy: Y position of background
bgrepeat: Background repeat param (repeat|repeat-x|repeat-y)
tpad/lpad/rpad: Top/left/right padding size
align: The position of the table content (left|center|right)
bs: Border size
bc: Border color
* required

Here's an example of the top.jsp badge with all options turned on. If you
replace the user name with your own, this url should work in your browser
(although the background image most likely won't exist).

http://localhost:8080/mhive/myhive?user=jdoe&w=300&h=200&page=top.jsp&what=songs&count=5&preset=week&text=%23444444&bold&er=%23bbbbbb&or=%23dddddd&bg=white&bgimg=images/bkg.png&bgx=50px&bgy=center&bgrepeat=repeat&tpad=10&lpad=5&rpad=5&align=center&bs=2&bc=black

To add the example above to your website, just put the url in an image tag.
Remember that if the media hive is running on a different machine than your
website, "localhost" won't work; you'll need to use the domain name or ip
address of the machine running the media hive.

<img src="http://localhost:8080/mhive/myhive?user=jdoe&w=300&h=200&page=top.jsp&what=songs&count=5&preset=week&text=%23444444&bold&er=%23bbbbbb&or=%23dddddd&bg=white&bgimg=images/bkg.png&bgx=50px&bgy=center&bgrepeat=repeat&tpad=10&lpad=5&rpad=5&align=center&bs=2&bc=black" alt=""/>


Configuring the favorites.jsp Badge
-----------------------------------
The following url parameters can be supplied to the favorites.jsp badge:

count*: The number of rows to show.
text: The color of the text. Specify '#' as %23 in the url.
bold: Sets text to bold. Just add "&bold" to the url; no value needed.
er/or: Even/odd row color.  Specify '#' as %23 in the url.
bg: The background color.  Specify '#' as %23 in the url.
bgimg: A url to the background image.
bgx: X position of background (#px|#%|left|center|right)
bgy: Y position of background
bgrepeat: Background repeat param (repeat|repeat-x|repeat-y)
tpad/lpad/rpad: Top/left/right padding size
align: The position of the table content (left|center|right)
bs: Border size
bc: Border color
* required

Here's an example of the favorites.jsp badge with all options turned on. If you
replace the user name with your own, this url should work in your browser
(although the background image most likely won't exist).

http://localhost:8080/mhive/myhive?user=jdoe&w=300&h=200&page=favorites.jsp&count=5&text=%23444444&bold&er=%23bbbbbb&or=%23dddddd&bg=white&bgimg=images/bkg.png&bgx=50px&bgy=center&bgrepeat=repeat&tpad=10&lpad=5&rpad=5&align=center&bs=2&bc=black

To add the example above to your website, just put the url in an image tag.
Remember that if the media hive is running on a different machine than your
website, "localhost" won't work; you'll need to use the domain name or ip
address of the machine running the media hive.

<img src="http://localhost:8080/mhive/myhive?user=jdoe&w=300&h=200&page=favorites.jsp&count=5&text=%23444444&bold&er=%23bbbbbb&or=%23dddddd&bg=white&bgimg=images/bkg.png&bgx=50px&bgy=center&bgrepeat=repeat&tpad=10&lpad=5&rpad=5&align=center&bs=2&bc=black" alt=""/>


Configuring the nowplaying.jsp Badge
------------------------------------
The following url parameters can be supplied to the nowplaying.jsp badge:

nowplaying.jsp badge:

text: The color of the text. Specify '#' as %23 in the url.
er/or: Even/odd row color.  Specify '#' as %23 in the url.
bg: The background color.  Specify '#' as %23 in the url.
bgimg: A url to the background image.
bgx: X position of background (#px|#%|left|center|right)
bgy: Y position of background
bgrepeat: Background repeat param (repeat|repeat-x|repeat-y)
lpad/rpad: Side padding width
align: The position of the table content (left|center|right)
bs: Border size
bc: Border color

Here's an example of the nowplaying.jsp badge with all options turned on. If you
replace the user name with your own, this url should work in your browser
(although the background image most likely won't exist).

http://localhost:8080/mhive/myhive?user=jdoe&w=300&h=200&page=nowplaying.jsp&count=5&text=%23444444&er=%23bbbbbb&or=%23dddddd&bg=white&bgimg=images/bkg.png&bgx=50px&bgy=center&bgrepeat=repeat&tpad=10&lpad=5&rpad=5&align=center&bs=2&bc=black

To add the example above to your website, just put the url in an image tag.
Remember that if media hive is running on a different machine than your
website, "localhost" won't work; you'll need to use the domain name or ip
address of the machine running media hive.

<img src="http://localhost:8080/mhive/myhive?user=jdoe&w=300&h=200&page=nowplaying.jsp&count=5&text=%23444444&er=%23bbbbbb&or=%23dddddd&bg=white&bgimg=images/bkg.png&bgx=50px&bgy=center&bgrepeat=repeat&tpad=10&lpad=5&rpad=5&align=center&bs=2&bc=black" alt=""/>


Troubleshooting
---------------
When you are adding a lot of configuration parameters to your badge, it's easier
to access the badge page directly, and then, once you have the parameters set up
the way you want, render it as an image.

(Note that when you work with a badge this way, the width and height settings
don't do anything.)

To access a badge directly, start with this url:

http://localhost:8080/mhive/my/<badgepage.jsp>?sid=<sid>&user=<username>&w=<width>&h=<height>&page=<badgepage.jsp>

Everything in <> should be replaced with values that are specific to your badge.
To get a valid sid (session id), go to a browser with a hive page open, and copy
it out of the url.

Add the desired url parameters to the end of the
url. Once you have all the parameters working, change the start of your url from
this:

http://localhost:8080/mhive/my/<badgepage.jsp>?sid=<sid>&

to this:

http://localhost:8080/mhive/myhive?

making sure to leave everything else the same.

Once you have changed your url, you can start adjusting the "w" and "h"
parameters to make your badge the right size for your web page.


Creating Your Own Badges
------------------------
Badge files must be located in the mhive/web/my directory. This applies to both
the badge itself (the jsp file), and any graphics files it uses.

Your best bet is to start  with a badge from the mhive/web/my/examples
directory. Use the technique described in the "Troubleshooting" section to load
your badge directly, because it's a lot easier to troubleshoot errors that way.
Once you have it working the way you want, change your url to render it as an
image (again, as described in the "Troubleshooting" section).

Badges must be written in strict XHTML. Even if your browser renders your custom
badge properly, the internal renderer will not if XHTML syntax is not used. You
can test your badges for XHTML compliance at http://validator.w3.org/.


Support
-------
If you are having trouble using the badge feature of media hive, drop me a line
from the support page of the media hive website (http://www.mhive.org/) and I'll
try to help.
