audio module hooks
- These hooks allow modules to add songs and albums to the audio player, etc. and add new fields to such content
hook_audio_load
Parameters:
$id => 'string' - usually a node nid but can also be some other unique string
Returns:
StdObject - Arbitrary fields are allowed, but the following are required at minimum:
id => 'string' - matching the $id parameter
audio_elements => array() - data pulled from the audio_elements table
title => 'string' - the name of the song
type => 'song'|'album'
Description:
Given a unique audio ID, fill in the details of the object. Most modules only need to implement this if they provide their own audio IDs via hook_audio_get_songs or hook_audio_get_albums.
hook_audio_get_songs
Parameters:
none
Returns:
array( 'id1', 'id2'... )
Description:
Return a list of unique audio IDs for songs this module provides to the audio API. e.g. the core audio module provides the node nids of all audio_song objects
hook_audio_get_albums
Parameters:
none
Returns:
array( 'id1', 'id2'... )
Description:
Return a list of unique audio IDs for albums this module provides to the audio API. e.g. the core audio module provides the node nids of all audio_album objects
hook_audio_song_types
Parameters:
none
Returns:
array('module_name' => 'Module Description')
Description:
Implementing this hook adds a tab to the manage/audio-song page allowing the songs to be sorted by activation and weight within this module.
hook_audio_album_types
Parameters:
none
Returns:
array('module_name' => 'Module Description')
Description:
Implementing this hook adds a tab to the manage/audio-album page allowing the albums to be sorted by activation and weight within this module.
hook_audio_fields
Parameters
$obj => StdObject - as returned by hook_audio_load
Returns:
array(
module_name => array(
'name' => 'module_name',
'title' => 'Module Description',
'fields' => array( 'field1' => array(0 => $field...)...), - Where $field is an array per the forms API
'weight' => int,
'always_on' => TRUE|FALSE,
)
)
Description:
Generate form fields for editing the audio object passed in. A checkbox with the title 'name' will be put in "Enabled Locations" fieldset of this object's edit form (i.e. audio_song or audio_album node or audio_edit_external_form form). The 'fields' parameter will be rendered in a fieldset that will collapse/expand as the checkbox is toggled off/on. If always_on is TRUE, the checkbox will not be displayed, and the fieldset will not be collapsible. These fieldets are sorted by 'weight'. If multiple fieldsets contain a field with the same name, those values will be linked via javascript and the default submit function.
hook_audio_elements_validate
Parameters:
$form => array() - per drupal forms API
&$form_state => array() - per drupal forms API
Returns:
none
Description:
Validate an audio object editing form. This function is invoked when an audio_song or audio_album node or audio_edit_external_form form is submitted. Generally, any given module should validate any fields it added to the form using hook_audio_fields.
hook_audio_elements_submit
Parameters:
$form => array() - per drupal forms API
&$form_state => array() - per drupal forms API
Returns:
none
Description:
Submit an audio object editing form. This function is invoked when an audio_song or audio_album node or audio_edit_external_form form is submitted. Generally, any given module should submit any fields it added to the form using hook_audio_fields. Fields that were added with the form $fields['name'][delta] will be automatically added to the audio_elements table. More complex fields will need to be processed manually.
hook_audio_xml
Parameters:
$songs => array(StdObject...) - each object is a song object per hook_audio_load
Returns:
'string' - XML for display
Description
Given a list of loaded song objects, generate whatever XML the audio player created by this module requires to render an audio player with those songs.
hook_audio_xml_small
Parameters:
$songs => array(StdObject) - each object is a song object per hook_audio_load
Returns:
'string' - XML for display
Description
Given a list of loaded song objects (usually just 1), generate whatever XML the audio player created by this module requires to render a small audio player with that song.
----- Non API helper functions ----
audio_insert_data
Parameters:
$id => string - unique object id
$name => string - field name
$delta => int - Instance number of this field for this object
$value => mixed - value
Returns:
None
Description:
Adds an entry to the audio_elements table. This is how modules can add custom fields to all types of audio objects throughout the system
audio_delete_data
Parameters:
$id => string - unique object id
$name => string - field name
$delta => int - instance number of this field for this object
$through_end => boolean - should all instances after $delta also be deleted?
Returns
none
Description:
Removes an entry from the audio_elements table. This allows modules to delete specific data from audio objects throughout the system
audio_load_audio
Parameters:
$id => string - unique object id
$no_cache => boolean - should the cache be bypassed?
Returns:
object - a fully-loaded audio object per hook_audio_load
Description:
This function loads a single audio object (from cache if possible) based on its unique ID. Module's should use this function instead of direct invocations of hook_audio_load both due to its simplicity, and because it caches, improving performance.
audio_get_songs
Parameters:
$ids => array - list of unique audio ID strings
$type => 'module_name' - per hook_audio_song_types (e.g. "catalog" or "audio_display")
Returns:
array - objects per hook_audio_load
Description:
This function loads audio song objects. $ids and $type are mutually exclusive. If $ids is specified, those specific objects are loaded. If $type is specified instead, all songs that are active for that section of the site are loaded. If neither is specified, all songs are loaded.
audio_get_albums
Parameters:
$ids => array - list of unique audio ID strings
$type => 'module_name' - per hook_audio_album_types (e.g. "catalog" or "audio_display")
Returns:
array - objects per hook_audio_load
Description:
This function loads audio album objects. $ids and $type are mutually exclusive. If $ids is specified, those specific objects are loaded. If $type is specified instead, all albums that are active for that section of the site are loaded. If neither is specified, all albums are loaded.
audio_get_complements
Parameters:
$id => string - unique audio object ID
$type => 'songs'|'albums' - retreive what type of complements?
Returns:
array - of audio object IDs
Description
This function fetches the IDs of a particular audio object's complementary type. e.g. If an album ID (and the type 'songs') are passed in, it will retrieve a list of all songs on that album. If a song ID (and the type 'albums') are passed, then it will return all albums that song is on.