oui_player

Introduction

An extendable plugin to easily embed customized audio and video players.

. This plugin does not use oembed, it builds iframe embedding codes and HTML5 players by its own without any external request for better performances.

Supported extensions

As known at the last plugin release…

• Abc News: oui_abcnews;
• Archive: oui_archive;
• Bandcamp: oui_bandcamp;
• Dailymotion: oui_dailymotion;
• Giphy: oui_giphy;
• HTML5 audio: oui_audio;
• HTML5 video: oui_video;
• Mixcloud: oui_mixcloud;
• Myspace videos: oui_myspace;
• Soundcloud: oui_soundcloud;
• Twitch: oui_twitch;
• Viddsee: oui_viddsee;
• Vimeo: oui_vimeo;
• Vine: oui_vine;
• Youtube: oui_youtube.

Plugin requirements

oui_player’s minimum requirements:

• Textpattern CMS 4.6+;
• oui_provider v1+;
• Any of the above provider related extension.

Plugin management

Installation

From the admin interface

Follow the below instructions before or after installing the wanted oui_player extensions:

1. Download the .txt or _zip.txt compiled plugin file;
2. Upload its contents through the Admin > Plugins tab;
3. Confirm the plugin install on the preview page.
4. Enable the plugin and click the Options link to set the plugin preferences.

Via Composer (not available yet)

After installing Composer

1. Target your project directory:
   $ cd /path/to/your/textpattern/installation/dir
2. If it’s not already done, lock your version of Txp:
   $ composer require textpattern/lock:4.6.2, where 4.6.2 is the Txp version in use.
3. Install oui_player:
   $ composer require nicolasgraph/oui_player
4. Connect to the Txp admin interface and click Options or visit your “Admin > Preferences”:?event=prefs#prefs_group_oui_player tab to fill the plugin prefs.

Update

From the admin interface

Follow the install instructions.
If you are updating from v1.*, be sure to install all wanted extensions before to visit the “Admin > Preferences”:?event=prefs#prefs_group_oui_player tab to keep your preference values untouched.

Via Composer (not available yet)

$ composer update nicolasgraph/oui_player

Uninstall

From the admin interface

1. In the Admin > Plugins tab, check the box on the left of the plugin related row.
2. Under the plugins list, select the the Delete option.
3. confirm the deletion.

Via Composer (not available yet)

$ composer remove nicolasgraph/oui_player

Preferences/options

Plugin prefs can be set under the Admin > Preferences tab and are mainly used as default values for the <txp:oui_player /> tag attributes.

Global prefs

Field used by default

Defines a field to use as the default play attribute value.
The provided fieldname must be different than any value entered in it; avoid digits if you use ID’s as play attribute values
Default: article_image
valid: article_image or any existing custom field

Favourite provider

Set the default provider attribute value.
Default: the first plugged provider
valid: Any plugged provider in the select list

Display the provider player preferences

Displays the defined provider prefs as a goup of prefs.
Default: yes
valid: yes or no

Providers prefs

While some player parameters, related to the item to play, should be used through attributes (e.g. the Youtube start parameter which defines the second where to start playing the video), these used as global settings should preferrably be set through the plugin preferences to avoid a massive use of tag attributes.

Of course, it is still possible to override a plugin pref value via an attribute when needed.

Tags

oui_player

Embeds a player.

<txp:oui_player />

Presentational attributes

label

String; empty by default.
Label for the video.

labeltag

HTML container tag name; empty by default.
HTML wraptag for the label, without brackets.

wraptag

HTML container tag name; empty by default.
HTML tag to be used as the content wraptag, without brackets.

class

String; empty by default.
CSS class for HTML content wraptag.

responsive

true or false, related preference value used by default.
Adapts the final player size from provided width and/or height and/or ratio values to fit the container width.
Wraps the player and adds some styles.

Main tag attributes

Most of the following attributes can be set via the Preferences tab; always prefer plugin “global” prefs to tag related attributes!

play

Valid values differs from one provider to another, check each extension.
The item to play; required if it does not use the value of the custom field selected in the plugin prefs (See each provider to know the valid values).
default: changed v1.2.0 the play attribute value of an eventual <txp:oui_if_play></txp:oui_if_play> container tag, or the custom field value of the one selected in the plugin prefs.

provider

Extension related provider name; uses the related preference value by default.
The provider to use; required if the play attribute is an id, recommended anyways if known as it increases the plugin performances by skipping the provider guess.

Providers related tag attributes

See each provider related extension.

oui_if_player

Checks the play attribute value againsts defined URL schemes.

<txp:oui_if_player>
[…]
</txp:oui_if_player>

Attributes

play

The custom field value of the one selected in the plugin prefs by default.
The item to play; required if it does not use the value of the custom field selected in the plugin prefs (See each provider to know the valid values).

provider

Extension related provider name; empty by default.
Check the URL against valid URL schemes of the defined provider.

Examples

Display a player from the default values collected via plugin prefs

<txp:oui_player />

Display a player from a manually filled URL

<txp:oui_player play="https://vimeo.com/155020267" />

…or, maybe a bit faster…

<txp:oui_player provider="vimeo" play="https://vimeo.com/155020267" />

Display a player from manually filled ID

Using the favourite provider set in the prefs.

<txp:oui_player play="x4l8awd" />

…or, in conjonction with the provider attribute…

<txp:oui_player provider="dailymotion" play="x4l8awd" />

Display a player only if its URL is recognized as a provider URL scheme

With the default values collected via plugin prefs…

<txp:oui_if_player>
    <txp:oui_player />
</txp:oui_if_player>

…or, with a manually filled URL…

<txp:oui_if_player play="https://vimeo.com/155020267">
    <txp:oui_player />
</txp:oui_if_player>

You can also add the provider attribute to check the URL against URL schemes of a defined provider.

Credits

Author

Nicolas Morand
Thank you to the Textpattern community and the core team.

License

This plugin is distributed under GPL v2.0.

oui_player version 2.0.0-BETA3, Copyright © 2018 Nicolas Morand
This Textpattern plugin comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under certain conditions.

Changelog

• v2.0.0-BETA3 (2018-08-15)
  • Added: admin side player preview;
  • Changed: excerpt field no longer supported;
  • Added: responsive embedding;
    • changed: providers related preferences displayed by default;
  • changed: code rework:
    • providers now work as pluggable extensions:
      • Extension base (required): oui_provider; any plugin extending the \Oui\Provider class in an author prefix related namespace will be plugged into oui_player;
      • ABC News: oui_abcnews;
      • Archive: oui_archive;
      • Bandcamp: oui_bandcamp;
      • Dailymotion: oui_bandcamp;
      • Giphy: oui_giphy (new);
      • Mixcloud: oui_mixcloud;
      • MySpace: oui_myspace;
      • HTML5 audio: oui_audio;
      • HTML5 video: oui_video;
      • Soundcloud: oui_soundcloud;
      • Twitch: oui_twitch;
      • Viddsee: oui_viddsee;
      • Vimeo: oui_vimeo;
      • Vine: oui_vine;
      • Youtube: oui_youtube;
    • author prefix related namespace;
    • new class names (Admin => PlayerAdmin, Main => Player, Player => PlayerBase);
    • tags now registered with related callback methods from the Player class;
    • providers stored with their plugin author related prefix/namespace.
    • instances created/get via Txp::get().
• v1.3.1 (2017-07-13)
• v1.3.0 (2017-05-24)
  • Adds Composer support for textpattern/installer;
  • fixes multiple players prefs display and improves perfs;
  • improves scripts embedding;
  • added: Youtube player parameters enablejsapi and origin;
  • added: Dailymotion player parameters api and origin;
  • added: Vimeo player parameter api and removes badge;
  • added: support for:
    • Bandcamp;
    • HTML5 audio + video;
• v1.2.1 (2017-01-16)
  • Fixed: Fixes the Field used by default pref display when no custom field exists;
  • fixed: fixes Textpack typo;
  • changed: compiled code lightened by removing duplicated license related comments;
• v1.2.0 (2016-12-12)
  • added: sets the custom field plugin pref as the defaut value of the conditional tag play attribute;
  • added: introduces a play attribute value inheritance in a conditional/container tag context;
  • added: support for:
    • Twitch channels,
    • Vine;
  • changed: improves PHP classes and methods use (see For developers).
• oui_player v1.1.0 (2016-10-14)
  • changed: plugin/tag names;
  • removed: Txp 4.5 support;
  • changed: consistency between attribute and player parameter names increased;
  • changed: code rework to be easily extendable;
  • added: support for:
    • Abc News,
    • Archive,
    • Mixcloud,
    • Myspace videos,
    • Soundcloud,
    • Twitch,
    • Viddsee;
  • (changed) Help file styling improvements.
• oui_video v0.1.0 (2016-09-13)
• oui_dailymotion v1.3.1 (2016-02-25) inspired by arc_youtube and arc_vimeo by Andy Carter.