4. Widgets

Widgets

Centova Cast provides a number of widgets which you can include in your own web pages to display information about your stream. No programming knowledge is required — anyone who understands HTML (and, ideally, CSS) can make use of these snippets to easily add custom stream information to a web page.

The code for each of these snippets can be obtained using the Widgets link under the Configuration heading in your Centova Cast control panel. Each widget is documented individually in its own section.

Using the Widgets

Each widget is provided as a set of two HTML tags which, together, provide the complete functionality of the widget.

The first of the two HTML tags essentially provides a “marker” to indicate where on the page you want the widget to appear. This tag should be embedded in your HTML page wherever you want the widget to be inserted.

The second HTML tag is a script reference which includes the “logic” for the widget in your page. This should be placed at the end of your HTML page, just before the closing </body> tag.

Once you have added these two tags to your HTML, simply save your changes and refresh your page. The new widgets should appear instantly.

Alternate Character Encodings

If you find that the code snippets show certain accented characters incorrectly when used on your web site, it is possible that you are not using UTF-8 encoding on your web page.

To correct this, you should set the “Character encoding” setting on the Widgets page to the correct character encoding for your web page. This will re-load the Widgets page and update each snippet to use the correct character encoding. Note that after changing the character encoding, you must copy and paste the updated widget code into your web site, replacing the old code.

tream Status Summary

About the Widget

The Stream Status Summary widget displays a brief line of information about the current status of your stream. Typically, this will look something like the following:

Station Name - Artist Name - Track Title

The above text is hyperlinked such that clicking it will launch the visitor’s default media player to tune in to the stream.

The status summary is automatically updated at regular intervals such that it always displays the correct song artist and title.

Advanced Customization

Configurable Options

Developers familiar with JavaScript may embed in their pages a code block similar to the following to customize the behavior of the widget.

This configuration block must appear before the JavaScript code for the widget.

<script language="javascript">
(function(){ var centovacast = (window.centovacast||(window.centovacast={}));
(centovacast.streaminfo||(centovacast.streaminfo={})).config = {

    poll_limit: 60,        // specify how many times to poll the server
    poll_frequency: 60000  // specify the poll frequency in milliseconds

};})();
</script>

CSS

Developers familiar with cascading stylesheets (CSS) may embed in their pages a stylesheet similar to the following to customize the appearance of the widget:

/* Element containing the stream information */
.cc_streaminfo {
}

Stream Details
About the Widget
The Stream Details widget is a more flexible version of the Stream Status Summary widget, and is designed for more advanced users who wish to customize the placement of the individual elements of stream information.

Using this snippet, you can individually place the elements for the current song, stream title, bit rate, and many more status indicators anywhere on your web page, and Centova Cast will automatically fill them in.

Much like the Stream Status Summary widget, all of the elements of the Stream Details widget are automatically updated at regular intervals such that they always display the correct information.

Available Elements
As of this writing, the Stream Details widget provides the following status elements:

Current song
The current track information, formatted as Artist - Title, and hyperlinked such that clicking launches the visitor's default media player to tune in to the stream.

Stream title
The title for the stream.

Bit rate
The bit rate at which the stream is currently broadcasting.

Current listeners
The number of listeners currently connected to the stream.

Maximum listeners
The maximum number of listeners which may connect to the stream.

Server status
The current status of the stream (either Online or Offline).

AutoDJ status
The current status of the autoDJ (either Online or Offline).

Source connected
An indication of whether a source is currently connected to the stream (either Yes or No).

Station time
The current date and time relative to the station's time zone, formatted per the station's locale settings.

Current playlist
The name of the playlist from which the current track was selected, if the autoDJ is active.

Track artist
The artist of the current track.

Track title
The title of the current track.

Track album
The album of the current track.

Album image
The album cover image for the current track.

Album URL
The album URL (if available) for the current track.

Advanced Customization
Configurable Options
Developers familiar with JavaScript may embed in their pages a code block similar to the following to customize the behavior of the widget.

This configuration block must appear before the JavaScript code for the widget.

<script language="javascript">
(function(){ var centovacast = (window.centovacast||(window.centovacast={}));
(centovacast.streaminfo||(centovacast.streaminfo={})).config = {

    poll_limit: 60,        // specify how many times to poll the server
    poll_frequency: 60000  // specify the poll frequency in milliseconds

};})();
</script>
CSS
Developers familiar with cascading stylesheets (CSS) may embed in their pages a stylesheet similar to the following to customize the appearance of the widget:

/* Element(s) containing the stream information */
.cc_streaminfo {
}
Note that the stream details sample provided on the Widgets page is plain HTML and the developer may optionally customize the HTML and/or add custom class names to each <span>/<a>/<img> element to address it via CSS.
Recent Tracks
About the Widget
The Recent Tracks widget displays a list of the tracks that were most recently played on your stream, along with the name of the artist, album, and broadcast time associated with each.

If available, the album cover image and a "Buy now" link are also displayed next to each track.

The track list is automatically updated at regular intervals such that it always reflects the most recently played tracks.

This widget can be configured on the Widgets tab of the Configuration Settings page.

Advanced Customization
Configurable Options
Developers familiar with JavaScript may embed in their pages a code block similar to the following to customize the behavior of the widget.

This configuration block must appear before the JavaScript code for the widget.

<script language="javascript">
(function(){ var centovacast = (window.centovacast||(window.centovacast={}));
(centovacast.recenttracks||(centovacast.recenttracks={})).config = {

    poll_limit: 60,        // specify how many times to poll the server
    poll_frequency: 60000, // specify the poll frequency in milliseconds
    track_limit: 0,        // maximum number of tracks to display (0=all)
    show_covers: 1,        // 1 to show covers, 0 to hide
    scale_covers: 1,       // 1 to scale covers to the default size, 0 to allow
                           // the web page to apply width/height via CSS
    buy_target: '_blank'   // target frame for "buy now" links

};})();
</script>
CSS
Developers familiar with cascading stylesheets (CSS) may embed in their pages a stylesheet similar to the following to customize the appearance of the widget:

/* Container element for the recent tracks list */
.cc_recenttracks_list {
}
/* Container for a single track in the list */
.cc_recenttracks_list > .cctrack {
}
/* Container for a track's image */
.cc_recenttracks_list > .cctrack > .cccover {
}
/* The track's image */
.cc_recenttracks_list > .cctrack > .cccover > img {
}
/* The time at which the track aired */
.cc_recenttracks_list > .cctrack > .cctime {
}
/* The time at which the current track began playing */
.cc_recenttracks_list > .cctrack > .cctime.ccnowplaying {
}
/* Container for the track's details */
.cc_recenttracks_list > .cctrack > .ccdetails {
}
/* The track's title */
.cc_recenttracks_list > .cctrack > .ccdetails > .cctitle {
}
/* The current track's title */
.cc_recenttracks_list > .cctrack > .ccdetails > .cctitle.ccnowplaying {
}
/* The track's artist */
.cc_recenttracks_list > .cctrack > .ccdetails > .ccartist {
}
/* The track's album */
.cc_recenttracks_list > .cctrack > .ccdetails > .ccalbum {
}
/* The track's buy-now link, if any */
.cc_recenttracks_list > .cctrack > .ccdetails > .ccbuy {
}


Listener Map
About the Widget
The Listener Map widget displays an interactive map, powered by the Google Maps mapping service, on which the geographic locations of your listeners and your stream are plotted.

This widget can be configured on the Widgets tab of the Configuration Settings page.

Advanced Customization
Configurable Options
Developers familiar with JavaScript may embed in their pages a code block similar to the following to customize the behavior of the widget.

This configuration block must appear before the JavaScript code for the widget.

<script language="javascript">
(function(){ var centovacast = (window.centovacast||(window.centovacast={}));
(centovacast.googlemaps||(centovacast.googlemaps={})).config = {

    show_server_location: true, // specify whether to plot server location on map
    server_location: null,      // textual name of server location (eg: city)
    server_country_code: null   // country code to display flag at server location

};})();
</script>
CSS
Developers familiar with cascading stylesheets (CSS) may embed in their pages a stylesheet similar to the following to customize the appearance of the widget:

/* Container element for the map */
.cc_gmaps_map {
}


On-demand Content
About the Widget
The On-demand Content widget provides a file browser for your on-demand content, allowing visitors to browse, stream, or download the media you've published in your "ondemand" folder in the File Manager.

This widget is commonly used to allow visitors to download podcasts or other pre-recorded content from your station.

Like all of the widgets, the On-demand Content widget operates using AJAX requests such that the page never re-loads, and thus can be safely embedded into any web page.

This widget can be configured on the Widgets tab of the Configuration Settings page.

Publishing On-demand Content
To add files for clients to download or stream:

Click the Files link under the AutoDJ heading in your client area.
Click the ondemand folder in the left-hand folder pane.
Click the Upload button to upload files into the ondemand folder. Any files you upload to this folder will immediately be published in your On-demand Content widget.
To remove files from the widget, simply select the file(s) to remove and click the Delete button at the bottom of the page.

Advanced Customization
CSS
Developers familiar with cascading stylesheets (CSS) may embed in their pages a stylesheet similar to the following to customize the appearance of the widget:

/* Container element for the widget */
.cc_ondemand_content {
}
/* Container for the file/folder list */
.cc_ondemand_content > .cc_ondemand_rowlist {
}
/* An individual item (file or folder) in the list */
.cc_ondemand_content > .cc_ondemand_rowlist > .ccfilerow {
}
/* An individual folder in the list */
.cc_ondemand_content > .cc_ondemand_rowlist > .ccfilerow.ccfiletype_folder {
}
/* An individual media file in the list */
.cc_ondemand_content > .cc_ondemand_rowlist > .ccfilerow.ccfiletype_media {
}
/* An individual generic file in the list */
.cc_ondemand_content > .cc_ondemand_rowlist > .ccfilerow.ccfiletype_other {
}
/* A selection checkbox for an item in the list */
.cc_ondemand_content > .cc_ondemand_rowlist > .ccfilerow > .ccfilebox {
}
/* The size of a file */
.cc_ondemand_content > .cc_ondemand_rowlist > .ccfilerow > .ccfilesize {
}
/* The name of a file/folder */
.cc_ondemand_content > .cc_ondemand_rowlist > .ccfilerow > .ccfilename {
}
/* Container for the "Play selected files" link at the end of the list */
.cc_ondemand_content > .cc_ondemand_rowlist > .ccfilem3u {
}
/* Container for the "loading" throbber */
.cc_ondemand_loading {
}

Song Requests
About the Widget
The Song Requests widget displays a form allowing your visitors to submit song requests.

Depending on how the widget has been configured, the request can be handled in one of two ways. Either:

The request can be emailed to the stream administrator for manual review and processing, or
The request can be processed automatically. In this case, the artist and song title are compared against the tracks in the media library. If a matching track is found, the track can be queued for playback automatically.
This widget can be configured on the Widgets tab of the Configuration Settings page.

Advanced Customization
CSS
Developers familiar with cascading stylesheets (CSS) may embed in their pages a stylesheet similar to the following to customize the appearance of the widget:

/* Container element for the widget */
.cc_request_form {
}
/* Container element for the loading throbber */
.cc_request_throbber {
}
/* Container element for the result text */
.cc_request_form *[data-type="result"] {
}
Note that the request form sample provided on the Widgets page is plain HTML and the developer may optionally customize the HTML and/or add custom class names to each <input> element to address it via CSS.

Tune In
About the Widget
The Tune In widget is not actually a widget, but rather just a collection of tune-in links for various media formats.

Embedding this widget in an HTML page simply displays a set of icons for a variety of popular media formats. Clicking on an icon will launch the user's default player for the selected media format.

Stream Directory
About the Widget
The Stream Directory widget displays a list of all stations currently broadcasting from your hosting server. The stream title, listener count, and current track information are provided for each station, with a clickable link to tune in.

The list is automatically updated at regular intervals such that it always displays the latest stream information.

Note that for privacy reasons your administrator may have disabled this feature, so this widget may not appear on your Widgets page.

Advanced Customization
CSS
Developers familiar with cascading stylesheets (CSS) may embed in their pages a stylesheet similar to the following to customize the appearance of the widget:

/* Container element for the widget */
.cc_streamlist_root {
}
/* Container for the list of streams */
.cc_streamlist_root > ul {
}
/* Container for an individual stream in the list */
.cc_streamlist_root > ul > li {
}
/* Container for a stream's details */
.cc_streamlist_root > ul > li > .stream_entry_details {
}
/* A stream's title and start page link */
.cc_streamlist_root > ul > li > .stream_entry_details > a {
}
/* A stream's current listener count */
.cc_streamlist_root > ul > li > .stream_entry_details > .cc_streamlist_entry_listeners {
}
/* The "loading" spinner for a stream in the list */
.cc_streamlist_root > ul > li > .stream_entry_details > .cc_streamlist_entry_loading {
}
/* Container for a stream's status (now-playing information, or offline) */
.cc_streamlist_root > ul > li > .stream_entry_status {
}

Web Player
About the Widget
The Web Player widget provides a web-based media player that your clients can use to tune in to your stream without leaving your web page, and without using an external media player.

This widget can be configured on the Widgets tab of the Configuration Settings page.

Basic Customization
The placeholder <div> element provided for the widget supports some additional options for basic customization of the widget.

skin - Specifies the name of the skin to use for the player.

When using Muses, a skin can be chosen on the Widgets page.
When using jPlayer, the skins blue.monday (the default) and pink.flag are available. Alternately, you can specify custom as the theme name and embed your own jPlayer skin stylesheet in your web page.
width - Specifies the width of the player (in pixels).
Normally this is autodetected from the skin, but may be overridden here.

height - Specifies the height of the player (in pixels).
Normally this is autodetected from the skin, but may be overridden here.

autoplay - Specifies whether or not to automatically begin playing when the page loads.
Set to 1 to automatically play, or 0 to require the user to press play.

These options may be added to the <div> placeholder as HTML5 data attributes. For example, to specify skin foobar and turn on autoplay, you could use:

<div class="cc_player" data-username="user" data-skin="foobar" data-autoplay="1">
    Loading ...
</div>
Advanced Customization
Developers familiar with JavaScript may embed in their pages a code block similar to the following to customize the behavior of the widget.

This configuration block must appear before the JavaScript code for the widget.

<script language="javascript">
(function(){ var centovacast = (window.centovacast||(window.centovacast={}));
(centovacast.player||(centovacast.player={})).config = {

muses: { // configuration used when Muses is your configured player
    lang: 'auto',          // force a specific language for the Muses interface
    volume: 75,            // set initial volume
    autoplay: false,       // automatically begin playing on page load
    buffering: 5,          // number of seconds of audio to buffer
    bgcolor: '#FFFFFF',    // background color (change to match your page)
    //width: 180,          // set a custom widget width (defaults to skin width)
    //height: 60,          // set a custom widget height (defaults to skin height)
    //title: 'Title',      // set a custom title (defaults to your station name)
    //skin: 'http://example.com/skin.xml', // use a custom Muses skin URL
},
jplayer: { // configuration used when jPlayer is your configured player
},
wmp: { // configuration used when Windows Media Player is your configured player
    autostart: 0,          // automatically begin playing on page load
    showcontrols: 1,       // show WMP playback controls
    showstatusbar: 1,      // show WMP status bar
    showdisplay: 1,        // show WMP display
    //width: 180,          // set a custom widget width
    //height: 60,          // set a custom widget height
}

};})();
</script>