PHP
Clone or download
Latest commit 92175ab Jul 5, 2018

README.textile

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…

Plugin requirements

oui_player’s minimum requirements:

Plugin management

Installation

From the admin interface

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

  1. Download the compiled plugin file or the source to compile a customized file.
  2. Paste the content of the compiled plugin file under the “Admin > Plugins”:?event=plugin tab and click the Upload button.
  3. Confirm the plugin install by clicking the Install button on the plugin preview page.
  4. Enable the plugin.

Once the plugin and its extensions enabled, you will need to complete the setup by clicking Options or visiting your “Admin > Preferences”:?event=prefs#prefs_group_oui_player tab.
This last step need to be repeated each time you add or remove one or more oui_player extensions to update 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. Check the box on the left of the plugin row under the “Admin > Plugins”:?event=plugin.
  2. open the select list at the bottom of the plugins table and choose Delete.
  3. confirm the plugin deletion.

Via Composer (not available yet)

$ composer remove nicolasgraph/oui_player

Preferences/options

Plugin prefs can be set under the “Admin > Preferences”:?event=prefs#prefs_group_oui_player 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, excerpt 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

Render responsive player

Default: no
valid: yes or no

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; none by default.
Label for the video.

labeltag

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

wraptag

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

class

String; none 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 the related link in the table of contents.

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; none 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-BETA2, 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-BETA2 (2018-07-05)
    • Added: responsive embedding;
      • changed: providers related preferences displayed by default;
    • changed: code rework:
  • 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:
  • 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:
    • 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:
    • (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.