Productizing the Milo Block Library

[dylandepass]

The block library featured developed by Chris Millar and the Milo team has been a highly desired and requested feature for Franklin projects. It's pretty safe to say everyone who see's it wants it.

It solves a few problems that authors may face today when working with blocks.

1. Provides a list of all blocks and block variations to authors in an intuitive manner and removes the need for authors to have to remember or search for every variation of a block.
2. It has the ability to bring together other data and external systems into a single tool for authors (blocks, assets, placeholders, tags etc).
3. It can aggregate blocks across multiple inherited projects into a single place.

Introducing the block library into the product would be a great addition to Franklin. I have attempted to explain the inner workings of it here so we can discuss its possible integration into the product, either as part of the sidekick/hlx.live or as an open source library with guidance for setup.

How does it work?

Sidekick setup

The block libary is itself a franklin block and served from the customers site into the authoring document via a sidekick plugin.

{
  "project": "wesco-ecommerce",
  "outerHost": "main--wesco-ecommerce--wesco-international.hlx.live",
  "host": "main--wesco-ecommerce--wesco-international.helix3.dev",
  "byocdn": true,
  "plugins": [
    {
      "id": "library",
      "title": "Library",
      "environments": [
        "edit"
      ],
      "isPalette": true,
      "paletteRect": "top: auto; bottom: 20px; left: 20px; height: 398px; width: 360px;",
      "url": "/docs/library",
      "includePaths": [
        "**.docx**"
      ]
    }
  ]
}

The url property in the plugin config points to a document that contains the library-config block.

Library Config Block

The library-config block is just like any other block in franklin. It contains a decorate method along with some css and goes through the typical decoration process as any other block does.

The one caveat here is because it goes through the decoration process customers also need a way to stop the loading of the header and footer. Milo does this by adding in metadata on the page to stop the loading of the header and footer (for boilerplate this would require changes to scripts.js)

Storybook workflows also have the same requirement of preventing the load of the header and footer.

The library-config block itself contains a url that points to a workbook containing multiple sheets. Each sheet represents a list of resources available to be exposed in the block library (blocks, tags, placeholders etc).

In the example above the blocks sheet contains a set of name / path rows. The path points to a document that contains all the variations of the cards block.

When the library-config block loads it fetches the base library workbook. The base library would be whatever library.json url is in the block. It would then look for any supplementary libraries defined in the url params provided to the sidekick plugin (See Extensibility below) and merge them into a final object used to render the first level of options in the block library.

It appears that there are a few variations of the library-config block used by Milo depending on the requirements for the site. All versions handle showing a list of blocks but some add in placeholders, assets, icons etc.

As items are selected from the first level of the block library, requests are made to load all the paths from the corresponding sheet and then display them on the second level. For example, selecting blocks would load all the plain.html files for the enteries in the blocks sheet.

From there is each plain.html document is parsed and the variations of each block are added under the parent item in the block-libary. In the example below the cards block is the parent item with each variation below it.

This setup of defining all the variations of a block in a document is the same approach used when setting up storybook to develop these blocks in isolation.

At the top level the block-library has a preview button that can take authors to the source document.

Each variation also has a copy button which allows authors to copy the plain.html content and paste it into the current document.

Extensibility

The block library can be extended to load additional libraries or other resource by adding on addition url params to the url provided to the sidekick plugin. For example.

Merging two libraries

The url below (provided to the sidekick plugin) would merge two libraries together, the base library would be whatever library is pointed to in /storybook/library and the supplimental libary from the parent site wesco-ecommerce. In this example this is defined by adding in the repo & owner params.

http://main--eecol-commerce--wesco-international.hlx.page/storybook/library?repo=wesco-ecommerce&owner=wesco-international

External libary and addition resources

The url below loads the library-config block hosted on milo but overrides the library loaded with the library param and also provides an assets param which points to a list of assets from AEM Assets (with a fusion proxy, not sure why fusion is in front).

https://main--milo--adobecom.hlx.page/tools/library?assets=https%3A%2F%2Fhook.app.workfrontfusion.com%2Fsxpq3kch33mktgchbcoo1nwmvh5i9fc3&&library=https%3A%2F%2Fmain--comirnaty--hlxsites.hlx.page%2Fdocs%2Flibrary%2Flibrary.json

This is an interesting example, a setup like this could mean we could host the library-config block on hlx.live and customers could just point it at thier library and not have to worry about managing the library-config block in thier repository.

CORS

Since the library doc (which includes the library-config block) needs to be accesible from outside of same-origin it requires an allow-origin CORS header to be returned. This goes for any other block that would be loaded by the block-library.

The requiment of a directory that contains block examples and has an open CORS policy is also the same to setup storybook.

Storybook

There is actually a lot of overlap between what the block library requires and what storybook integration requires. It is 100% possible for there to be a single set of example blocks that power both the block library and storybook.

Current list of sites using the block library

Live

BACOM
Milo
Stock

Pre-Production

Blog (goes live in a month)
FedPub (live in a month)
Creative Cloud (live in 3 months)
Doc Cloud (release imminent)
Business Blog (goes live in a month)
Wesco
WKND
Maidenform

Productizing questions

1. Figure out if the library-config block is something we want to manage/host as part of the product, provide in boilerplate or just put out there as a code example.. If we choose to put it in boilerplate it will make future features a little harder to roll out. On the other hand if we choose to manage/host it ourselves than unless we provide a plugin mechanism, customers will loose the ability to hook in whatever API/thing they want into the block library.

2. What elements should we consider in the initial MVP of the block library? A catalogue of blocks is a given, but would we like to include AEM Assets, placeholders, icons as well? The first two seem to be straightforward, but the last two might differ between sites.

Next Steps

Try and get more usage of the block library from projects other than milo based ones to gather feedback from customers.

Anyone looking to try it out can reference the WKND project.

Relevant code is below (it's more or less just a copy and paste from a milo project) and is only using the blocks part at this point.

https://github.com/hlxsites/wknd/blob/main/tools/sidekick/config.json
https://github.com/hlxsites/wknd/tree/main/blocks/library-config

If you integrate it into your project please let us know any feedback you receive from customers!

[hannessolo]

We implemented a (simplified) version of this feature, inspired by the Milo code, in the Maidenform project.

We don't have customer feedback on it yet, (we haven't even created most blocks in the block library yet), but will keep everyone updated once we do.

I suggest we wait for initial customer feedback on Maidenform, to see if this is a desired feature for them. If they are interested, we should consider whether its worth it to switch to using the Milo implementation, also depending on the outcome of the discussion here about productization (cc @herzog31 ).

Some screenshots from the Maidenform implementation:

[shsteimer]

regarding the productization questions, I'd push for making it part of the boilerplate, but only handling blocks (not assets, placeholders, icons, etc.) at least for now. because:

1. I consider the ability to extend this a must have, so by putting it in boilerplate, that comes by default without having to figure out all the complexity that comes with a plugin system.
2. not all project will use assets, icons, etc. so limiting to things every project uses, at least as a starting point, is ideal, but still allows for the individual projects to extend as needed

I'll admit to being a little naive to what exactly is meant by "If we choose to put it in boilerplate it will make future features a little harder to roll out" so maybe that concern outweighs the above, but just my $.02

[rofe]

In addition to what @shsteimer said, I think it should be integrated into the sidekick by default, without the need for a plugin config. What's hosted on https://milo.adobe.com/tools/library today should be available on https://www.hlx.live/tools/sidekick/library. And the boilerplate should have example content (with cards, columns) to make it easy to get started.

[arumsey]

You can add Merative to the list of projects using a modified version of the Milo library config. It supports blocks, complex sections, and buttons. Adding page templates has also be suggested as a future enhancement.

• https://github.com/hlxsites/merative2/blob/main/blocks/library-config/library-config.js
• https://main--merative2--hlxsites.hlx.page/block-library/library