Music API

by Justin Bodeutsch | Last edited: 9/23/2016

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#
TagDescription
__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__"