Skip to content

Latest commit

 

History

History
executable file
·
226 lines (131 loc) · 7.96 KB

README.md

File metadata and controls

executable file
·
226 lines (131 loc) · 7.96 KB
Raw

📹 HTML5-Video Kirbytag by @wottpal

Release MIT Tweet

(Disclaimer: This is a pre-release.)

The last kirbytag for HTML5-videos you'll ever need. 👊

  • Dynamic Video- & Image-Source Recognition
  • Lazy-Loading of all sources
  • Placeholder-Color until the video has loaded to increase Perceived-Performance1, 2
  • Use Fallback Images or GIFs
  • Configurable & Customizable to it's core

Demo of HTML5-Video Kirbytag

1 Works out of the box with kirby-dominant-color by @iandoe if fallback-image is provided
2 For consistency the fade-out transition looks exactly like the color-placeholder in ImageSet by @fabianmichael

🐼 Demos

🐸 Installation

Use Kirby's CLI and install the plugin via: kirby plugin:install wottpal/kirby-video or place the repo manually under site/plugins.

Include styles1 in your <head> with:

<?= css('assets/plugins/video/video.min.css') ?>`

Include scripts2 before the end of your </body> with:

<?= js('assets/plugins/video/video.min.js') ?>

1 Necessary for placeholder-color and ratio-sizing.
2 Necessary for lazy-loading and img/gif fallback.

Internet Explorer Support

If you want to support IE you either need to polyfill Array.from or rewrite some parts of video.js.

🐨 Usage

It's pretty straightforward to use this Kirbytag, the only rule to follow is basically: Give all your source-files (and fallback-image) the same filename. Only the file-extensions should differ.1

So, if you embed a video you only have to specify that base-filename and the plugin determines all matching files automagically. If you want to specify file-types/-formats or the source-order please see Options.

(video: funniest_thing_ever)

Video-Options & Presets

You can also manually specify options for the <video> element. In addition to the spec-compliant attributes you can also use lazyload to enable lazy-loading. Options are seperated by spaces.

Same as first:
(video: funniest_thing_ever options: lazyload controls)

GIF-like behavior:
(video: funniest_thing_ever options: lazyload autoplay loop muted playsinline)

These two options are also bundled in presets by default. You can add/modify presets by your own (see Options).

Same as first:
(video: funniest_thing_ever preset: default)

GIF-like behavior:
(video: funniest_thing_ever preset: gif)

Sizing

By default videos are displayed in their native resolutions. But you can specify width and height.2

(video: funniest_thing_ever width: 500px height: 300px)

Color

If you don't use kirby-dominant-color you can manually specify the placeholder-color with the color-option. This also overwrites the dominant-color if given. If neither a dominiant-color is available nor you've specified color then #fff is used. To change this default see Options.

No Figure-Wrapper

By setting figure to false you can disable the video-element to be wrapped by a <figure>. Please note that without a wrapper color-placeholders are disabled.

1They also should have the same dimensions. I haven't tested anything else.
2 Theoretically you can also specify these in options but if you also want to set a preset, these get overwritten by it.

🦊 Options

The following options can be set globally in your config.php with c::set($key, $value = null). You can also set multiple keys with c::set([$key => $value, ..]). 🤓

  • video.kirbytext.tagname (default: 'video')

The name of the tag to embed a video within kirbytext.

  • video.kirbytext.class (default: '')

Additional class which is added to all video-elements.

  • video.kirbytext.default.color (default: '#fff')

The default color of the placeholder.

  • video.kirbytext.merge.presets (default: [])

Add your own presets to the default presets or modify them. See Usage above for the two default presets default and gif.

  • video.kirbytext.video.types (default underneath)
[
  'webm' => 'video/webm; codecs="vp9"',
  'mp4' => 'video/mp4',
  'ogg' => 'video/ogg'
]

Specify all video-filetypes (and their respective type-attributes) you want the plugin to look for. The order is the same of the resulting <source> elements.

Note: It's totally fine if you don't supply all of these. But at least one has to be available, otherwise no <video> is generated.

  • video.kirbytext.image.formats (default: ['gif', 'jpeg', 'jpg', 'png'])

The image-extensions which are used to find a fallback-image. The first found file is used an the others are ignored.

  • video.kirbytext.figure (default: true)

Globally prevent video-embeds to be wrapped by a <figure> element. Please note that without a wrapper color-placeholders are disabled.

🐻 Changelog

Have a look at the releases page.

🦁 Roadmap

  • Option to disable Preview-Color
  • Option to disable <figure> wrapper
  • Option to specify ratio + ratio-placeholders to prevent page-reflow when ratio is given. (like in ImageSet)
  • Make it work with @bastianallgeier's columns-kirbytag & markdown.extra enabled
  • Maybe use responsive fallback images

🐯 For Reference

Interesting reads on <video> usage

Alternative Plugins/Snippets

👨‍💻 Development

For minification and transpilation I use Gulp. Please note that all files under assets/ are only the generated ones from src_assets/.

# Install Dependencies
npm i

# Or: Install Dependencies for Hipsters
yarn

# Build & Watch (Install 'gulp-cli' globally to omit the 'npx')
npx gulp

💰‍ Pricing

Just kidding. This plugin is totally free. Please consider following me on Twitter if it saved your day.

Twitter Follow

You can also check out one of my other Kirby-plugins:

  • Lightbox-Gallery - Easily inline beautifully aligned galleries with lightbox-support powered by PhotoSwipe.
  • Anchor-Headings - A kirby field-method which enumerates heading-elements, generates IDs for anchor-links and inserts custom markup based on your needs.