Embed for Kirby 2 CMS

Embed extends Kirby with some extensive media embed functionalities. It enables Kirby to display embeds from various media sites (e.g. YouTube, Vimeo, Soundcloud, Instagram etc.) by only providing the URL to the medium. It is powered by the oscarotero/Embed library.

With the release of Kirby 3, this plugin has been archived and will not be maintained.

Table of Contents

1. Requirements
2. Installation & Update
3. Usage
4. Options
5. Panel field
6. Advanced
7. Styles, Scripts & Translations
8. Examples
9. Help & Improve
10. Version History

Requirements

Kirby CMS 2.3.0+ and PHP 5.5+.

Installation & Update

1. Download Embed and add the files to site/plugins/embed/
2. Add the necessary styles by including the following in the header:

<?= css('assets/plugins/embed/css/embed.css') ?>

With video lazyload option (activated by default, include unless deactived)

3. Add the necessary script by including the following right before the </body> tag:

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

With the Kirby CLI

kirby plugin:install distantnative/embed

And add CSS and JS as outlined above.

Usage

As field method in templates:
Use the method on fields that contain a url that points to a supported medium (e.g. YouTube, Vimeo, Twitter, Instagram, Spotify etc.):

<?= $page->tweet()->embed(); ?>

You can use any text field containing a valid URL, but you might want to use the designated Embed panel field.

As Kirbytext tag:

You'll be given love. You'll be taken care of. You'll be given love. You have to trust it. Maybe not from the sources. You have poured yours. Maybe not from the directions. You are staring at.

(embed: https://vimeo.com/43444347)

Twist your head around. It's all around you. All is full of love. All around you. All is full of love. You just ain't receiving. All is full of love. Your phone is off the hook. All is full of love. Your doors are all shut. All is full of love.

As global PHP helper function:

<?= embed('https://www.youtube.com/watch?v=m2ua3O_fdCY') ?>

Options

Per embed

You can set the following options on each embed to apply:

// with the field method
<?= $page->featured_video()->embed([
  'lazyvideo' => true
]) ?>

// with the Kirbytext tag
(embed: https://www.youtube.com/watch?v=IlV7RhT6zHs lazyvideo: true)

Global

You can set the following options in your site/config/config.php to generally apply to all embeds:

c::set('plugin.embed.video.autoplay', false);

c::set('plugin.embed.video.lazyload', true);
c::set('plugin.embed.video.lazyload.btn', 'assets/plugins/embed/images/play.png');

c::set('plugin.embed.caching', true);
c::set('plugin.embed.caching.duration', 24); // in hours

c::set('plugin.embed.w3c.enforce', false);

c::set('plugin.embed.providers.jsapi', false);
c::set('plugin.embed.providers.google.key', null);
c::set('plugin.embed.providers.soundcloud.key', null):

URL parameters

Embed supports various URL parameters of provider that usually get lost during the embed call. To see which parameters are supported, please use the panel field and switch on the cheatsheet option.

Panel field

Embed also includes its own panel field which provides a preview of the embedded medium right inside the panel:

// in your blueprint
…
fields:
  …
  featured_video:
    label: Featured video
    type:  embed

With its additional options you can also disable the preview section, the information section as well as the cheatsheet or set a max-height for the preview:

fields:
  …
  featured_video:
    label:      Featured video
    type:       embed
    preview:    false
    info:       false
    cheatsheet: false
    height:     250px

Advanced

Embed does not only provide you an easy way to output the embed code, but also gives you access to a whole array of additional information provided by the oscarotero/Embed library.

// instead of echoing the field method, use it for further details:
$page->video()->embed()->title()

$info = $page->video()->embed();
echo $info->description();
echo $info->authorName();

You can find a full overview of what information can be accessed in the documentation of the oscarotero/Embed library or also just test your media URL and see what information is available.

Styles, Scripts & Translations

Embed comes with very minimal styles, mainly for embedded videos and only a small script necessary when lazyloading videos (activated by default):

// Include styles
<?= css('assets/plugins/embed/css/embed.css') ?>

// Include script
<?= js('assets/plugins/embed/js/embed.js') ?>

If you want to further customize and work with the embedded medium. The following CSS classes are applied to the main wrapper:

.embed
.embed--{TYPE}      // e.g. video, rich
.embed--{PROVIDER}  // e.g. YouTube, Vimeo

.embed__thumb
.embed__thumb > img

You can also translate the strings used by Embed. Translations for English and German are already included. To find out what keys to use, check out the English translation file.

Examples

Blog: Featured Embed

// site/blueprints/article.yml
…
fields:
  …
  cover:
    Cover photo
    type: image
  featured:
    label: Featured embed (instead of cover photo)
    type:  embed

// site/snippets/article.php
<article>
  <aside class="entry-meta">...</aside>
  <div class="entry-main">
    <?php if($page->featured()->isNotEmpty()): ?>
      <figure class="entry-cover">
        <?= $page->featured()->embed() ?>
      </figure>
    <?php elseif($page->cover()->isNotEmpty()) : ?>
      <figure class="entry-cover">
        <?= $page->cover() ?>
      </figure>
    <?php endif; ?>
    <div class="entry-content"><?= $page->text()->kt() ?></div>
  </div>
</article>

Screenshots

Video from Vimeo:

Tweet from Twitter:

Player from Spotify:

Help & Improve

If you have any suggestions for further configuration options, please let me know.

Version history

You can find a more or less complete version history in the changelog.

License

MIT License

Author

Nico Hoffmann - https://nhoffmann.com