Class: AudioWidget

PR. AudioWidget

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>
Author:
  • AppStudio Widgets
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 exist

Parameters:
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
Top