Embedding Giphy GIFs

In this tutorial we're going to show you how to embed Giphy GIFs on web pages with Scrivito. It guides you through building a Giphy Widget from scratch and using a third-party service.

This tutorial requires some basic knowledge of the Scrivito workflow and React. It is based on the Scrivito Example App but can be used to extend any Scrivito app.

Get started – install the Giphy SDK

We'll implement a “GiphyWidget” so that editors can place random GIFs on any page simply by selecting the widget from the widget browser. Additionally, we will limit the randomness by providing a tag option. For finding GIFs, we'll use the giphy-js-sdk-core package. So let's include this component in the Scrivito app first.

Scrivito dependencies are managed with npm. To add the giphy-js-sdk-core package to your app, just open a terminal, go to your project directory, and execute

Copy
~$ npm install --save giphy-js-sdk-core

To make sure the package has been installed, open the “package.json” file and find the “dependencies” hash. It should include the component and look something like this:

Copy
"devDependencies": {
 // ...
 "giphy-js-sdk-core": "^1.0.2",
 // ...
}

Define the widget model

First things first, so let's add the file for the new widget model class in the project at “src/Widgets/GiphyWidget/” named “GiphyWidgetClass.js”.

In this file, we make the widget model known to Scrivito by calling  Scrivito.provideWidgetClass and passing  the widget class name, “GiphyWidget”, to it. Next to this name, we pass an attributes definition to it consisting of just a single attribute, tag, that lets us restrict our image request later on.

src/Widgets/GiphyWidget/GiphyWidgetClass.js
Copy
import * as Scrivito from 'scrivito';
Scrivito.provideWidgetClass('GiphyWidget', {
  attributes: {
    tag: 'string',
  },
});

Render the widget instances

For rendering instances of the “GiphyWidget”, we’ll now create a React component (and make it known to Scrivito). We suggest using an ES6 class to define such components (extends React.Component). Inside the render function, we can access the widget instance via the corresponding widget prop to fetch the widget attribute values.

src/Widgets/GiphyWidget/GiphyWidgetComponent.js
Copy
import * as React from 'react';
import * as Scrivito from 'scrivito';
import GphApiClient from 'giphy-js-sdk-core';

class GiphyWidgetComponent extends React.Component {
  constructor(props) {
    super(props);

    this.state = { gif: '', };
  }

  componentDidMount() {
    const tag = this.props.widget.get('tag');
    const client = GphApiClient('dc6zaTOxFJmzC');

    client.random('gifs', { tag: tag })
      .then(response => {
        this.setState({
          gif: response.data.images.fixed_height_downsampled.gif_url,
        });
      })
  }

  render() {
    return (
      <div className='text-center img-responsive'>
        <img src={ this.state.gif } alt="" />
      </div>
    );
  }
}

Scrivito.provideComponent('GiphyWidget', GiphyWidgetComponent);

As you can see, we are importing the Giphy SDK and using it for requesting an image and saving its URL to the component’s gif state prop when the component is mounted. This causes a new GIF to be requested each time the widget is inserted into the DOM. The render function outputs the Giphy image referenced in this gif state prop.

Finally, to have Scrivito use the “GiphyWidgetComponent” for rendering instances of the “GiphyWidget”, we associate the widget class with the component using Scrivito.provideComponent.

Make the attributes editable

We want the tag attribute to be editable via the properties dialog of each widget, so let's provide Scrivito with a UI configuration for the “GiphyWidget”. This can be done using Scrivito.provideEditingConfig:

src/Widgets/GiphyWidget/GiphyWidgetEditingConfig.js
Copy
import * as Scrivito from 'scrivito';
Scrivito.provideEditingConfig('GiphyWidget', {
  title: 'GiphyWidget',
  description: 'A widget with a random GIF',

  properties: [
    'tag',
  ],

  attributes: {
    tag:{
      title: 'Tag',
      description: 'Input a tag to limit by tag.',
    },
  },
});

We're done!

Now that everything is in place, fire up your Scrivito app via npm start from your project directory, then open the site in your browser (if you haven't already done so). Note that you need to add scrivito/ to the URL to be able to switch to Edit mode. So the URL should look something like this: http://localhost:8080/scrivito/

Click the + icon at the top or bottom edge of a widget and select the “Giphy” widget from the widget browser.

You will see a random GIF generated. If you would like to limit the randomness to a specific tag value, you can specify it in the widget properties.

Notes and resources

Finished!

To summarize: Every widget is comprised of

  • a model defining its attributes (Scrivito.provideWidgetClass),
  • a React component for rendering the instances (attached to the Scrivito widget class using Scrivito.provideComponent),
  • and a UI specification for making at least those attributes editable (Scrivito.provideEditingConfig) that cannot be accessed directly on the page.