Widgets Specification

Dispatch Widgets

Widgets are modular components that can be used throughout different parts of a Dispatch website.

Zones

A zone is a pre-defined portion of the website that can support one or more widget types. Zones allow us to configure the placement of widgets throughout the site. A widget can be compatible with one or more zones.

Defining zones in your theme

# your-theme/zones.py

from dispatch.theme import theme_zone
from dispatch.theme.zones import Zone

@theme_zone
class Zone1(Zone):
  id = 'zone-1'
  name = 'Zone 1'

@theme_zone
class Zone2(Zone):
  id = 'zone-2'
  name = 'Zone 2'

Using zones in templates

A zone can be rendered in any template using the zone template tag like so:

{% load zones %}

... 

<div>
{% zone 'zone-1' %}
</div>

Zones API Spec

Zones only have two methods: GET and PUT. Since zones and widgets are defined in the theme code, they do not support the standard CRUD operations. The zone PUT route only allows the user to manipulate the dynamic data stored for that zone.

GET '/api/zones/'

# JSON
[
  {
    'id': 'zone-1',
    'name': 'Zone 1',
    'widget': {
      'id': 'widget-1',
      'data': {
        'title': 'test title 1',
      }
    }
  },
  {
    'id': 'zone-2',
    'name': 'Zone 2',
    'widget': {
      'id': 'widget-2',
      'data': {
        'title': 'test title 2',
      }
    }
  }
]

GET '/api/zones/{id}'

# JSON
{
  'id': 'zone-2',
  'name': 'Zone 2'
  'widget': {
    'id': 'widget-2',
    'data': {
      'title': 'test title 2',
    }
  }
}

PATCH '/api/zones/{id}'

# JSON
{
  'widget': {
    'id': 'widget-1',
    'data': {
      'title': 'test title 1',
    }
  }
}

Widgets

Defining widgets in your theme

# your-theme/widgets.py

from dispatch.theme import theme_widget
from dispatch.theme.widgets import Widget, CharField

@theme_widget
class CustomWidget(Widget):
  id = 'custom-widget'
  name = 'Custom Widget'
  template = 'widgets/custom-widget.html'
  zones = (Zone1,)
 
  # Define fields
  title = CharField()

Widgets API Spec

GET '/api/widgets/'

# JSON

[
  {
    'id': 'widget-1',
    'name': 'Widget 1',
    'fields': [
      {
        'type': 'text'
      },
       {
        'type': 'image',
        'many': True
      }
    }]
  }
]