kirby-video
kirby-video copied to clipboard
wottpal
Adds a kirbytag for embedding HTML5-videos with a variety of features.
📹 HTML5-Video Kirbytag by @wottpal
(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
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
- www.dennisadelmann.de
- wottpal.com (my personal site)
- Submit yours
🐸 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
- [x] Option to disable
<figure>wrapper - [ ] Option to specify ratio + ratio-placeholders to prevent page-reflow when ratio is given. (like in ImageSet)
- [x] 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
- kirby-kirbytag-html5video by @jbeyerstedt
- snippet.video.php by @jancbeck
👨💻 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.
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.
wottpal