sanity-plugin-goth-vimeo-input

A Sanity Plugin for Inputting Vimeo Videos by their URL and Pre-Loading oEmbed Data.

Usage no npm install needed!

<script type="module">
  import sanityPluginGothVimeoInput from 'https://cdn.skypack.dev/sanity-plugin-goth-vimeo-input';
</script>

README

Sanity Plugin Goth Vimeo Input

???? sanity-plugin-vimeo-input was taken so it's named sanity-plugin-goth-vimeo-input.

A Sanity Plugin for Inputting Vimeo Videos by their URL and Pre-Loading oEmbed Data.

Through this plugin, your users will simply be required to input a valid Vimeo video URL. The plugin will use the Vimeo oEmbed API to then verify the video and import the full oEmbed payload for the video, which includes the video's title, ID, iFrame embed code, and thumbnail URL.

Additionally, the plugin allows the developer to set both defaults and available configuration options for the user to further customize the player included in the oEmbed response (e.g.; setting the video to autoplay or to use custom player control colors).

Plugin Example

Install

While in your Sanity project directory, run the following command:

sanity install goth-vimeo-input

You can read more about Sanity Plugin usage in the official guide.

Usage

Basic

To have your user simply input a Vimeo URL without additional configuration, you may include the type, vimeoVideo, in your schema without additional options.

export default {
  name: "video",
  title: "Video",
  type: "document",
  fields: [
    {
      name: "vimeoVideo",
      title: "Vimeo Video",
      type: "vimeoVideo",
      validation: Rule => Rule.required()
    },
  ],
  preview: {
    select: {
      vimeoVideo: "vimeoVideo"
    },
    prepare(selection) {
      let oEmbedData = selection.vimeoVideo
        ? selection.vimeoVideo.oEmbedData
        : {};

      return {
        title: oEmbedData.title || ""
      }
    }
  }
};

See: https://vimeo.com/475247102

With Configuration

To include additional configuration, you may utilize either or both of the options provided with this plugin: configurableFields and defaultFieldValues. The configurableFields option tells the plugin which of the Vimeo oEmbed Arguments to allow your user to set when loading the video, and the defaultFieldValues option tells the plugin the default values for any such arguments (whether configurable by the user or not).

For example, the follow example will expose controls for toggling autoplay and controls on the player, and set default values for several other important oEmbed arugments:

export default {
  name: "video",
  title: "Video",
  type: "document",
  fields: [
    {
      name: "vimeoVideo",
      title: "Vimeo Video",
      type: "vimeoVideo",
      options: {
        configurableFields: [
          "autoplay",
          "controls"
        ],
        defaultFieldValues: {
          autopause: false,
          autoplay: true,
          background: false,
          byline: false,
          controls: false,
          dnt: true,
          loop: true,
          muted: true,
          portrait: false,
          quality: "auto",
          title: false,
          // Load a reasonably large thumbnail up front. Note this will add
          // relevant width/height attributes to the iframe. If youre making
          // your player responsive on the frontend this will be ok, but keep
          // it in mind.
          width: "960"
        }
      },
      validation: Rule => Rule.required()
    },
  ],
  preview: {
    select: {
      vimeoVideo: "vimeoVideo"
    },
    prepare(selection) {
      let oEmbedData = selection.vimeoVideo
        ? selection.vimeoVideo.oEmbedData
        : {};

      return {
        title: oEmbedData.title || ""
      }
    }
  }
};

See: https://vimeo.com/475247026

Additional Cases

User Updates to Configuration

:warning: Important

The user will be asked to reload the video any time they make changes to configurable fields. This is because configuration options are used during the request to Vimeo for oEmbed data, and as such updated configurations require an updated request to Vimeo. The plugin will alert the user to this automatically.

See: https://vimeo.com/475246939

Non-Existent Vimeo URLs / Fail Case

Should the user ever attempt to load a non-existent or errant Vimeo URL, the plugin will alert the user automatically.

See: https://vimeo.com/475247012

Configuration

All configurable fields exposed through the configurableFields option match the configuration arguments available for use with Vimeo's oEmbed API. To expose a field for user configuration, simply add its name to the configurableFields array within the options object when adding the vimeoVideo type to your schema (see "Usage" section above). Further, each configurable field exposed to the user will include the description from the matching argument in Vimeo's API. To override any default value, use defaultFieldValues (see "Usage" section above).

This is taken directly from Vimeo's documentation:

ArgumentDefault ValueDescription
urlNoneThe URL of the video on Vimeo. This is a required value.
apitrueWhether to enable the Vimeo player SDK.
autopausetrueWhether to pause the current video when another Vimeo video on the same page starts to play.
autoplayfalseWhether to start playback of the video automatically. This feature might not work on all devices.
backgroundfalseFor videos on a Vimeo Plus account or higher: whether to hide all video controls, loop the video automatically, enable autoplay, and mute the video. The loop and autoplay behaviors can't be overridden, but the mute behavior can be; see the muted argument below.
bylinetrueWhether to display the video owner's name.
callbackNoneThe name of JavaScript function to use as the callback parameter of a JSONP call. The indicated function wraps the JSON response.
controlstrueWhether to display (true) or hide (false) all interactive elements in the player interface. To start video playback when controls are hidden, set autoplay to true or use our player API. This argument is available only for Vimeo Pro and Business accounts.
colorNoneThe hexadecimal color value of the video controls, which is normally 00ADEF.
dntfalseWhether to prevent the player from tracking session data, including cookies. Keep in mind that setting this argument to true also blocks video stats.
funtrueWhether to disable informal error messages in the player, such as Oops.
heightNoneThe height of the video in pixels.
loopfalseWhether to restart the video automatically after reaching the end.
maxheightNoneThe height of the video in pixels, where the video won't exceed its native height, no matter the value of this field.
maxwidthNoneThe width of the video in pixels, where the video won't exceed its native width, no matter the value of this field.
mutedfalseWhether to mute playback by default. The user can increase the volume manually.
player_idNoneThe unique ID for the player, which comes back with all JavaScript API responses.
playsinlinetrueWhether the video plays inline on supported mobile devices.
portraittrueWhether to display the video owner's portrait.
qualityautoFor videos on a Vimeo Plus account or higher: the playback quality of the video. Use auto for the best possible quality given available bandwidth and other factors. You can also specify 360p, 540p, 720p, 1080p, 2k, and 4k.
responsivefalseWhether to return a responsive embed code, or one that provides intelligent adjustments based on viewing conditions. We recommend this option for mobile-optimized sites.
speedfalseFor videos on a Vimeo Plus account or higher: whether to include playback speed among the player preferences.
texttrackNoneThe text track to display with the video. Specify the text track by its language code (en), the language code and locale (en-US), or the language code and kind (en.captions). For this argument to work, the video must already have a text track of the given type; see our Help Center or Working with Text Track Uploads for more information.
titletrueWhether to display the video's title.
transparenttrueWhether the background of the player area is transparent on Vimeo. When this value is false, the background of the player area is black. Depending on the video's aspect ratio, there might be visible black bars around the video.
widthNoneThe width of the video in pixels.
xhtmlfalseWhether to make the embed code XHTML-compliant.

Payload

Once loaded, a field of type vimeoVideo will include the following.

url

The Vimeo video URL input by the user.

oEmbedDataLastFetchedAt

The last date at which the user updated the oEmbed data for the video by clicking "load".

oEmbedDataJsonResponse

The raw JSON response, encoded as a string, returned by the Vimeo oEmbed API.

vimeoOEmbedData

All fields returned by the Vimeo oEmbed API, as individual Sanity fields within a sub-object on the sanity vimeoVideo object. See the source code here and "oEmbed response fields" here.

vimeoOEmbedConfigData

All configuration used by the plugin when the oEmbed data was last updated, as individual Sanity fields within a sub-object on the sanity vimeoVideo object. See the source code here.