core_media_player_external Class Reference

Base class for players which handle external links (YouTube etc). More...

Inheritance diagram for core_media_player_external:

Public Member Functions
	embed ($urls, $name, $width, $height, $options)
	Generates code required to embed the player.
	get_embeddable_markers ()
	Lists keywords that must be included in a url that can be embedded with this player.
	get_rank ()
	Gets the ranking of this player.
	get_supported_extensions ()
	Gets the list of file extensions supported by this media player.
	is_enabled ()
	list_supported_urls (array $urls, array $options=array())
	Given a list of URLs, returns a reduced array containing only those URLs which are supported by this player.
	setup ($page)
	Setup page requirements.
	supports ($usedextensions=[])
	Returns human-readable string of supported file/link types for the "Manage media players" page.

Static Public Member Functions
static	compare_by_rank ()

Public Attributes
string const	END_LINK_REGEX_PART = '[^#]*(#d=([::d]{1,4})x([::d]{1,4}))?~si'
	Part of a regular expression, including ending ~ symbol (note: these regexes use ~ instead of / because URLs and HTML code typically include / symbol and makes harder to read if you have to escape it).
const	LINKPLACEHOLDER = '<!--LINKFALLBACK-->'
	Placeholder text used to indicate where the link fallback is placed.
const	PLACEHOLDER = '<!--FALLBACK-->'
	Placeholder text used to indicate where the fallback content is placed within a result.

Protected Member Functions
	embed_external (moodle_url $url, $name, $width, $height, $options)
	Obtains HTML code to embed the link.
	get_name ($name, $urls)
	Obtains suitable name for media.
	get_regex ()
	Returns regular expression used to match URLs that this player handles.

Static Protected Member Functions
static	fix_match_count (&$matches, $count)
	Annoyingly, preg_match $matches result does not always have the same number of parameters - it leaves out optional ones at the end.
static	pick_video_size (&$width, &$height)
	Utility function that sets width and height to defaults if not specified as a parameter to the function (will be specified either if, (a) the calling code passed it, or (b) the URL included it).

Protected Attributes
array	$matches
	Array of matches from regular expression - subclass can assume these will be valid when the embed function is called, to save it rerunning the regex.

Detailed Description

Base class for players which handle external links (YouTube etc).

As opposed to media files.

Copyright

2016 Marina Glancy

Author

2011 The Open University

License

http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

compare_by_rank()

static core_media_player::compare_by_rank ( )

staticinherited

Deprecated

since Moodle 3.2

embed()

core_media_player_external::embed	(		$urls,
			$name,
			$width,
			$height,
			$options )

Generates code required to embed the player.

The returned code contains a placeholder comment '' (constant core_media_player\PLACEHOLDER) which indicates the location where fallback content should be placed in the event that this type of player is not supported by user browser.

The $urls parameter includes one or more alternative media formats that are supported by this player. It does not include formats that aren't supported (see list_supported_urls).

The $options array contains key-value pairs. See OPTION_xx constants for documentation of standard option(s).

Parameters

array	$urls	URLs of media files
string	$name	Display name; '' to use default
int	$width	Optional width; 0 to use default
int	$height	Optional height; 0 to use default
array	$options	Options array

Return values

string

HTML code for embed

Reimplemented from core_media_player.

embed_external()

core_media_player_external::embed_external ( moodle_url $url, $name, $width, $height, $options )

abstractprotected

Obtains HTML code to embed the link.

Parameters

moodle_url	$url	Single URL to embed
string	$name	Display name; '' to use default
int	$width	Optional width; 0 to use default
int	$height	Optional height; 0 to use default
array	$options	Options array

Return values

string

HTML code for embed

Reimplemented in media_vimeo_plugin, and media_youtube_plugin.

fix_match_count()

static core_media_player_external::fix_match_count ( & $matches, $count )

staticprotected

Annoyingly, preg_match $matches result does not always have the same number of parameters - it leaves out optional ones at the end.

WHAT. Anyway, this function can be used to fix it.

Parameters

array	$matches	Array that should be adjusted
int	$count	Number of capturing groups (=6 to make $matches[6] work)

get_embeddable_markers()

core_media_player::get_embeddable_markers ( )

inherited

Lists keywords that must be included in a url that can be embedded with this player.

Any such keywords should be added to the array.

For example if this player supports FLV and F4V files then it should add '.flv' and '.f4v' to the array. (The check is not case-sensitive.)

Default handling calls the get_supported_extensions function, so players only need to override this if they don't implement get_supported_extensions.

This is used to improve performance when matching links in the media filter.

Return values

array

Array of keywords to add to the embeddable markers list

Reimplemented in media_videojs_plugin, media_vimeo_plugin, and media_youtube_plugin.

get_name()

core_media_player::get_name ( $name, $urls )

protectedinherited

Obtains suitable name for media.

Uses specified name if there is one, otherwise makes one up.

Parameters

string	$name	User-specified name ('' if none)
array	$urls	Array of moodle_url used to make up name

Return values

string

Name

get_rank()

core_media_player::get_rank ( )

abstractinherited

Gets the ranking of this player.

This is an integer used to decide which player to use (after applying other considerations such as which ones the user has disabled).

This function returns the default rank that can be adjusted by the administrator on the Manage media players page.

Return values

int	Rank (higher is better)

Reimplemented in media_html5audio_plugin, media_html5video_plugin, media_videojs_plugin, media_vimeo_plugin, and media_youtube_plugin.

get_regex()

core_media_player_external::get_regex ( )

protected

Returns regular expression used to match URLs that this player handles.

Return values

string

PHP regular expression e.g. '~^https?://example.org/~'

Reimplemented in media_vimeo_plugin, and media_youtube_plugin.

get_supported_extensions()

core_media_player::get_supported_extensions ( )

inherited

Gets the list of file extensions supported by this media player.

Note: This is only required for the default implementations of list_supported_urls(), get_embeddable_markers() and supports(). If you override these functions to determine supported URLs in some way other than by extension, then this function is not necessary.

Return values

array

Array of strings (extension not including dot e.g. '.mp3')

Reimplemented in core_media_player_native, media_html5audio_plugin, media_html5video_plugin, and media_videojs_plugin.

is_enabled()

core_media_player::is_enabled ( )

inherited

Deprecated

since Moodle 3.2

list_supported_urls()

core_media_player_external::list_supported_urls	(	array	$urls,
		array	$options = array() )

Given a list of URLs, returns a reduced array containing only those URLs which are supported by this player.

(Empty if none.)

Parameters

array	$urls	Array of moodle_url
array	$options	Options (same as will be passed to embed)

Return values

array

Array of supported moodle_url

Reimplemented from core_media_player.

Reimplemented in media_youtube_plugin.

pick_video_size()

static core_media_player::pick_video_size ( & $width, & $height )

staticprotectedinherited

Utility function that sets width and height to defaults if not specified as a parameter to the function (will be specified either if, (a) the calling code passed it, or (b) the URL included it).

Parameters

int	$width	Width passed to function (updated with final value)
int	$height	Height passed to function (updated with final value)

Reimplemented in media_html5video_plugin, and media_videojs_plugin.

setup()

core_media_player::setup ( $page )

inherited

Setup page requirements.

The typical javascript requirements MUST not take action on the content directly. They are meant to load the required libraries and listen to events in order to know when to take action. The role of this method is not to provide a way for plugins to look for content to embed on the page. The self::embed() method is meant to be used for that.

Parameters

moodle_page

$page

The page we are going to add requirements to.

Since

Moodle 3.2

Reimplemented in media_videojs_plugin.

supports()

core_media_player::supports ( $usedextensions = [] )

inherited

Returns human-readable string of supported file/link types for the "Manage media players" page.

Parameters

array

$usedextensions

extensions that should NOT be highlighted

Return values

string

Reimplemented in media_videojs_plugin.

Member Data Documentation

END_LINK_REGEX_PART

string const core_media_player_external::END_LINK_REGEX_PART = '[^#]*(#d=([::d]{1,4})x([::d]{1,4}))?~si'

Part of a regular expression, including ending ~ symbol (note: these regexes use ~ instead of / because URLs and HTML code typically include / symbol and makes harder to read if you have to escape it).

Matches the end part of a link after you have read the 'important' data including optional #d=400x300 at end of url, plus content of tag, up to .

LINKPLACEHOLDER

const core_media_player::LINKPLACEHOLDER = '<!--LINKFALLBACK-->'

inherited

Placeholder text used to indicate where the link fallback is placed.

No other players will apply to it but it will be converted to the link in the end (unless prevented by OPTION_NO_LINK).

---

The documentation for this class was generated from the following file:

• media/classes/player_external.php