Panel for blocks

[uroybd]

Currently, we can use FieldPanel, MultiFieldPanel, and FieldRowPanel to create very efficient editing workflow. However, StreamField blocks cannot take advantage of those. This, I think, is very important for Stream blocks since they are being heavily used as freeform page body editors.

Very recently, I've solved this problem by some custom blocks which can be considered as proof of concept of what can be done. here's the full code:

blocks.py

# blocks.py
class BlockPanel:
    def __init__(self, handle, fields, label="", classnames=""):
        self.handle = handle
        self.fields = fields
        self.label = label or handle
        self.classnames = classnames

    def js_args(self):
        return {
            "handle": self.handle,
            "label": self.label,
            "classnames": self.classnames,
            "fields": [field.js_args() for field in self.fields],
        }


class BlockField:
    def __init__(self, field, classnames="", hide_label=False):
        self.field = field
        self.classnames = classnames
        self.hide_label = hide_label

    def js_args(self):
        return {
            "field": self.field,
            "classnames": self.classnames,
            "hide_label": self.hide_label,
        }


class TabbedStructBlock(blocks.StructBlock):
    MUTABLE_META_ATTRIBUTES = ["panels"]

    class Meta:
        panels = []


class TabbedStructBlockAdapter(StructBlockAdapter):
    js_constructor = "pages.blocks.TabbedStructBlock"

    def js_args(self, block):
        args = super().js_args(block)
        args[-1]["panels"] = [panel.js_args() for panel in block.meta.panels]

        return args

    @cached_property
    def media(self):
        struct_block_media = super().media
        return forms.Media(
            js=struct_block_media._js + ["wagtailutils/js/tabbed_struct.js"],
            css={
                "all": [
                    "https://cdnjs.cloudflare.com/ajax/libs/gridlex/2.7.1/gridlex.min.css",
                    "wagtailutils/css/tabbed_struct.css",
                ]
            },
        )


register(TabbedStructBlockAdapter(), TabbedStructBlock)

tabbed_struct.js

// tabbed_struct.js

function h(unsafe) {
  return unsafe
    .replace(/&/g, "&")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#039;");
}

const removeErrorMessages = (container) => {
  container
    .querySelectorAll(":scope > .help-block.help-critical")
    .forEach((element) => element.remove());
};

const addErrorMessages = (container, messages) => {
  messages.forEach((message) => {
    const errorElement = document.createElement("p");
    errorElement.classList.add("help-block");
    errorElement.classList.add("help-critical");
    errorElement.innerHTML = h(message);
    container.insertBefore(errorElement, container.childNodes[0]);
  });
};

const hasOwn = (object, key) =>
  object ? Object.prototype.hasOwnProperty.call(object, key) : false;

class TabbedStructBlockValidationError {
  constructor(blockErrors) {
    this.blockErrors = blockErrors;
  }
}

class TabbedStructBlock {
  constructor(blockDef, placeholder, prefix, initialState, initialError) {
    const state = initialState || {};
    this.blockDef = blockDef;
    this.type = blockDef.name;
    this.childBlocks = {};
    console.log(prefix);
    const namespace = h(prefix || "");
    const dom = $(`
        <div id="${namespace}" class="tabbed-struct struct-block ${h(
      this.blockDef.meta.classname
    )}">
        </div>
      `);
    $(placeholder).replaceWith(dom);
    if (this.blockDef.meta.helpText) {
      // help text is left unescaped as per Django conventions
      dom.append(`
          <span>
            <div class="help">
              ${this.blockDef.meta.helpIcon}
              ${this.blockDef.meta.helpText}
            </div>
          </span>
        `);
    }
    const tabs = $(`
        <ul class="w-tabs__list tabbed-struct-menu">
        </ul>
      `);
    dom.append(tabs);
    const blockErrors = initialError?.blockErrors || {};
    blockDef.meta.panels.forEach((p, idx) => {
      let ns = `${namespace}-tab-${p.handle}-${idx}`;
      let header = $(`<li class="w-tabs__tab ${idx == 0 ? " selected" : ""}">
        <a href="#${ns}-content" class="ui-tabs-anchor">${p.label}</a>
      </li>
      `);
      tabs.append(header);
      header.click(function (e) {
        e.preventDefault();
        let target = $(e.target);
        target.parent().addClass("selected");
        target.parent().siblings().removeClass("selected");
        dom.children("section").removeClass("active-tab");
        dom.children(`#${ns}-content`).addClass("active-tab");
      });
      let tab = $(
        `<section id="${ns}-content" class="tabbed-tab w-panel__content ${
          idx == 0 ? " active-tab" : ""
        } ${p.classnames}"></section>`
      );
      dom.append(tab);
      p.fields.forEach((field, idnx) => {
        const childBlockDef = this.blockDef.childBlockDefs.find(
          (c) => c.name == field.field
        );
        const label = field.hide_label
          ? ""
          : `<label class="w-field__label">${h(
              childBlockDef.meta.label
            )}</label>`;
        const childDom = $(`
          <div id="${ns}-field-${idnx}" class="field  ${
          childBlockDef.meta.required ? "required" : ""
        } ${field.classnames}" data-contentpath="${childBlockDef.name}">
            ${label}
            <div data-streamfield-block></div>
          </div>
        `);
        tab.append(childDom);
        const childBlockElement = childDom
          .find("[data-streamfield-block]")
          .get(0);

        const childBlock = childBlockDef.render(
          childBlockElement,
          prefix + "-" + childBlockDef.name,
          state[childBlockDef.name],
          blockErrors[childBlockDef.name],
          new Map()
        );
        this.childBlocks[childBlockDef.name] = childBlock;
        if (!field.hide_label) {
          const labelElement = childDom.find("label").get(0);
          if (childBlock.idForLabel) {
            labelElement.setAttribute("for", childBlock.idForLabel);
          }
        }
      });

      if (idx == 0) {
        tabs.attr("data-current-tab", ns);
      }
    });
    this.container = dom;
    // $(dom).tabs();
  }

  setState(state) {
    // eslint-disable-next-line guard-for-in, no-restricted-syntax
    for (const name in state) {
      this.childBlocks[name].setState(state[name]);
    }
  }

  setError(error) {
    if (!error) return;

    // Non block errors
    const container = this.container[0];
    removeErrorMessages(container);
    if (error.messages) {
      addErrorMessages(container, error.messages);
    }

    if (error.blockErrors) {
      for (const blockName in error.blockErrors) {
        if (hasOwn(error.blockErrors, blockName)) {
          this.childBlocks[blockName].setError(error.blockErrors[blockName]);
        }
      }
    }
  }

  getState() {
    const state = {};
    // eslint-disable-next-line guard-for-in, no-restricted-syntax
    for (const name in this.childBlocks) {
      state[name] = this.childBlocks[name].getState();
    }
    return state;
  }

  getValue() {
    const value = {};
    // eslint-disable-next-line guard-for-in, no-restricted-syntax
    for (const name in this.childBlocks) {
      value[name] = this.childBlocks[name].getValue();
    }
    return value;
  }

  getTextLabel(opts) {
    if (this.blockDef.meta.labelFormat) {
      return this.blockDef.meta.labelFormat.replace(
        /\{(\w+)\}/g,
        (tag, blockName) => {
          const block = this.childBlocks[blockName];
          if (block.getTextLabel) {
            return block.getTextLabel(opts);
          }
          return "";
        }
      );
    }

    /* if no labelFormat specified, just try each child block in turn until we find one that provides a label */
    for (const childDef of this.blockDef.childBlockDefs) {
      const child = this.childBlocks[childDef.name];
      if (child.getTextLabel) {
        const val = child.getTextLabel(opts);
        if (val) return val;
      }
    }
    // no usable label found
    return null;
  }

  focus(opts) {
    if (this.blockDef.childBlockDefs.length) {
      const firstChildName = this.blockDef.childBlockDefs[0].name;
      this.childBlocks[firstChildName].focus(opts);
    }
  }
}

class TabbedStructBlockDefinition extends window.wagtailStreamField.blocks
  .StructBlockDefinition {
  render(placeholder, prefix, initialState, initialError) {
    return new TabbedStructBlock(
      this,
      placeholder,
      prefix,
      initialState,
      initialError
    );
  }
}

window.telepath.register(
  "pages.blocks.TabbedStructBlock",
  TabbedStructBlockDefinition
);

And here's an usecase

# home/blocks.py

class ShowReel(utilblocks.TabbedStructBlock):
    video = VideoChooserBlock()
    thumbnail_video = VideoChooserBlock(required=False)
    text_left = blocks.CharBlock(default="Play")
    text_right = blocks.CharBlock(default="Reel")
    color_settings = ColorSettings()
    anchor = blocks.CharBlock(required=False)
    loop = blocks.BooleanBlock(default=False, required=False)
    overlay = ShowReelOverlaySettings()
    padding = PaddingSettings()

    class Meta:
        panels = [
            utilblocks.BlockPanel(
                "content",
                [
                    utilblocks.BlockField("video"),
                    utilblocks.BlockField("thumbnail_video"),
                    utilblocks.BlockField("text_left"),
                    utilblocks.BlockField("text_right"),
                ],
            ),
            utilblocks.BlockPanel(
                "settings",
                [
                    utilblocks.BlockField("loop"),
                    utilblocks.BlockField("overlay"),
                    utilblocks.BlockField("color_settings"),
                    utilblocks.BlockField("padding"),
                    utilblocks.BlockField("anchor"),
                ],
            ),
        ]

It renders an UI like this 🖼️

[lb-]

@uroybd thanks for raising this. There are likely ways to do something similar already in Wagtail.

I think it might be good to point you towards our Stimulus RFC 78 which offers some of the building blocks that come already with Wagtail. Namely the ability to dynamically attach some JS to rendered form parts in Wagtail. When using plain html (as used by Panels), StreamField will use that provided HTML without issue, so the tricky part is conveniently attaching JS to that HTML when it gets added to the DOM, Stimulus bridges this gap with a lightweight data attributes convention in html and a simple JS class approach.

Additionally, there is activate work in place to make some approaches documented and more capabilities supported in this area.

See

• https://github.com/wagtail/rfcs/blob/main/text/078-adopt-stimulus-js.md (Wagtail 5.0 comes with the start of this RFC implementation)
• Add ability to support attrs in Panel and by extension FieldPanel #10133  #10323
• Documentation - Extending Wagtail client-side with Stimulus #10510

Additionally, there is also Telepath which may provide some ways to achieve your goals in the StreamField case.

• https://docs.wagtail.org/en/stable/advanced_topics/customisation/streamfield_blocks.html#additional-javascript-on-structblock-forms
• https://wagtail.github.io/telepath/
• https://wagtail.org/blog/telepath/

[zerolab]

To add to this - looking at the screenshot, I see one of the use cases is to have settings. There's a discussion around block settings specifically at #7739 (comment)

[lb-]

Converting to a discussion @uroybd - I think this is useful for others to chime in but i do not think this can be really resolved with a single fix or enhancement.

It's likely a mix of seeing what documented/upcoming solutions will be available and maybe some gaps can lead to some more focused enhancement requests.

[uroybd]

Actually, the example with the tabs is just a demo. The main point is about giving the same amount of control in block level that is currently available in field level for admin interface using the same type of abstraction. This, I believe will be very good from a DX perspective.

[thibaudcolas]

@lb- can you elaborate on why you don’t think this can be solved with a single enhancement?

From my perspective it seems like supporting the "panels" API we have at the page level or for snippets would make a lot of sense for CMS users and site implementers. Now what the implementation looks like / how much work that is – I don’t know.

The use case that we see a lot is "settings", which really could just be having collapsible sections within the block (so for example MultiFieldPanel + #10227).

[lb-]

I'll have another read, been a while since I looked at this and have no recollection of why I said this haha.

[lb-]

Ok. Upon re-reading, I'm not sure I understand this discussion/issue the same as you.

It looks the the requested enhancement is about setting up a completely different way to present the structure of a single StreamField value and not about snippets specifically as per your comment.

A lot has changed in the last 8 months so there may be some other ways to approach this problem though.

Anyway, more than happy to take on ideas and feel free to ignore my call on converting this to a discussion. I understood the requirement as quite complex, needing us to better abstract our TabbedInterface or build a new one specifically for StreamField blocks, I think that's why I suggested this be split up.

Sorry if I've misunderstood.