Custom Addon

Custom addons in Widgetbook offer the flexibility to tailor your development environment according to the unique needs of your project. We will explore two examples, simple and advanced, demonstrating the process of creating custom addons.

Setup#

To create a custom Addons, follow these steps:

• Define a model for your custom Addon. This model will hold the data and behavior of your Addon.
• Create a new class that extends the WidgetbookAddon class with a generic parameter corresponding to your defined model.

Writing a custom Alignment Addon#

Here's an example demonstrating how to create a simple Alignment Addon:

import 'package:flutter/material.dart';
import 'package:widgetbook/widgetbook.dart';

class AlignmentAddon extends WidgetbookAddon<Alignment> {
  AlignmentAddon({
    Alignment initialAlignment = Alignment.center,
  }) : super(
          name: 'Alignment',
          initialSetting: initialAlignment,
        );

  @override
  Widget buildUseCase(
    BuildContext context,
    Widget child,
    Alignment setting,
  ) {
    // customize how the use case is built using your custom Addon
    return Align(
      alignment: setting,
      child: child,
    );
  }

  @override
  List<Field<Alignment>> get fields {
    return [
      ListField<Alignment>(
        name: 'alignment',
        initialValue: initialSetting,
        values: [
          Alignment.topLeft,
          Alignment.topCenter,
          Alignment.topRight,
          Alignment.centerLeft,
          Alignment.center,
          Alignment.centerRight,
          Alignment.bottomLeft,
          Alignment.bottomCenter,
          Alignment.bottomRight,
        ],
      )
    ];
  }

  @override
  Alignment valueFromQueryGroup(Map<String, String> group) {
    return valueOf<Alignment>('alignment', group)!;
  }
}

In this example, we create a AlignmentAddon that manages a Alignment value. The initialSetting is the initial state of the Alignment value. The fields list contains a single ListField which represents the Alignment value managed by the addon in the Widgetbook UI

Let's break down the code to understand better.

class AlignmentAddon extends WidgetbookAddon<Alignment> {

We create a new class called AlignmentAddon, which extends WidgetbookAddon. The Alignment generic indicates that this addon will handle a Alignment value.

class AlignmentAddon extends WidgetbookAddon<Alignment> {
  AlignmentAddon({
    Alignment initialAlignment = Alignment.center,
  }) : super(
          name: 'Alignment',
          initialSetting: initialAlignment,
        );

The constructor for AlignmentAddon takes a parameter. initialAlignment is Alignment with default value, if provided, will be used as the initial value of the addon.

We define one final fields in the class, alignment, to hold the values passed in from the constructor. You may add more fields if necessitates.

  @override
  Widget buildUseCase(
    BuildContext context,
    Widget child,
    Alignment setting,
  ) {
    return Align(
      alignment: setting,
      child: child,
    );
  }

The buildUseCase method is where we specify how the addon will affect the widget tree. It's an abstract method from the WidgetbookAddon class that we need to implement. It takes three parameters: a BuildContext, a Widget that is the child of this addon, and a Alignment that is the current setting of the addon. For now, we wrap the child widget with an Align widget that uses the setting parameter (which is the current Alignment setting for this addon) as its alignment value.

    @override
  List<Field<Alignment>> get fields {
    return [
      ListField<Alignment>(
        name: 'alignment',
        initialValue: initialSetting,
        values: [
          Alignment.topLeft,
          Alignment.topCenter,
          Alignment.topRight,
          Alignment.centerLeft,
          Alignment.center,
          Alignment.centerRight,
          Alignment.bottomLeft,
          Alignment.bottomCenter,
          Alignment.bottomRight,
        ],
      )
    ];
  }

The fields getter is where we specify the fields that will represent the addon in the Widgetbook UI. Each field corresponds to an input field in the UI. In this case, we have a single ListField with an initial value of initialSetting and values of possible alignments for Align widget.

  @override
  Alignment valueFromQueryGroup(Map<String, String> group) {
    return valueOf<Alignment>('alignment', group) ?? initialSetting;
  }

Lastly, the valueFromQueryGroup method is overridden. This method is responsible for generating a new Alignment setting for the addon from the URL's query parameters. It uses the helper method valueOf to extract the Alignment value associated with the 'alignment' key from the group map. If the value is not found (i.e., it's null), it falls back to the initialSetting.

Congratulation! you have managed to created your first custom Addon that wraps Align widget. So now, nothing cannot stop you to write what your project need.

Field Types in Widgetbook#

For more detailed information, visit the Field Types page.