Create initial extension and extension context classes

Sub6Resources · Sub6Resources · commit c5ee0bda30d5 · 2023-05-09T15:38:20.000-06:00
diff --git a/lib/src/extension/extension.dart b/lib/src/extension/extension.dart
@@ -0,0 +1,50 @@
+import 'package:flutter/painting.dart';
+import 'package:flutter_html/flutter_html.dart';
+import 'package:flutter_html/src/extension/extension_context.dart';
+
+/// The [Extension] class allows you to customize the behavior of flutter_html
+/// or add additional functionality.
+///
+/// TODO add additional documentation
+///
+abstract class Extension {
+  /// Tells the [HtmlParser] what additional tags to add to the default
+  /// supported tag list (the extension's user can still override this by
+  /// setting an explicit tagList on the Html widget).
+  ///
+  /// Extension creators should override this with any additional tags
+  /// that should be visible to the end user.
+  List<String> get supportedTags;
+
+  /// This method is called to test whether or not this extension needs to do
+  /// any work in this context.
+  ///
+  /// Subclasses must override this method and return true if they'd like the
+  /// other methods to be called in a certain context.
+  bool matches(ExtensionContext context);
+
+  // Converts parsed HTML to a StyledElement. Need to define default behavior, or perhaps defer this step back to the Html widget by default
+  StyledElement lex(ExtensionContext context) {
+    throw UnimplementedError("TODO");
+  }
+
+  // Called before styles are applied to the tree. Default behavior: return tree;
+  StyledElement beforeStyle(ExtensionContext context) {
+    return context.styledElement!;
+  }
+
+  // Called after styling, but before extra elements/whitespace has been removed, margins collapsed, list characters processed, or relative values calculated. Default behavior: return tree;
+  StyledElement beforeProcessing(ExtensionContext context) {
+    return context.styledElement!;
+  }
+
+  //The final step in the chain. Converts the StyledElement tree, with its attached `Style` elements, into an `InlineSpan` tree that includes Widget/TextSpans that can be rendered in a RichText or Text.rich widget. Need to define default behavior, or perhaps defer this step back to the Html widget by default
+  InlineSpan parse(ExtensionContext context) {
+    throw UnimplementedError("TODO");
+  }
+
+  //Called when the Html widget is being destroyed. This would be a very good place to dispose() any controllers or free any resources that the extension uses. Default behavior: do nothing.
+  void onDispose() {
+    // Subclasses may override this to clean up when the extension is being disposed.
+  }
+}
diff --git a/lib/src/extension/extension_context.dart b/lib/src/extension/extension_context.dart
@@ -0,0 +1,81 @@
+import 'dart:collection';
+
+import 'package:flutter/widgets.dart';
+import 'package:flutter_html/html_parser.dart';
+import 'package:flutter_html/src/html_elements.dart';
+import 'package:html/dom.dart' as html;
+
+/// Provides information about the current element on the Html tree for
+/// an [Extension] to use.
+class ExtensionContext {
+  /// The HTML node being represented as a Flutter widget.
+  final html.Node node;
+
+  /// Returns the name of the Html element, or an empty string if the node is
+  /// a text content node, comment node, or any other node without a name.
+  String get elementName {
+    if (node is html.Element) {
+      return (node as html.Element).localName ?? '';
+    }
+
+    return '';
+  }
+
+  /// Returns the HTML within this element, or an empty string if there is none.
+  String get innerHtml {
+    return node.sourceSpan?.text ?? '';
+  }
+
+  /// Returns the list of child Elements on this html Node, or an empty list if
+  /// there are no children.
+  List<html.Element> get elementChildren {
+    return node.children;
+  }
+
+  /// Returns a linked hash map representing the attributes of the node, or an
+  /// empty map if it has no attributes.
+  LinkedHashMap<String, String> get attributes {
+    return LinkedHashMap.from(node.attributes.map((key, value) {
+      // Key is either a String or html.AttributeName
+      return MapEntry(key.toString(), value);
+    }));
+  }
+
+  /// Returns the id of the element, or an empty string if it is not present
+  String get id {
+    if (node is html.Element) {
+      return (node as html.Element).id;
+    }
+
+    return '';
+  }
+
+  /// Returns a set of classes on the element, or an empty set if none are
+  /// present.
+  Set<String> get classes {
+    if (node is html.Element) {
+      return (node as html.Element).classes;
+    }
+
+    return <String>{};
+  }
+
+  /// A reference to the [HtmlParser] instance. Useful for calling callbacks
+  /// on the [Html] widget like [onLinkTap].
+  final HtmlParser parser;
+
+  /// A reference to the [StyledElement] representation of this node.
+  /// Guaranteed to be non-null only after the lexing step
+  final StyledElement? styledElement;
+
+  /// Guaranteed only when in the `parse` method of an Extension, but it might not necessarily be the nearest BuildContext. Probably should use a `Builder` Widget if you absolutely need the most relevant BuildContext.
+  final BuildContext? context;
+
+  /// Constructs a new [ExtensionContext] object with the given information.
+  const ExtensionContext({
+    required this.node,
+    required this.parser,
+    this.styledElement,
+    this.context,
+  });
+}
