Developer Documentation
==================
Getting Started
---------------
.. TODO
Widgets
-------
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:
.. attribute:: get_header
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``.
.. attribute:: get_body
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``.
.. attribute:: generate_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:
.. attribute:: identifier
The identifier has to be a unique string across the widgets.
.. attribute:: name
The widget name is the string that will be used to render in the view, if needed.
Example Widget:
.. code-block:: python
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``.
.. code-block:: python
{% 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 %}
.. warning::
Warning! Remember to use the tag ``{{ block.super }}`` inside the html block. Otherwise, the page will appear blank.