Developer Documentation

Getting Started


A widget is a piece of HTML that will be inserted in a specific spot in a page to render some view.

To create a new widget you need to extend the Widget class from colab.widgets. In the child class you can override the methods below, but it is not mandatory:


This method should return the HTML code to be used in the page’s head. So, it will extract the head content from the content.


This method should return the HTML code to be used in the page’s body. So, it will extract the body content from the content.


This method will set the content when the widget is requested by the WidgetManager. The content contains a HTML code that will be rendered in the target page.

The Widget class has the following attributes:


The identifier has to be a unique string across the widgets.


The widget name is the string that will be used to render in the view, if needed.

Example Widget:

from colab.widgets.widget_manager import Widget

class MyWidget(Widget):
    identifier = 'my_widget_id'
    name = 'My Widget'
    def generate_content(self, **kwargs):
        # process HTML content
        self.content = processed_content

To add the widget in a view check the Widgets section in User Documentation. To use a widget in the templates, you have to use the import_widget tag inside the html block. This way, the kwargs parameter will have a context key from the html. You can also set the variable that the widgets of an area will be imported. Or you can use the default name, which is widgets_area_name. For example, in the profile area the variable name is widgets_profile. This variable will be inserted directly in the page context.

{% load widgets_tag %}

{% block html %}
   {% import_widgets 'profile' %}
   {{ block.super }}
{% endblock %}

{# example of how to use #}
{% block head %}
  {{ block.super }}

  {% for widget in widgets_profile %}
    {{ widget.get_header }}
  {% endfor %}

{% endblock %}

{% block body %}
  {{ block.super }}

  {% for widget in widgets_profile %}
    {{ widget.get_body }}
  {% endfor %}

{% endblock %}


Warning! Remember to use the tag {{ block.super }} inside the html block. Otherwise, the page will appear blank.


The blacklist is an array of urls that the user cannot access directly. This variable holds an array of urls regex that must be blocked. This variable must be set on, exactly as the following example:

BLACKLIST = [r'^dashboard$']