Media plugins - Vlog / Podcast

Publising a vlog or a podcast require more introspection on the plugin contents than is generally available to django CMS plugins.

djangocms-blog provides a mixin for plugin models and templatetags to help when dealing with this use case.

For convenience, an additional media placeholder has been added to the Post model.


djangocms-blog only provide a generic interface to introspect media plugins but it does not provide any plugin for any media platform as they would be very hard to maintain as the platforms changes. Examples provided here are working at the time of writing but they may require changes to work.

Base classes


Base class for media-enabled plugins.

Items that needs implementation in subclasses:

  • media_id: property that provides the object id on the external platform

  • media_url: property that provides the media public URL

  • _media_autoconfiguration: configuration dictionary (see documentation for details)

_media_autoconfiguration = {'callable': None, 'main_url': '', 'params': [], 'thumb_url': ''}

Configuration dictionary. All the keys are required:

  • 'params': one or more regular expressions to retrieve the media ID according to the provided media_url. It must contain a capturing group called media_id (see examples below).

  • 'thumb_url': URL of the intermediate resolution media cover (depending on the plaform). It supports string formatting via format by providing the return json for the media according to the plugic specification.

  • 'main_url': URL of the maximum resolution media cover (depending on the plaform). It supports string formatting via %-formatting by providing the return json for the media according to the plugic specification.

  • 'callable': in case the above information are not recoverable from the object URL, provide here the name of a method on the plugin model instance taking the media_id as parameter and that builds the data required by thumb_url, media_url strings to build the correct cover urls.


URL of the media cover at maximum resolution

Return type:



URL of the media cover at intermediate resolution

Return type:


property media_id

ID of the object on the remote media.

Return type:


property media_params

Retrieves the media information.

Minimal keys returned:

  • media_id: object id on the external platform

  • url: full url to the public version of the media

In case the 'callable' key in py:attr:` _media_autoconfiguration` is not None, it will be called instead (as method on the current model instance) to retrieve the information with any required logic.


media information dictionary

Return type:


property media_url

Public URL of the object on the remote media.

As you will likely have a URL on the plugin model, it’s usually enough to return that value, but you are free to implement any way to retrieve it.

Return type:


djangocms_blog.templatetags.djangocms_blog.media_images(context, post, main=True)

Extract images of the given size from all the plugins in the media placeholder of the provided post.

Support djangocms-video poster field in case the plugin does not implement MediaAttachmentPluginMixin API.



list of images urls

Return type:


djangocms_blog.templatetags.djangocms_blog.media_plugins(context, post)

Extract plugins from the media placeholder of the provided post.

They can be rendered with render_plugin templatetag:


list of plugins

Return type:


How to build the media plugins

  1. Create a plugin model

    Create a plugin model inheriting from CMSPlugin or a subclass of it and add mixin.

  2. Provide the media configuration


  3. Implement required properties

    Provide an implementation for the following properties:

  4. Add any additional properties / method suitable for your case.

    See media_title field in the Vimeo model below.


Plugin model

This is a basic example for a Vimeo plugin.

As covers cannot be calculated from the video id, we must download the related json and extract information from there. This model use the 'callable' parameter in

 class Vimeo(MediaAttachmentPluginMixin, CMSPlugin):
     url = models.URLField('Video URL')

     _media_autoconfiguration = {
         'params': [
         'thumb_url': '%(thumb_url)s',
         'main_url': '%(main_url)s',
         'callable': 'vimeo_data',

     def __str__(self):
         return self.url

     def media_id(self):
             return self.media_params['id']
         except KeyError:
             return None

     def media_title(self):
             return self.media_params['title']
         except KeyError:
             return None

     def media_url(self):
         return self.url

     def vimeo_data(self, media_id):
         response = requests.get(
             '' % {'media_id': media_id, }
         json = response.json()
         data = {}
         if json:
             data = json[0]
                     'main_url': data['thumbnail_large'],
                     'thumb_url': data['thumbnail_medium'],
         return data

Plugin class

Plugin class does not require any special code / configuration and can be setup as usual.

 class VimeoPlugin(CMSPluginBase):
     model = Vimeo
     module = 'Media'
     name = 'Vimeo'
     render_template = 'media_app/vimeo.html'

How to display information in templates

The actual implementation may vary a lot according to your design. To ease retrieving the plugins, check djangocms_blog.templatetags.djangocms_blog.media_images() djangocms_blog.templatetags.djangocms_blog.media_plugins() which abstract away a lot of the django CMS logic to retrieve the plugins for a placeholder.

It’s important to remember that at least in some templates, you must have the media placeholder rendered using {% render_placeholder %} templatetag, otherwise you will not be able to add the plugins to the blog post.


Media plugin

The media plugin requires the normal template to render the video according to the plugin fields:

 {% if instance.media_id %}<iframe src="{{ instance.media_id }}?badge=0&autopause=0&player_id=0&app_id=2221" width="1920" height="1080" frameborder="0" title="{{ instance.media_title }}" allow="autoplay; fullscreen" allowfullscreen></iframe>{% endif %}

Blog posts list

A basic implementation is retrieving the covers associated to each media content via djangocms_blog.templatetags.djangocms_blog.media_images() and rendering each with a <img> tag:

 {% media_images post as previews %}
 <div class="blog-visual">
   {% for preview in previews %}<img src="{{ preview }}" />{% endfor %}

Blog posts detail

A basic implementation is rendering the media plugins as you would do with normal plugins:

 {% if not post.main_image_id %}
     <div class="blog-visual">{% render_placeholder %}</div>
 {% else %}

djangocms-video support

poster attribute from djangocms-video is also supported.

poster is just a static fixed-size image you can set to a djangocms-video instance, but adding the plugin to the media placeholder allows to extract the image from the field and display along with the generated previews by seamlessly using media_images.

The rendering of the full content is of course fully supported.