Super Embed Architecture

[matthew-carroll]

Super Embed is a drop-in solution, as well as a small toolkit. Both modalities need to be supported by the architecture.

The fundamental responsibilities of Super Embed are as follows:

• Recognize supported URLs
• Fetch supported URLs and parse relevant data
• Display a UI while a URL is being fetched, and a UI that presents the URL's data

Recognizing URLs

Adding new URLs must be trivial.

Multiple handlers for a single URL must be supported. For example, there might be a Medium-specific handler, and there might also be a generic "catch all" handler for blog-style URLs. Both of these handlers need to be able to live together.

Fetching and Parsing URLs

Each type of metadata parser should be implemented in its own object so that developers can utilize parsers at their own discretion.

The parsed data should be returned in a formally typed data structure that's specific to the data being parsed, e.g., MediumBlogPostMetadata.

Multiple types of errors are possible when fetching and parsing. Each error condition needs to be identified and well represented.

Displaying a UI

A polished, responsive, cross-platform UI must exist for each type of metadata.

The UI needs to provide an experience for loading, error conditions, and the expected metadata presentation.

Each metadata experience needs to be deployable without the other parts of the system. i.e., the developer can provide a pre-constructed metadata, without fetching the URL, and the UI will display as expected.

High-Level Structure

At a high level, Super Embed should process URLs as shown below.

The above process describes the drop-in solution. When designing the object structure, the individual component use-cases must be kept in mind, too, e.g., fetching/parsing without display and displaying without fetching/parsing.

Technical Guidance

Conceptual Usage

To help inform the construction of Super Embed, the following are pseudo-code examples for how a developer might utilize Super Embed.

// Construct a SuperUrlParsers, which fetches and parses a given URL, returning metadata.
// By default, this object is configured with all existing parsers.
final parsers = const SuperUrlParsers();

// Constructs a SuperUrlDisplays, which provides a WidgetBuilder for a given metadata.
// By default, this object is configured with all existing displays.
final displays = const SuperUrlDisplays();

// Use only your desired parsers.
final customParsers = SuperUrlParsers([
    YouTubeUrlParser(),
    LoomUrlParser(),
    MediumUrlParser(),
    // etc.
]);

// Add a new parser
customParsers.add(SuperDeclarativeUrlParser());

// Remove a parser
customParsers.removeAt(1);

final customDisplays = SuperUrlDisplays([
    BlogDisplay(),
    YouTubeVideoDisplay(),
    LoomVideoDisplay(),
    // etc.
]);

// Add a new display
customDisplays.addAt(0, SuperDeclarativeBlogDisplay());

// Remove a display
customDisplays.removeAt(1);

// Ask if a given URL can be fetched and parsed.
//
// This query doesn't run a fetch or parse, it only checks if SuperUrlParsers knows
// what to do with this URL. We need to offer this query so that something like
// Super Editor doesn't try to insert a Super Embed widget for a URL that Super Embed
// can't handle.
final isUrlRecognized = urlParsers.recognizesUrl(myUrl);

// This example shows how to coordinate fetching, parsing, and display. The inside implementation
// of the drop-in SuperEmbed widget might look something like this.

try {
  final url = "some url";

  // The URL is parsed to metadata. The metadata might be a YouTubeVideoMetadata,
  // or a MediumBlogMetadata. We don't know exactly what it is.
  final metadata = await urlParsers.fetchAndParse(url);

  // SuperUrlDisplays returns a WidgetBuilder that builds a display with the given metadata.
  //
  // It's possible that we could return a Widget here instead of a WidgetBuilder. I haven't
  // thought through the consequences. But a WidgetBuilder is a safer bet because it
  // provides an opportunity to recreate the actual display widget every time it runs.
  final displayBuilder = urlDisplays.getDisplayBuilder(metadata);
} catch (exception) {
  // This example doesn't enumerate any error conditions because
  // it's focused on the happy path process to fetch, parse, and display.
}

Widget build(BuildContext context) {
  return Center(
    // Run the WidgetBuilder that we got from urlDisplays, or render empty space
    // if we don't have a builder, yet.
    child: displayBuilder?.call(context) ?? const SizedBox(),
  );
}

// When a developer wants to explicitly parse a URL for a known domain, the developer
// can instantiate and run the parser, directly.
final url = "some url";

final parser = YouTubeUrlParser();
assert(parser.recognizesUrl(url));

final metadata = await parser.fetchAndParse();

// When a developer wants to explicitly display pre-created metadata, the developer can
// use the same display widget that SuperEmbed uses.
final youtubeMetadata = YouTubeMetadata(
  // fill with desired properties
);

Widget build(BuildContext context) {
  return YouTubeVideoDisplay(
    metadata: youtubeMetadata,
  );
}

late SuperEmbedController _superEmbedController;

void initState() {
  super.initState();
  _superEmbedController = SuperEmbedController();
}

Future<void> _onUserProvidesUrl(String url) async {
  await  _superEmbedController.fetchAndDisplay(url);
}

// A drop-in widget should be available for quick and easy use of Super Embed.
Widget build(BuildContext context) {
  return Center(
    // This is the drop-in widget for SuperEmbed. Most developers will drop this
    // Widget in at a desired location without customizing parsers or displays.
    child: SuperEmbed(
      controller: _superEmbedController,
    ),
  );
}

URL Parsing and Display Resolution

To support URL parsers with overlapping applicability, a Chain of Responsibility should be used. The formal definition for a Chain of Responsibility is overly verbose. For our purposes, a Chain of Responsibility is a list of URL parsers. To parse a URL, the overall parser will go down this list, asking each individual parser to attempt to parse a URL. If a URL parser returns null, the overall parser goes to the next item in the list. This continues until a URL is parsed, or until there aren't any more parsers, indicating that we don't know how to parse this URL.

The SuperUrlDisplays should also use a Chain of Responsibility to map a given metadata to an appropriate WidgetBuilder, for the same reasons as the SuperUrlParsers object.

Super Embed should maintain default const lists of all parsers and displays that ship with the package. By default, when a developer instantiates a SuperUrlParsers or SuperUrlDisplays without any configuration, those objects should use the global default lists.

SuperEmbed Widget

The SuperEmbed widget is the drop-in solution that immediately gives developers full parsing and display functionality.

To provide fetching, parsing, display, a loading UI, and an error UI all in one, the SuperEmbed widget will operate on a SuperEmbedController, which internally handles all of those responsibilities, and notifies clients of changes.

[miguelcmedeiros]

@matthew-carroll

The API is really nicely structured and I can already image how this can be used together with SuperEditor 👍
Just one remark/question

URL recognition and fetching of metadata

If a developer that wants to integrate SuperEmbed together with SuperEditor, I would expect that urlParsers.recognizesUrl might have to do a bit more than checking if the URL is known to SuperUrlParsers.

If we take Slack as an example, if the user writes a URL then Slack will only show the embed in the input field only if the URL is correct. Otherwise it just formats the text referring to the URL as a link and shows no embed.

I'm assuming that Slack check if the URL comes from a supported embed source and fetches the metadata in one go, and then it decide whether to display the embed or not.

Is this a valid concern or has it already been considered in the proposed design?

[matthew-carroll]

Would this situation make sense as an error condition? I think you'll have to run a fetch and attempt to parse it to recognize this situation. And I think this situation still signifies "we tried to show a preview but we couldn't." Is there anything about this that you don't think would fit under error handling?

[matthew-carroll]

Tagging @miguelcmedeiros to make sure you saw this reply

[miguelcmedeiros]

It does make sense 👍

Don't mind the long reply, but I just want to give a bit more of context 🙂

I can imagine that with SuperEditor we will define a new node type for displaying an embed. In that case I think the approach of handling this scenario under handling works fine, since the user explicitly chose to introduce a node in the document.

The situation that I was considering is what we would encounter in chat tools like Slack, where the user is typing and depending on text (detects a URL) it would show a preview close to the input field:

In this example, the existing message in the conversation (display a video player) would be a use case for using SuperEmbed widget.
For displaying the embed below the input field would probably require something else. The proposal above gives all the building blocks (URL recognition, fetch/parse and display) we need to be able to achieve this.

[matthew-carroll]

@miguelcmedeiros Ok, let's keep this use-case in mind and make sure it works with whatever we create. I think we can find a way to make this possible with the proposed design.

Do you want to follow up with @bk-one about the status of this project? Is there anything for us to build at this point, if we can't embed video players? Do you want to check out that macos plugin I mentioned? I don't expect that plugin to work out, but you can check.

[miguelcmedeiros]

@matthew-carroll

I played a bit with flutter_macos_webview and it feels like it was made to serve very specific needs from the author (kudos to the authors for sharing it with the community), but it fails on some basic things like playing the following YouTube embed link: https://www.youtube.com/embed/M7lc1UVf-VE?autoplay=1

I'll follow up with @bk-one when he's back from holidays.