# Gigasavvy VideoFrame jQuery Plugin
Iframe embedded popups for common Video providers

## Installation

#### NPM

```npm install gsvideoframe --save```

#### Yarn

```yarn add gsvideoframe --save```



## Demo

See a [live demo](https://cdn.rawgit.com/loganstellway/gsVideoFrame/master/docs.html).



## Usage

Include jQuery

```<script type="text/javascript" src="http://code.jquery.com/jquery-3.3.1.min.js"></script>```

Include gsVideoFrame

```<script type="text/javascript" src="./dist/scripts/gsVideoFrame.min.js"></script>```



## Options

  - **src** ([string](http://api.jquery.com/Types/#String))
    - The `src` attribute is the URL to view the video.
      - The script will parse YouTube and Vimeo URL's and will create an iFrame embed from them.
      - _**Note:**_ YouTube URL's with `.com` and `.be` are currently supported.
  - **autoplay** ([number](http://api.jquery.com/Types/#Number)) [Default `1`]
    - This parameter determines whether or not the video automatically plays once it is opened
  - **params** ([object](http://api.jquery.com/Types/#Object))
    - **query** ([object](http://api.jquery.com/Types/#Object))
      - Object that defines the query string parameters to be appended to the embedded iFrame
        - [Vimeo Help Center - "Embedding Videos"](https://help.vimeo.com/hc/en-us/sections/203874347-Embedding-Videos)
        - [YouTube Player Parameters](https://developers.google.com/youtube/player_parameters)
    - **api** ([object](http://api.jquery.com/Types/#Object))
      - Object that defines the parameters to be passed to the video provider's API constructor
        - [Vimeo Embed Options](https://github.com/vimeo/player.js#embed-options)
        - [YouTube Embed Parameters](https://developers.google.com/youtube/player_parameters?playerVersion=HTML5#Parameters)
  - **target** ([string](http://api.jquery.com/Types/#String) | jQuery [object](http://api.jquery.com/Types/#Object)) [Default `false`]
    - The target where the video should be embedded.
      - This can be a selector string (ex: `"#gsVideoFrame"`)
      - Or this can be a jQuery object (ex: `$('#gsVideoFrame')`).
      - In the default case `false` or if the target cannot be found, the video will be appended to the `body` element.
  - **esc** ([boolean](http://api.jquery.com/Types/#Boolean))
    - Determines whether to add an event observer to listen for the escape key to close the video.
  - **time** ([object](http://api.jquery.com/Types/#Object))
    - Object that defines animation timing
      - *fadeIn* [Default `250`] - Time for video fade-in animation
      - *fadeOut* [Default `250`] - Time for video fade-out animation
  - **class** ([object](http://api.jquery.com/Types/#Object))
    - Object that defines HTML classes used throughout the script
      - *opening* [default `gsvideoframe-opening`] - Class applied to content as it is opening
      - *closing* [default `gsvideoframe-closing`] - Class applied to content as it is closing
      - *iframe* [default `gsvideoframe-frame`] - Class applied to embedded iFrame
  - **id** ([string](http://api.jquery.com/Types/#String))
    - Unique HTML ID given to the embedded iFrame
      - This defaults to "video" plus a timestamp
  - **container** ([string](http://api.jquery.com/Types/#String) | jQuery [object](http://api.jquery.com/Types/#Object))
    - HTML / Element to be used as the frame container. Use `false` to prevent the script from wrapping your content in a container
  - **closeButton** ([string](http://api.jquery.com/Types/#String) | jQuery [object](http://api.jquery.com/Types/#Object))
    - HTML / Element to be used as the close button. Use `false` to remove the close button

Example:
```
$('#element').gsVideoFrame({
  params: {
    api: {
      color: 'white'
    }
  },
  class: {
    iframe: 'video-player'
  },
  src: 'https://www.youtube.com/watch?v=Rk6_hdRtJOE',
  autoplay: 1
});
```



## Events

To create event listeners, pass an anonymous function as an option.

  - **gsvf:apiload**
    - Event called when the player API is loaded
  - **gsvf:beforeopen**
    - Event called before the video is embedded
  - **gsvf:open**
    - Event called after the video is embedded
  - **gsvf:play**
    - Event called when the video is played
  - **gsvf:pause**
    - Event called when the video is paused
  - **gsvf:ended**
    - Event called when the video has finished playing
  - **gsvf:ready**
    - Event called when the video is ready
  - **gsvf:error**
    - Event called when an error has occurred
  - **gsvf:beforeclose**
    - Event called before the video is closed
  - **gsvf:close**
    - Event called after the video is closed
  - **gsvf:destroy**
    - Event called when the player is "destroyed"

Example:

```
$('#element').on('gsvf:ready', function(event, options) {
  if (options.type == 'vimeo') {
    options.player.on('timeupdate', function(data) {
      console.log('Time Update:');
      console.log(data);
    })
  }
});
```


## Accessing the Player

The player can be accessed via the `player` property of the `gsvideoframe` object. The player object will vary depending on which video provider the video is initialized with.
  - [YouTube Player Options](https://developers.google.com/youtube/iframe_api_reference#Playback_controls)
  - [Vimeo Player Options](https://github.com/vimeo/player.js/#table-of-contents)

Example:

```
$('#element').data('gsvideoframe').player.pauseVideo()
```

## API

To utilize API methods, you can access the `gsvideoframe` data of the element used to initiate gsVideoFrame. 

  - **close()**
    - Closes the embedded video iFrame
  - **play()**
    - Plays the video
  - **pause()**
    - Pauses the video
  - **toggle()**
    - Toggles video play/pause state.
  - **stop()**
    - Stops the video
  - **seek()**
    - Seeks to a specified time in the video
      - [YouTube Javascript API::seekTo() method](https://developers.google.com/youtube/iframe_api_reference#seekTo)
      - [Vimeo Javascript API::setCurrentTime() method](https://github.com/vimeo/player.js#setcurrenttimeseconds-number-promisenumber-rangeerrorerror)
  - **destroy()**
    - Destroys the video (note: `beforeClose()` and `close()` events will not be called when `destroy()` is called)

Example:

```
$('#element').gsVideoFrame({ ...options });
$('#element').data('gsvideoframe').close();
$('#element').data('gsvideoframe').seek(123);
```



## Issues / Feedback

Please feel free to submit any issues you encounter or share your ideas :blush:

[Submit Issues / Give Feedback](https://github.com/loganstellway/gsVideoFrame/issues)