Form widget client-side API

In order for the StreamField editing interface to dynamically create form fields, any Django form widgets used within StreamField blocks must have an accompanying JavaScript implementation, defining how the widget is rendered client-side and populated with data, and how to extract data from that field. Wagtail provides this implementation for widgets inheriting from django.forms.widgets.Input, django.forms.Textarea, django.forms.Select and django.forms.RadioSelect. For any other widget types, or ones which require custom client-side behaviour, you will need to provide your own implementation.

The telepath library is used to set up mappings between Python widget classes and their corresponding JavaScript implementations. To create a mapping, define a subclass of wagtail.widget_adapters.WidgetAdapter and register it with wagtail.telepath.register.

from wagtail.telepath import register
   from wagtail.widget_adapters import WidgetAdapter

   class FancyInputAdapter(WidgetAdapter):
       # Identifier matching the one registered on the client side
       js_constructor = 'myapp.widgets.FancyInput'

       # Arguments passed to the client-side object
       def js_args(self, widget):
           return [
               # Arguments typically include the widget's HTML representation
               # and label ID rendered with __NAME__ and __ID__ placeholders,
               # for use in the client-side render() method
               widget.render('__NAME__', None, attrs={'id': '__ID__'}),
               widget.id_for_label('__ID__'),
               widget.extra_options,
           ]

       class Media:
           # JS / CSS includes required in addition to the widget's own media;
           # generally this will include the client-side adapter definition
           js = ['myapp/js/fancy-input-adapter.js']


   register(FancyInputAdapter(), FancyInput)

The JavaScript object associated with a widget instance should provide a single method:

A widget’s state will often be the same as the form field’s value, but may contain additional data beyond what is processed in the form submission. For example, a page chooser widget consists of a hidden form field containing the page ID, and a read-only label showing the page title: in this case, the page ID by itself does not provide enough information to render the widget, and so the state is defined as a dictionary with id and title items.

The value returned by render is a ‘bound widget’ object allowing this widget instance’s data to be accessed. This object should implement the following attributes and methods: