Music API
- Display mode: auto
- Display mode: list
- Parameters
- URL Parameters
- API Display mode: Categories
- Display mode: Selector
Display mode: auto
Depending on the URL, will display a list of playlists, a list of songs or the song detail page. See the music howto for more information.
Display mode: list
Depending on the Parameters, will display a list of playlists or a list of songs. See the music howto for more information.
Display mode: Parameters
Playlist List Parameters
find_category
Only show items assigned to that category. Can find multiple categories with a comma separated list. If category slugs are separated by , or || any item assigned to ANY specified category is returned. If && is used to separate only items assigned to ALL specified categories will be returned.
Example:
"find_category:category1,category2,category3",
"find_category:category1 && category2 && category3",
find_year
Only show items from that year.
Example:
"find_year:2009",
find_month
Only show items from that month.
Example:
"find_month:11-2007",
include_songs
Display the songs for each playlist in the list of playlists. The show_songs tags will be used.
Example:
"include_songs:yes",
howmany_playlist
Limits the number of playlists displayed.
Example:
"howmany_playlist:2",groupby_playlists
Will group the content, uses group_show_playlists tags. If display:list is used and group_show_playlist and show_playlist tags are not used, then a <ul> is auto-generated with a list item linking to each item.
| item | description |
|---|---|
| category | Categories and child categories. Some items may appear multiple times if they are assigned to multiple playlists. |
| year | Displays the four digit year as the title. |
| month | Display the two digit month, a hyphen, then the four digit year as the title. Example: 03-2009. |
order
Sets the order of the items in the list.
| item | description |
|---|---|
| recent | by date, starting with most recent |
| title | by entry title, alphabetically |
Song Parameters
howmany
Sets the maximum number of items to display
Example:
"howmany:3",
offset
Skips the first X records returned
Example:
"offset:1",
find_performance
Gets the detail for a performace. Only accepts the performace ID at this point.
Example:
"find_performance:1234",
find_song
WIll limit results to one song.
Example:
"find_song:song-slug",
find_composer
Results will be limited to songs by specified composer.
Example:
"find_composer:composer-slug",
find_performer
Results will be limited to songs by specified performer.
Example:
"find_performer:performer-slug",
find_category
Only show items assigned to that category. Can find multiple categories with a comma separated list. If category slugs are separated by , or || any item assigned to ANY specified category is returned. If && is used to separate only items assigned to ALL specified categories will be returned.
Example:
"find_category:category1,category2,category3",
"find_category:category1 && category2 && category3",
find_tag
Finds all items with that tag or tags. Spaces in tags should be replaced with a dash (-).
Example:
"find_tag:tag-slug,tag-slug2",
groupby
| item | description |
|---|---|
| category | Categories and child categories. Some items may appear multiple times if they are assigned to multiple playlists. |
| performer | The performer's full name will be the title. |
| composer | The composer's full name will be the title. |
order
| item | description |
|---|---|
| recent | by date, starting with most recent |
| title | by entry title, alphabetically |
URL Parameters
All URL based parameters require display:auto. If a nav item is created pointing to either playlists or songs the following URLs will live at those locations. For instance if you point the nav item Media > Sets at playlists, the list of playlists will live at http://www.example.com/media/sets/ and the playlist detail at http://www.example.com/media/sets/playlist-slug/.
http://www.example.com/playlists/
Displays a list of playlists. Uses before_show_playlist, after_show_playlist, no_show_playlist, group_show_playlists, and show_playlist.
http://www.example.com/songs/
Displays a list of all songs regardless of playlists. Uses before_show_songs, after_show_songs, no_show_songs, group_show_songs, show_songs.
http://www.example.com/playlists/playlist-slug/
Displays a list of songs in a particular playlist. Uses before_show_songs, after_show_songs, no_show_songs, group_show_songs, show_songs
http://www.example.com/songs/song-slug/performer-slug/
Displays detail of a particular song performance. Uses before_show_detail, after_show_detail, no_show_songs, no_show_detail.
http://www.example.com/playlists/playlist-slug/song-slug/performer-slug/
Displays detail of a particular song performance with playlist detail info. Uses before_show_detail, after_show_detail, no_show_songs, no_show_detail.
Auto Groupby and Finds
You can automatically generate grouped lists and finds with the URLs as well.
http://www.example.com/playlists/category
A list of playlists grouped by category. Uses group_show_playlists as well as the normal playlist list tags.
http://www.example.com/playlists/category/category-slug/
A list of playlists in a given category. Uses group_show_playlists as well as the normal playlist list tags.
Other available groupings are /month/ and /year/.
http://www.example.com/songs/performer/
A list of songs grouped by performer. Uses group_show_songs as well as the normal song list tags.
http://www.example.com/songs/performer/performer-slug/
A list of songs by a given performer. Uses group_show_songs as well as the normal song list tags.
Other available groupings for songs are /category/, /composer/, and /tag/tag-slug/. Note that /tag/ requires a tag slug, for a list of tags it is recommened to use a tag cloud.
API
Playlist List
before_show_playlist, after_show_playlist, no_show_playlist
| __headerdescription__ | The description entered on the music settings page. |
group_show_playlists
| Tag | Description |
|---|---|
| __title__ | The title of the category, the month or the year. |
| __slug__ | Category slug, the month (formatted 03-2008), or the year. |
show_playlist
| Tag | Description |
|---|---|
| __listtitle__ | Title of the Playlist |
| __listdescription__ | Description of the Playlist |
| __listtitlelink__ | The title of the playlist wrapped in an anchor tag linking to the playlist detail page. |
| __date__ | Formattable date. Use __date format='j/m/Y'__ a complete list of tags is available |
| __listcategory__ | Comma separated list of categories assigned to the playlist |
| __listcategoryslug__ |
The slug of the first category assigned to the playlist |
| __listcategorylinks__ | Comma separated list of links to all playlists in that category. |
| __listaudioplayer__ | A link to the popup audio player with the playlist queued. |
| Any Custom Fields setup for Playlists will output their API tags | |
Playlist Detail / Song List / Song Detail
The same tags are available for both the song list and detail pages, only different calls are used to differentiate the pages.
before_show_songs, after_show_songs, before_show_detail, after_show_detail, no_show_songs, no_show_detail
| Tag | Description |
|---|---|
| __listtitle__ | Title of the Playlist |
| __listdescription__ | Description of the Playlist |
| __listtitlelink__ | The title of the playlist wrapped in an anchor tag linking to the playlist detail page. |
| __date__ | Formattable date. Use __date format='j/m/Y'__ a complete list of tags is available |
| __listcategory__ | Comma separated list of categories assigned to the playlist |
| __listcategoryslug__ |
The slug of the first category assigned to the playlist |
| __listcategorylinks__ | Comma separated list of links to all playlists in that category. |
| __listaudioplayer__ | A link to the popup audio player with the playlist queued. |
| __pagination__ | Divides the records into smaller groups and provides links to navigate through them. |
| __headerdescription__ | The description entered on the music settings page. |
| Any Custom Fields setup for Playlists will output their API tags | |
group_show_songs
| Tag | Description |
|---|---|
| __title__ | The title of the category, the composer or the performer. |
| __slug__ | Category, composer, or performer slug. |
| __type__ | The parameter used to group the content. |
show_songs, show_detail
| Tag | Description |
|---|---|
| __title__ | The title of the category, the composer or the performer. |
| __titlelink__ | The name of the song wrapped in an anchor linking to the song detail page |
| __date__ | The parameter used to group the content. |
| __performer__ | The name of the performer |
| __composer__ | The name of the composter |
| __image__ | The image associated with the song |
| __imageurl__ | |
| __image2__ | |
| __imageurl2__ | |
| __image2__ | |
| __imageurl3__ | |
| __imageTMB__ | A smaller version of the image associated with the song |
| __songsheet__ | A document with the music for the song |
| __lyrics__ | A document with the lyrics to the song |
| __audio__ | A link to download the audio file assigned to the song |
| __audioplayer__ | A link to the popup audio player with the song queued. If the song is part of a playlist, the playlist will be queued after the song. |
| __video__ | A link to download the video file assigned to the song |
| __videoflash__ | url to the flash version of the video when present |
| __videoplayer__ | A link to the popup video player with the song queued |
| __description__ | The description of the song |
| __keywords__ | Tags given to the song |
| __category__ | Comma separated list of categories assigned to the song |
| __categoryslug__ | The slug of the first category assigned to the song |
| __categorylinks__ | Comma separated list of links to all songs in that category. |
| Any Custom Fields setup for Songs will output their API tags | |
Display mode: categories
Show
level#
| Tag | Description |
|---|---|
| __bid__ | Internal system ID of the category for unique identification. |
| __count__ | Numerical count of the articles belonging directly to the category. |
| __level__ | Hierarchical level of the category. The root level is considered level 1. |
| __name__ | Name of the category as entered in the backend. |
| __parentid__ | Internal system ID of the category's parent. This is set to '0' if the category has no parent. |
| __slug__ | Slugged version of the category name. |
Parameters
parent_category
Specifies the parent category slug to use as the hierarchical root to start from.
Example:
"parent_category:slugged-category-name",
Full Example
getContent(
"MODULETYPE",
"display:categories",
"level1:Parent: __name__ (__count__) ",
"level2:Child: __name__",
"level3:Grandchild: __name__",
);
Using "playlist" for the module name will display categories for playlists only.
Using "song" or "music" will display categories for songs.
Display Mode: Selector
A dropdown select will automatically be created which will take the user to a list of songs grouped by the selected categories.
| Tag | Description |
|---|---|
| __composer__ | |
| __performer__ | |
| __category__ | |
| __all__ | Will take the user back to the normal list, not grouped. |
Monklet Example:
tag="music"
display="selector"
select="__performer__ __composer__ __category__ __all__"
You can also do the same thing with playlist lists.
| Tag | Description |
|---|---|
| __month__ | |
| __category__ | |
| __all__ | Will take the user back to the normal list, not grouped. |
Monklet Example:
tag="playlist"
display="selector"
select="__month__ __category__ __all__"