Merge pull request Sub6Resources#546 from tneotia/feature/html-from-dom

erickok · web-flow · commit 8200613fc099 · 2021-03-16T23:21:51.000+01:00
Support creating Html widget from dom.Document
diff --git a/README.md b/README.md
@@ -33,9 +33,13 @@ A Flutter widget for rendering HTML and CSS as Flutter widgets.
 
 - [API Reference](#api-reference)
 
+  - [Constructors](#constructors)
+
   - [Parameters Table](#parameters)
 
   - [Data](#data)
+    
+  - [Document](#document)
 
   - [onLinkTap](#onlinktap)
 
@@ -131,11 +135,20 @@ For a full example, see [here](https://github.com/Sub6Resources/flutter_html/tre
 
 Below, you will find brief descriptions of the parameters the`Html` widget accepts and some code snippets to help you use this package.
 
+## Constructors:
+
+The package currently has two different constructors - `Html()` and `Html.fromDom()`. 
+
+The `Html()` constructor is for those who would like to directly pass HTML from the source to the package to be rendered. 
+
+If you would like to modify or sanitize the HTML before rendering it, then `Html.fromDom()` is for you - you can convert the HTML string to a `Document` and use its methods to modify the HTML as you wish. Then, you can directly pass the modified `Document` to the package. This eliminates the need to parse the modified `Document` back to a string, pass to `Html()`, and convert back to a `Document`, thus cutting down on load times.
+
 ### Parameters: 
 
 |  Parameters  |   Description   |
 |--------------|-----------------|
-| `data` | The HTML data passed to the `Html` widget. This is required and cannot be null. |
+| `data` | The HTML data passed to the `Html` widget. This is required and cannot be null when using `Html()`. |
+| `document` | The DOM document passed to the `Html` widget. This is required and cannot be null when using `Html.fromDom()`. |
 | `onLinkTap` | A function that defines what the widget should do when a link is tapped. The function exposes the `src` of the link as a `String` to use in your implementation. |
 | `customRender` | A powerful API that allows you to customize everything when rendering a specific HTML tag. |
 | `onImageError` | A function that defines what the widget should do when an image fails to load. The function exposes the exception `Object` and `StackTrace` to use in your implementation. |
@@ -148,7 +161,7 @@ Below, you will find brief descriptions of the parameters the`Html` widget accep
 
 ### Data:
 
-The HTML data passed to the `Html` widget as a `String`. This is required and cannot be null.
+The HTML data passed to the `Html` widget as a `String`. This is required and cannot be null when using `Html`.
 Any HTML tags in the `String` that are not supported by the package will not be rendered.
 
 #### Example Usage - Data: 
@@ -169,6 +182,36 @@ Widget html = Html(
 );
 ```
 
+### Document:
+
+The DOM document passed to the `Html` widget as a `Document`. This is required and cannot be null when using `Html.fromDom()`.
+Any HTML tags in the document that are not supported by the package will not be rendered.
+Using the `Html.fromDom()` constructor can be useful when you would like to sanitize the HTML string yourself before passing it to the package.
+
+#### Example Usage - Document: 
+
+```dart 
+import 'package:html/parser.dart' as htmlparser;
+import 'package:html/dom.dart' as dom;
+...
+String htmlData = """<div>
+  <h1>Demo Page</h1>
+  <p>This is a fantastic product that you should buy!</p>
+  <h3>Features</h3>
+  <ul>
+    <li>It actually works</li>
+    <li>It exists</li>
+    <li>It doesn't cost much!</li>
+  </ul>
+  <!--You can pretty much put any html in here!-->
+</div>""";
+dom.Document document = htmlparser.parse(htmlData);
+/// sanitize or query document here
+Widget html = Html(
+  document: document,
+);
+```
+
 ### onLinkTap:
 
 A function that defines what the widget should do when a link is tapped.
diff --git a/lib/flutter_html.dart b/lib/flutter_html.dart
@@ -5,14 +5,15 @@ import 'package:flutter_html/html_parser.dart';
 import 'package:flutter_html/image_render.dart';
 import 'package:flutter_html/style.dart';
 import 'package:webview_flutter/webview_flutter.dart';
+import 'package:html/dom.dart' as dom;
 
 class Html extends StatelessWidget {
   /// The `Html` widget takes HTML as input and displays a RichText
   /// tree of the parsed HTML content.
   ///
   /// **Attributes**
-  /// **data** *required* takes in a String of HTML data.
-  ///
+  /// **data** *required* takes in a String of HTML data (required only for `Html` constructor).
+  /// **document** *required* takes in a Document of HTML data (required only for `Html.fromDom` constructor).
   ///
   /// **onLinkTap** This function is called whenever a link (`<a href>`)
   /// is tapped.
@@ -44,24 +45,57 @@ class Html extends StatelessWidget {
     this.blacklistedElements = const [],
     this.style = const {},
     this.navigationDelegateForIframe,
-  }) : super(key: key);
+  }) : document = null,
+        assert (data != null),
+        super(key: key);
 
-  final String data;
+  Html.fromDom({
+    Key? key,
+    @required this.document,
+    this.onLinkTap,
+    this.customRender = const {},
+    this.customImageRenders = const {},
+    this.onImageError,
+    this.shrinkWrap = false,
+    this.onImageTap,
+    this.blacklistedElements = const [],
+    this.style = const {},
+    this.navigationDelegateForIframe,
+  }) : data = null,
+        assert(document != null),
+        super(key: key);
+
+  /// The HTML data passed to the widget as a String
+  final String? data;
+
+  /// The HTML data passed to the widget as a pre-processed [dom.Document]
+  final dom.Document? document;
+
+  /// A function that defines what to do when a link is tapped
   final OnTap? onLinkTap;
+
+  /// An API that allows you to customize the entire process of image rendering.
+  /// See the README for more details.
   final Map<ImageSourceMatcher, ImageRender> customImageRenders;
+
+  /// A function that defines what to do when an image errors
   final ImageErrorListener? onImageError;
+
+  /// A parameter that should be set when the HTML widget is expected to be
+  /// flexible
   final bool shrinkWrap;
 
-  /// Properties for the Image widget that gets rendered by the rich text parser
+  /// A function that defines what to do when an image is tapped
   final OnTap? onImageTap;
 
+  /// A list of HTML tags that defines what elements are not rendered
   final List<String> blacklistedElements;
 
   /// Either return a custom widget for specific node types or return null to
   /// fallback to the default rendering.
   final Map<String, CustomRender> customRender;
 
-  /// Fancy New Parser parameters
+  /// An API that allows you to override the default style for any HTML element
   final Map<String, Style> style;
 
   /// Decides how to handle a specific navigation request in the WebView of an
@@ -71,12 +105,13 @@ class Html extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
+    final dom.Document doc = data != null ? HtmlParser.parseHTML(data!) : document!;
     final double? width = shrinkWrap ? null : MediaQuery.of(context).size.width;
 
     return Container(
       width: width,
       child: HtmlParser(
-        htmlData: data,
+        htmlData: doc,
         onLinkTap: onLinkTap,
         onImageTap: onImageTap,
         onImageError: onImageError,
diff --git a/lib/html_parser.dart b/lib/html_parser.dart
@@ -30,7 +30,7 @@ typedef CustomRender = dynamic Function(
 );
 
 class HtmlParser extends StatelessWidget {
-  final String htmlData;
+  final dom.Document htmlData;
   final OnTap? onLinkTap;
   final OnTap? onImageTap;
   final ImageErrorListener? onImageError;
@@ -57,9 +57,8 @@ class HtmlParser extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    dom.Document document = parseHTML(htmlData);
     StyledElement lexedTree = lexDomTree(
-      document,
+      htmlData,
       customRender.keys.toList(),
       blacklistedElements,
       navigationDelegateForIframe,
