Creates an audio element and manipulates it to produce audio.
For iOS and Android there are two implementations of audio: app and inline. The App player references the native player and play will be persisted across pages i.e. you can swipe away from the page and audio will still be playing. The Inline player is unique to each page and audio will stop (if it is still playing) when you move away from the page.
Audio elements are often referenced by play and pause buttons (although native controls can be specified), when the user clicks a play button the associated audio will start playing. A subsequent click on a different play button will cause that new audio to queue and be played only once the current audio source has finished, in this manner a user can queue a playlist.
HTML Parameters
The following parameters are required
- data-widget="AUDIO" Required
- The identifier for the widget type.
- data-src="{{string}}" Required
- The source file to use. Can be local ('../assets/audio.mp3') or web ('http://somewebsite.com/someaudio.mp3').
The following parameters are optional (defaults are listed between the braces).
- id="{{id}}" Optional
- It is usually preferable to include a unique ID but it is not strictly necessary.
- data-audio-type="{{inline}}" Optional
-
app
||inline
. The type of player associated with this audio widget. - data-loop="{{false}}" Optional
-
true
||false
. Specifies whether the audio should loop. - data-controls="{{false}}" Optional
-
true
||false
. Specifies whether default controls are shown, if false then the audio will need to be triggered by buttons on the page. - data-autoplay="{{false}}" Optional
-
true
||false
. Specifies whether the audio plays as soon as the page becomes visible.
Examples
Inline Audio Implementation
The following example shows the HTML specifying an inline Audio Widget, it shows controls on the page and the source is located relative to the page. A unique ID is not strictly required but is strongly recommended.
- id Optional
- A unique id for the HTML element.
- data-widget="AUDIO" Required Audio Widget identifier.
- data-src="{{src}}" Required
- The audio source.
- data-audio-type="INLINE" Required
- Required to specify the player as an inline player.
- data-controls="{{true||false}}" Required
- Specifies whether or not to show native controls.
<!-- Inline Audio Example -->
<div id="uniqueid1"
data-widget="AUDIO"
data-src="../assets/audio.mp3"
data-audio-type="inline"
data-controls="true">
<!-- Optional content placed inside the audio container -->
<img src="../assets/audio.png"/>
<span>Inline Player</span>
</div>
App Audio Implementation
The following example shows the HTML specifying an Audio Widget that uses the native app audio, the source used is based in the cloud and the widget will start playing as soon as the page is navigated to. A unique ID is not strictly required but is strongly recommended.
- id Optional
- A unique id for the HTML element.
- data-widget="AUDIO" Required
- Audio Widget identifier.
- data-src="{{src}}" Required
- The audio source.
- data-audio-type="APP" Required
- Required to specify the player as an app player.
- data-autoplay="{{true||false}}" Required
- Specifies whether or not the audio should autoplay.
<!-- App Player Example-->
<div id="uniqueid1"
data-src="http://somewebsite.com/audio.mp3"
data-widget="AUDIO"
data-audio-type="app"
data-autoplay="true">
<!-- Optional content placed inside the audio container -->
<img src="../assets/audio.png"/>
<span>App Player</span>
</div>
Button Operated Audio Implementation
The following example shows the HTML for an audio widget that is controlled via on-page buttons, the native audio controls are hidden (the widget will still work if controls are specified as visible, there is no conflict with between native controls and controls placed as buttons in the page). As the audio widget is controlled via buttons a specified unique ID is required.
- id Required
- A unique id for the HTML element.
- data-widget="AUDIO" Required
- Audio Widget identifier.
- data-src="{{src}}" Required
- The audio source.
- data-audio-type="INLINE" Optional
- Required to specify the player as an inline player.
- data-controls="false" Optional
- Specifies whether or not the audio should display controls.
<!-- Inline Player-->
<div id="uniqueid1"
data-src="../assets/audio.mp3"
data-widget="AUDIO"
data-audio-type="app"
data-controls="false">
<!-- Optional content placed inside the audio container -->
<!-- Note that the on-page controls could be placed in here -->
<img src="../assets/audio.png"/>
<span>Inline Player</span>
</div>
<!-- Play Button-->
<div id="uniqueid2"
data-widget="BUTTON"
data-action="PLAY_MEDIA"
data-target="uniqueid1">
<!-- HTML content for the button -->
<img src="../assets/play.png"/>
</div>
<!-- Pause Button -->
<div id="uniqueid3"
data-widget="BUTTON"
data-action="PAUSE_MEDIA"
data-target="uniqueid1">
<!--HTML content for the button-->
<img src="../assets/pause.png"/>
</div>
- Source:
- widgets/AudioWidget.js, line 2
Extends
- PR.BaseWidget
Members
-
audioJSONString
-
Audio details in JSON object
- Source:
- widgets/AudioWidget.js, line 266
-
autoplayFunctionFunction
-
References the function that autoplays the player
- Source:
- widgets/AudioWidget.js, line 251
-
autostopFunctionFunction
-
References the function that autostops the player
- Source:
- widgets/AudioWidget.js, line 256
-
elHTMLDivElement
-
The element that the widget is attached to
- Source:
- widgets/AudioWidget.js, line 230
-
notifyMessage_String
-
The notify message associated with an App Player
- Source:
- widgets/AudioWidget.js, line 235
-
pauseFunctionFunction
-
References the function that pauses the player
- Source:
- widgets/AudioWidget.js, line 246
-
playFunctionFunction
-
References the function that plays the player
- Source:
- widgets/AudioWidget.js, line 241
-
toggleFunctionFunction
-
References the function that toggle the player
- Source:
- widgets/AudioWidget.js, line 261
Methods
-
appAutoPlay( )
-
Checks that the autoplay is set to true and plays the audio if it is
- Source:
- widgets/AudioWidget.js, line 594
-
appAutoStop( )
-
Autostops the app player
Does not perform any checks, just notifies the app to stop the player- Source:
- widgets/AudioWidget.js, line 609
-
audio( elem, player, str )
-
Tells the application to start playing the Audio file
Parameters:
Name Type Description elem
Object the DOM element of the function call
player
String the type of audio player to use
str
String the audio file's relative location
- Source:
- widgets/AudioWidget.js, line 370
-
audioPause( )
-
Pauses the currently playing audio
- Source:
- widgets/AudioWidget.js, line 406
-
autoplayAudio( )
-
Grabs all the audio elements with the 'autoplay' parameter
and plays them by triggering an onClick event- Source:
- widgets/AudioWidget.js, line 392
-
autoStopInline( )
-
Autostops the object - does not perform any checks, it just stops the player
- Source:
- widgets/AudioWidget.js, line 489
-
initialize( el )
-
Acts like a constructor, this function triggered by default when you create an object.
Creates an audio element if one does not already existParameters:
Name Type Description el
Object the DOM element associated with the widget
- Source:
- widgets/AudioWidget.js, line 295
-
inlineAutoPlay( )
-
Autoplays the object
- Source:
- widgets/AudioWidget.js, line 471
-
inlineDestroyPlayer( )
-
Destroys the player
- Source:
- widgets/AudioWidget.js, line 518
-
inlinePause( obj )
-
Pauses the audio object
Parameters:
Name Type Description obj
HTMLElement the object firing the event
- Source:
- widgets/AudioWidget.js, line 454
-
inlinePlay( obj )
-
Plays the audio object
Parameters:
Name Type Description obj
HTMLElement the object firing the event
- Source:
- widgets/AudioWidget.js, line 431
-
inlineToggle( )
-
Toggles the object playing or pausing
- Source:
- widgets/AudioWidget.js, line 505
-
subscribeEvents_( )
-
Subscribe to events - add event handlers
- Source:
- widgets/AudioWidget.js, line 625
-
unSubscribeEvents_( )
-
Unsubscribe from events
- Source:
- widgets/AudioWidget.js, line 642