Download as
Browse Code »

Commit 8d0e0f117eeec8c3ee8ad486f1bd01230ef918ce

Authored by Matheus de Sousa Faria
Committed by Gust
1 parent 80f0bb5a
Exists in master and in 4 other branches 1.12.x, fix-dashboard, fix-message-preview, validate-passwd

Adding widget documentation

Showing 2 changed files with 65 additions and 0 deletions   Show diff stats
docs/source/dev.rst
  Diff comments   View file @8d0e0f1
... ... @@ -4,3 +4,47 @@ Developer Documentation
4 4 Getting Started
5 5 ---------------
6 6 .. TODO
  7 +
  8 +Widgets
  9 +-------
  10 +
  11 +A widget is a piece of HTML that will be inserted in a specific spot in a page to render some view.
  12 +
  13 +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:
  14 +
  15 +.. attribute:: get_header
  16 +
  17 + 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``.
  18 +
  19 +.. attribute:: get_body
  20 +
  21 + 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``.
  22 +
  23 +.. attribute:: generate_content
  24 +
  25 + 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.
  26 +
  27 +The Widget class has the following attributes:
  28 +
  29 +.. attribute:: identifier
  30 +
  31 + The identifier has to be a unique string across the widgets.
  32 +
  33 +.. attribute:: name
  34 +
  35 + The widget name is the string that will be used to render in the view, if needed.
  36 +
  37 +Example Widget:
  38 +
  39 +.. code-block:: python
  40 +
  41 + from colab.widgets.widget_manager import Widget
  42 +
  43 + class MyWidget(Widget):
  44 + identifier = 'my_widget_id'
  45 + name = 'My Widget'
  46 + def generate_content(self, request):
  47 + # process HTML content
  48 + self.content = processed_content
  49 +
  50 +To add the widget in a view check the Widgets section in User Documentation.
... ...
docs/source/user.rst
  Diff comments   View file @8d0e0f1
... ... @@ -58,6 +58,27 @@ View the following file:
58 58  
59 59 The file /etc/colab/settings.py have the configurations of colab, this configurations overrides the django settings.py
60 60  
  61 +Widgets
  62 +-------
  63 +
  64 +A widget is a piece of HTML that will be inserted in a specific spot in a page to render some view.
  65 +
  66 +To configure the widgets you have to edit, or create, the file ``/etc/colab/widgets_settings.py``. Or you can create a py file inside the folder ``/etc/colab/widgets.d``.
  67 +
  68 +Example:
  69 +
  70 +.. code-block:: python
  71 +
  72 + # Widget Manager handles all widgets and must be imported to register them
  73 + from colab.widgets.widget_manager import WidgetManager
  74 +
  75 + # Specific code for Gitlab's Widget
  76 + from colab_gitlab.widgets import GitlabProfileWidget
  77 +
  78 + WidgetManager.register_widget('profile', GitlabProfileWidget())
  79 +
  80 +
  81 +In this example the Gitlab's widget is added in a new tab inside the user profile.
61 82  
62 83 Add a new plugin
63 84 ----------------
... ...