Creating a Custom oEmbed Request Handler

Maybe neither the generic oEmbed HTML template nor the site-specific template provided by the oEmbed provider meet your requirements. In this case you will need to create a custom request handler. If you make a custom request handler then you can specify exactly how to request content from the provider and embed the provider's content into your page. Making a custom request handler requires Java programming skills.

To make a custom request handler:

  1. Create a Java class that extends the abstract class com.escenic.livecenter.service.proxy.api.AbstractOEmbedRequestHandler.

  2. Override the following methods:

    protected String doOEmbedRequest(final String pContentURL, final List<Header> pHeaders) throws Exception;

    This method requests content from the provider. Writing your own method gives you the opportunity to deal with any special requirements the provider site might have (such as supplying credentials).

    protected String generateOEmbedCodeFromTemplate(final String pContentURL, final List<Header> pHeaders)

    This method merges the information returned by the provider with the HTML template. Writing makes it possible to deal with complex requirements that cannot be satisfied by a simple merge process.

  3. Copy OEmbedCustomRequestHandler.properties from the plug-in installation into your webapp configuration layer (not the common configuration layer), and rename it appropriately. For Flickr, for example, you might enter:

    $ cp /opt/escenic/engine/plugins/live-center/misc/siteconfig/com/escenic/livecenter/service/proxy/OEmbedCustomRequestHandler.properties
    > /etc/escenic/engine/common/com/escenic/livecenter/service/proxy/FlickrCustomOEmbedHandler.properties
  4. Open the copied file for editing and set the following properties as required:

    urlPatterns

    A comma-separated list of host names (not URL patterns as listed here) for which this handler is to be used. For Flickr, for example, you might want to set this property as follows:

    urlPatterns=flickr.com,flic.kr
    OEmbedUrlEndPoint

    The URL to which embed requests are to be sent. These URLs are included in the list of oEmbed providers

    blockCodeTemplate

    An HTML template from which the embedding code for your web pages will be generated. To include oEmbed property values in your template, enclose the property name in braces thus:

    {property-name}

    For Flickr, for example, you might specify a template like this:

    blockCodeTemplate=<blockquote class="flickr-image" lang="en">TBS</blockquote>
    providerName

    The name of the provider for which you are implementing this handler (Flickr, for example). This property is mandatory if you have specified a blockCodeTemplate, otherwise it is optional.

  5. Register your request handler as described in Register Request Handlers.