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.


Blacklist
----------

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 settings.py, exactly as the following example:

.. code-block:: python

    BLACKLIST = [r'^dashboard$']