User:Willscrlt/UBX/Musicbox/doc

This is a documentation subpage for User:Willscrlt/UBX/Musicbox.
It may contain usage information, categories and other content that is not part of the original userbox page.

This documentation describes how this template will work after some additional development work is completed. The documentation for how the template currently works is available here. It is recommended that you do not implement this template until this notice is removed, because some of the attributes and options will be changed and your implementation may stop working or display bogus information after the changes are made. Nothing serious; but you still might want to wait a little while.

Purpose

Musicboxes are special userboxes that serve three purposes. The first is obvious: they provide a fun way to express your enjoyment of various types of music, favorite artists, albums, and songs. The second purpose is to help editors who enjoy similar styles of music to find each other and collaborate on related music articles. It accomplishes this by adding you to categories that match your interest. By default, Musicboxes do add you to categories; you can turn on that feature ("|cat=n") if you are not interested in collaborating with other editors. The third purpose is to help promote articles on all sorts of music topics. If someone sees you are interested in Klezmer but are not familiar with that style of music, they will probably visit the article and learn more about it.

The rest of this page explains how to add a Musicbox, including fully-customized ones, to your user page. If you already know how or are good at figuring things out on your own, you can browse the complete catalog of available Musicboxes. Select a primary genre to get started:

#18 is used for artists, albums, and song titles, not for genres; it is deliberately omitted from the list above.

Usage

There are four standard Musicboxes: Genre ("This user enjoys…"), Artist ("This user enjoys works by…"), Album ("This user enjoys the album…"), and Song ("This user enjoys the song…"). The Genre Musicbox recognizes 20 broad genres of music, with each genre being identified with a unique color scheme. The Genres allow further specificity with Styles of music, and most styles also recognize several sub-Types of music.

When specifying Genres, Styles, and Types, capitalization is unimportant and ignored by the Musicbox ("RnB" = "rnb" = "RNB").

For Artist, Album, Song Title, and Custom Musicboxes, article names ('name'), if used, are cAsE sEnSiTiVe and must match the Wikipedia article name exactly. Labels ('label') default to the article name, which may be undesirable if the article name is not capitalized the way you would like or if it contains disambiguation information. You may specify a different label if you prefer. The label appears inside a link, so you must not include pipe symbols ("|"), square brackets ("[" or "]"), or braces ("{" or "}"). Remember that the font size on labels is large, so keep the label length relatively short or the label may be truncated.

Custom Musicboxes allow you to create a Musicbox for unrecognized styles and subtypes of music. Just pick the color scheme that matches the Genre of your music (e.g., if your favorite subtype of jazz is unrecognized, use color 12—the color for the jazz Genre), include the article name, and an optional label. Unique Musicboxes allow great lattitude in customization, enabling you to create a truly unique Musicbox.

Technical details are available concerning how the Musicbox templates work.

Syntax

Please also refer to the Table of Color and Genre codes below for examples.

Capitalization should not matter in how the Musicbox understands you input. The only exceptions are that article name links (name=) must match the actual Wikipedia article name in capitalization, and also any labels (label=) or other text (top= and bottom=) are displayed exactly the way you type them. In the latter case, nothing will break, but it might look funny on the screen.

Standard Genre Musicboxes

Genre Musicboxes are the most common type. At a minimum, enter one of the 20 recognized genres (alpha or numerical code, it doesn't matter which). You can get much more specific by adding Styles and sub-Types. See the complete catalog for the codes to use. You can be automatically added to a category of other Wikipedians interested in the same Genre by adding "|cat=y" attribute. You can also pick a non-standard category by entering a category name (e.g., "|cat=Your category goes here")

Standard Musicbox with Genre:

{{User Musicbox|Genre}}
{{User Musicbox|genre=Genre}}

Standard Musicbox with Genre and Style:

{{User Musicbox|Genre|Style}}
{{User Musicbox|genre=Genre|style=Style}}

Standard Musicbox with Genre, Style, and Subtype:

{{User Musicbox|Genre|Style|Type}}
{{User Musicbox|genre=Genre|style=Style|type=Type}}

Optional attribute for Genre Musicboxes:

You can set "|cat=n" to disable the automatic addition of yourself to one of the 20 genre-related categories or set it to any other category ("|cat=Your category here") to add yourself to that category instead of the default

{{User Musicbox|genre|cat=n}}

You can set "|float=right" to right-align the Musicbox (instead of the usual left-alignment) or "|float=none" to disable all floating

{{User Musicbox|genre|float=right}}

The three basic attribute names (genre=, style=, and type=) are optional, but you should either include all three or omit all three. Including one or two, but not the others will usually cause problems. If you omit the attribute names, you must enter the attributes in the correct order (genre, style, type) or the Musicbox will not display correctly.

Other standard Musicboxes

Artist, Album, and Song Title Musicboxes allow you to express your love for specific artists and albums or individuals songs. The structure is the same in each type. You must enter a Wikipedia article name. Be sure that the capitalization and any disambiguations are included. If the article name is how you want your link to appear, then you do not need to enter a label. If you want to shorten the title, change the capitalization, omit a disambiguation, or have something other than the article title appear, enter a custom label. The label appears inside a link, so you must not include pipe symbols ("|"), square brackets ("[" or "]"), or braces ("{" or "}"). Remember that the font size on labels is large, so keep the label length relatively short or the label may be truncated.

Standard Musicbox with Artist's Name:

"article" is the name of the artist's wiki article, "label" is how the artist's name appears and defaults to the article name

{{User Musicbox|artist|name=article|label=display}}

Standard Musicbox with an Album Name:

"article" is the name of the album's wiki article, "label" is how the album's name appears and defaults to the article name

{{User Musicbox|album|name=article|label=display}}

Standard Musicbox with a Song Title:

"article" is the name of the song's wiki article, "label" is how the song title appears and defaults to the article name

{{User Musicbox|song|name=article|label=display}}

You can set "|float=right" to right-align the Musicbox (instead of the usual left-alignment) or "|float=none" to disable all floating

{{User Musicbox|artist|name=article|label=display|float=right}}

Custom and Unique Musicboxes

Custom Musicboxes are structured the same way as the other standard Musicboxes, but let you create Musicboxes for types of music not recognized by the Musicbox template. While you are not required to use the standard color schemes, they help other people quickly identify the main genre for music types they are not familiar with. The label appears inside a link, so you must not include pipe symbols ("|"), square brackets ("[" or "]"), or braces ("{" or "}"). Remember that the font size on labels is large, so keep the label length relatively short or the label may be truncated. The "|float=" attribute works as usual.

Custom Musicbox with any article you choose:

"color" is one of the 22 predefined color schemes (see the table below), "article" is the name of the wiki article, "label" allows you to customize how the article title appears and defaults to the article name, "top" allows you to change the default top text ("This user enjoys") to anything else

{{User Musicbox|custom|color=number|name=article|label=display|top=top text}}

Unique Musicboxes are essentially regular userboxes with a funky layout and a music staff in the background. You can customize nearly everything: border color ("border-c") and thickness ("border-s"); background color ("background-c") and text-color ("text-c"); the uper text ("top") and its font size ("top-s") and line height ("top-lh"); and the lower text ("bottom") and its font size ("bottom-s") and line height ("bottom-lh"). All attributes except "bottom" are optional, and will use the default settings if omitted, so you only need to change what you want to change. Note that "bottom" is plain text, not a link. You may enter a wikilink and format it however you like.

Unique Musicbox with any colors and text you choose:

{{User Musicbox|unique|border-c=css color|border-s=pixels|background-c=css color|text-c=css color|link-c=css color|top-s=points|top-lh=points|top=text|bottom-s=points|bottom-lh=points|bottom=text}}

Table of Color and Genre codes

The following table displays the standard 22 colors (numbered 0–21) and 21 Genre codes recognized by the Musicbox template, along with examples of a Musicbox for each Genre code, the syntax used to produce the Musicbox, and the category associated with each Musicbox.

This table will be added once all of the Musicbox attributes, Genres, and other options are finalized.

A note about Genres and how things are organized

The Genres used by Musicbox, and also how the various musical Styles and sub-Types are organized within each Genre, are unique to Musicbox. When trying to place musical styles into any organized structure, it is impossible to satisfy everyone. Music transcends strict categorization.

After a few false starts from trying to come up with a cohesive system using Wikipedia articles exclusively, the original Musicbox developer (Willscrlt) picked the All Music Guide genre structure to serve as the backbone of Musicbox's Genre classification scheme. This is the same source of information used by several media players, online stores, and books to identify and organize music collections. AMG's genre list was incomplete, and Will didn't like how some things had been placed based on his earlier research on Wikipedia, so he augmented the data with additional help from Wikipedia articles (see articles below); online music databases LyricWiki, Rate Your Music, Last.fm, and MusicBrainz; and online music retailers eMusic.com and Amazon.com. Where multiple sources agreed, that became part of the structure. Where sources disagreed, Will used his best judgement and personal preferences. As a result, many people will find many of the musical styles in logical places, while some people will find that some musical styles are completely miscategorized and consider the structure an epic failure as a result. ;-) Will can live with that and hopes you can, too.

However, Will is a reasonable sort of guy, and if you leave him a note on his talk page how a particular "miscategorization" ruins your day and leave supporting information from reliable sources that explains how your way is a better way to organize things, he'll probably make the change. Of course, this is Wikipedia, so you can edit the templates directly if you prefer (and have a REALLY good understanding of parser functions and other esoteric templating features so you don't break Musicboxes on every other user's page). Probably a better idea is to use the Custom or Unique option to make a special Musicbox exactly the way you like it.

External links

AllMusic.com — used as the primary source for organization of music styles and subtypes within genres for Musicboxes
RateYourMusic.com — used as a secondary source, especially for hard to place music
LyricWiki.org — used as a secondary source, especially for hard to place music
eMusic.com — used as a secondary source, especially for hard to place music
Amazon.com — used as a secondary source, especially for hard to place music
List of genres in ID3v1 — 125 genres widely recognized and embedded in MP3 audio files