sanity-plugin-goth-vimeo-input v1.0.4

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).

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:

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.