Building a YouTube Video Plugin for CrafterCMS

Introduction

CrafterCMS is an open source CMS with a Git-based repository that enables developers, content authors, and ops to work together collaboratively to deliver stunning personalized, multi-channel experiences faster and easier than ever before. What makes it even more powerful is the ability to extend functionality via its plugin system to provide users with more features developed by members of the Crafter open source community, enterprise customers, and partner ecosystem. Plugins can be published to the Crafter Marketplace and made available to all.

In this tutorial, we are going to create a plugin to integrate YouTube videos into CrafterCMS. We can then search YouTube videos, insert them to Components or Pages on sites/apps, and deliver YouTube-based video experiences to site visitors/app users.

CrafterCMS provides two types of extensions that can be published to the Crafter Marketplace: Blueprints and Plugins; learn more about extensions in our docs. In this case, our YouTube Integration Plugin will be a Plugin.

NOTE: You must use CrafterCMS version 4.x or above to utilize this Plugin. It will not work with version 3.x. 

YouTube Integration Plugin Design

Our first goal is to create a custom Form Control to search YouTube by keyword and select a video with ID and some metadatas, including title, description and a thumbnail image. This will be implemented as a small React application that will be integrated into Crafter Studio, which is the content authoring system.

To search and store YouTube videos, we will need a Content Type, with the following fields

• YouTube ID
• Title
• Description
• Poster Image
• A React Widget to search and select YouTube videoYouTube ID
  

A final version for this plugin can be found in this repository: https://github.com/craftercms/youtube-plugin

Preliminaries

We need to use CrafterCMS version 4.0 or later to use this plugin. To learn about CrafterCMS version 4.0, check the official documentation here.

We have to create a site beforehand. For this tutorial, we create a site from the blueprint “Website Editorial Blueprint” on the Crafter Marketplace. This site blueprint uses Freemarker templates, so we will be extending these to render the YouTube videos.

A YouTube Data API v3 key is also needed. We will go back to how to get an API key later on this tutorial. 

Install Plugin

There are two ways to install a plugin: via the Crafter Studio UI in Plugin Management or via the crafter-cli package included with CrafterCMS.

Install via Plugin Management

To install a plugin via Plugin Management in the Studio UI.

Install with crafter-cli

While most of your operations are via the Crafter Studio UI, some features are also available in the command line interface (CLI). Crafter CLI  provide such commands including the installation of a plugin. Crafter CLI is available in the bin folder in your CrafterCMS installation.

Installing a plugin via the CLI  is convenient for developers to test and debug the plugin before actually submitting it to the Crafter Marketplace.

To learn more about Crafter CLI Commands in our docs.

First of all, we first need to set up the connection to CrafterCMS before actually using other available commands. To set up the connection, run the add-environment command, provide a name, the url for a CrafterCMS authoring server and the authentication information.

$ cd {CRAFTER_AUTHORING}/bin
$ ./crafter-cli add-environment -e local -u "http://localhost:8080" --username admin  --password
Enter value for --password (The password for authentication): 

Clone the plugin repository to your local environment:

$ cd {YOUR_WORKSPACE}
$ git clone git@github.com:phuongnq/site-plugin-youtube-picker.git

Install the plugin with command:

$ cd {CRAFTER_AUTHORING}/bin
$ ./crafter-cli copy-plugin --environment=local --path={YOUR_WORKSPACE}/site-plugin-youtube-picker --siteId={YOUR_CrafterCMS_SITE_ID}

OK

After above commands, a site plugin is installed in Crafter Studio. Checking following files are added:

youtubepicker-*.ftl for templates

YouTube Page and YouTube Picker content type:

On the next step, we need to add an additional form control plugin. Unfortunately, this is not automatically installed via crafter-cli for now. For that reason, we need to manually copy files and change site configuration. 

To learn more about Form Control Plugin, read about it in our docs.

$ mkdir -p {YOUR_SITE}/sandbox/config/studio/plugins/control/youtubepicker/ # If directory is not existed
$ cd {YOUR_WORKSPACE}/site-plugin-youtube-picker
$ cp authoring/control/youtubepicker/main.js {YOUR_SITE}/sandbox/config/studio/plugins/control/youtubepicker/main.js
$ cd {YOUR_SITE}/sandbox/
$ git add .
$ git commit -m "Update Plugin"

Update Site Config:

<control>
    <plugin>
        <type>control</type>
        <name>youtubepicker</name>
        <filename>main.js</filename>
    </plugin>
    <icon>
        <class>fa-youtube</class>
    </icon>
</control>

Add a Google API Key

Go to Content Types configuration, select YouTube Picker Component, click on Component ID “YouTube Picker” and input your Google API Key in Properties box.

A Google API Key is required to search YouTube videos. For this plugin, we are using YouTube Data API v3. To request an API key, refer to this document from Google.

Check files

If everything is setup correctly, we will see that a component and page are installed to Crafter Studio local repository:

$ cd {YOUR_SITE}/sandbox/
$ ls -la config/studio/content-types/component/plugins/org/craftercms/plugin/youtubepicker/youtubepicker
total 28
drwxrwxr-x 2 phuongnq phuongnq 4096 Mar 24 12:56 .
drwxrwxr-x 3 phuongnq phuongnq 4096 Mar 24 12:56 ..
-rw-rw-r-- 1 phuongnq phuongnq  605 Mar 24 12:56 config.xml
-rw-rw-r-- 1 phuongnq phuongnq  529 Mar 24 12:56 controller.groovy
-rw-rw-r-- 1 phuongnq phuongnq 8592 Mar 24 12:58 form-definition.xml
$ ls -la config/studio/content-types/page/plugins/org/craftercms/plugin/youtubepicker/youtubepicker
total 24
drwxrwxr-x 2 phuongnq phuongnq 4096 Mar 24 12:56 .
drwxrwxr-x 3 phuongnq phuongnq 4096 Mar 24 12:56 ..
-rw-rw-r-- 1 phuongnq phuongnq  591 Mar 24 12:56 config.xml
-rw-rw-r-- 1 phuongnq phuongnq  529 Mar 24 12:56 controller.groovy
-rw-rw-r-- 1 phuongnq phuongnq 5983 Mar 24 12:56 form-definition.xml
$ ls -la config/studio/plugins/control/youtubepicker/      
total 16
drwxrwxr-x 2 phuongnq phuongnq 4096 Mar 24 12:57 .
drwxrwxr-x 3 phuongnq phuongnq 4096 Mar 24 12:57 ..
-rw-rw-r-- 1 phuongnq phuongnq 6881 Mar 24 12:57 main.js

Create Content

So far, we installed YouTube Integration Plugin to Crafter Studio. Next, we will create a simple page to display a YouTube video as well as some metadata information.

Go to the site dashboard, create a page with content type “YouTube Page”:

Notice that we have “YouTube Widget” in Content Form, click “Add” to add a YouTube component:

Inside the form “YouTube Picker”, there are several inputs for YouTube ID, Title, Description, Poster Image but we don’t have to input them manually. Scroll down to the search box, input a keyword then press “Enter”. Search result video will be added automatically to all above inputs. We can also click on the videos list to update selected videos.

After creating a page, it should be previewable with our template

That’s it. We have just installed a plugin, and created some content around it to display YouTube videos.

Other than the default provided page, we can freely create separate components with “YouTube Picker” then later on integrate to other pages with a different template. While creating content, choose “YouTube Picker” component to create a separate component.

For Plugin Developers

Support for creating, managing and reusing Plugins is a critical feature to a fully functional content management system. With CrafterCMS’s Plugin framework and Crafter Marketplace, developers can easily develop and publish plugins that can be easily found and used by both the open source community and enterprise customers.