Skip to content

Commit 93303a5

Browse files
author
Nguyen Dat
committed
add maxlines support
2 parents 8391d56 + df53f43 commit 93303a5

16 files changed

+580
-99
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,3 +149,5 @@ modules.xml
149149
**/.flutter-plugins-dependencies
150150

151151
**/flutter_export_environment.sh
152+
153+
/example/ios/Flutter/Flutter.podspec

‎README.md

Lines changed: 107 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,15 +33,21 @@ A Flutter widget for rendering HTML and CSS as Flutter widgets.
3333

3434
- [API Reference](#api-reference)
3535

36+
- [Constructors](#constructors)
37+
3638
- [Parameters Table](#parameters)
3739

3840
- [Data](#data)
41+
42+
- [Document](#document)
3943

4044
- [onLinkTap](#onlinktap)
4145

4246
- [customRender](#customrender)
4347

4448
- [onImageError](#onimageerror)
49+
50+
- [onMathError](#onmatherror)
4551

4652
- [onImageTap](#onimagetap)
4753

@@ -71,6 +77,10 @@ A Flutter widget for rendering HTML and CSS as Flutter widgets.
7177

7278
- [SVG](#svg)
7379

80+
- [MathML](#mathml)
81+
82+
- [Tex](#tex)
83+
7484
- [Table](#table)
7585

7686
- [Notes](#notes)
@@ -96,8 +106,8 @@ Add the following to your `pubspec.yaml` file:
96106
| `mark` | `nav` | `noscript`|`ol` | `p` | `pre` | `q` | `rp` | `rt` | `ruby` | `s` |
97107
| `samp` | `section` | `small` | `span`| `strike` | `strong`| `sub` | `sup` | `summary` | `svg`| `table`|
98108
| `tbody` | `td` | `template` | `tfoot` | `th` | `thead` |`time` | `tr` | `tt` | `u` | `ul` |
99-
| `var` | `video` | | | | | | | | | |
100-
109+
| `var` | `video` | `math`: | `mrow` | `msup` | `msub` | `mover` | `munder` | `msubsup` | `moverunder` | `mfrac` |
110+
| `mlongdiv` | `msqrt` | `mroot` | `mi` | `mn` | `mo` | | | | | |
101111

102112

103113
## Currently Supported CSS Attributes:
@@ -131,14 +141,24 @@ For a full example, see [here](https://github.com/Sub6Resources/flutter_html/tre
131141

132142
Below, you will find brief descriptions of the parameters the`Html` widget accepts and some code snippets to help you use this package.
133143

144+
## Constructors:
145+
146+
The package currently has two different constructors - `Html()` and `Html.fromDom()`.
147+
148+
The `Html()` constructor is for those who would like to directly pass HTML from the source to the package to be rendered.
149+
150+
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.
151+
134152
### Parameters:
135153

136154
| Parameters | Description |
137155
|--------------|-----------------|
138-
| `data` | The HTML data passed to the `Html` widget. This is required and cannot be null. |
156+
| `data` | The HTML data passed to the `Html` widget. This is required and cannot be null when using `Html()`. |
157+
| `document` | The DOM document passed to the `Html` widget. This is required and cannot be null when using `Html.fromDom()`. |
139158
| `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. |
140159
| `customRender` | A powerful API that allows you to customize everything when rendering a specific HTML tag. |
141160
| `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. |
161+
| `omMathError` | A function that defines what the widget should do when a math fails to render. The function exposes the parsed Tex `String`, as well as the error and error with type from `flutter_math` as a `String`. |
142162
| `shrinkWrap` | A `bool` used while rendering different widgets to specify whether they should be shrink-wrapped or not, like `ContainerSpan` |
143163
| `onImageTap` | A function that defines what the widget should do when an image is tapped. The function exposes the `src` of the image as a `String` to use in your implementation. |
144164
| `blacklistedElements` | A list of elements the `Html` widget should not render. The list should contain the tags of the HTML elements you wish to blacklist. |
@@ -148,7 +168,7 @@ Below, you will find brief descriptions of the parameters the`Html` widget accep
148168

149169
### Data:
150170

151-
The HTML data passed to the `Html` widget as a `String`. This is required and cannot be null.
171+
The HTML data passed to the `Html` widget as a `String`. This is required and cannot be null when using `Html`.
152172
Any HTML tags in the `String` that are not supported by the package will not be rendered.
153173

154174
#### Example Usage - Data:
@@ -169,6 +189,36 @@ Widget html = Html(
169189
);
170190
```
171191

192+
### Document:
193+
194+
The DOM document passed to the `Html` widget as a `Document`. This is required and cannot be null when using `Html.fromDom()`.
195+
Any HTML tags in the document that are not supported by the package will not be rendered.
196+
Using the `Html.fromDom()` constructor can be useful when you would like to sanitize the HTML string yourself before passing it to the package.
197+
198+
#### Example Usage - Document:
199+
200+
```dart
201+
import 'package:html/parser.dart' as htmlparser;
202+
import 'package:html/dom.dart' as dom;
203+
...
204+
String htmlData = """<div>
205+
<h1>Demo Page</h1>
206+
<p>This is a fantastic product that you should buy!</p>
207+
<h3>Features</h3>
208+
<ul>
209+
<li>It actually works</li>
210+
<li>It exists</li>
211+
<li>It doesn't cost much!</li>
212+
</ul>
213+
<!--You can pretty much put any html in here!-->
214+
</div>""";
215+
dom.Document document = htmlparser.parse(htmlData);
216+
/// sanitize or query document here
217+
Widget html = Html(
218+
document: document,
219+
);
220+
```
221+
172222
### onLinkTap:
173223

174224
A function that defines what the widget should do when a link is tapped.
@@ -292,6 +342,24 @@ Widget html = Html(
292342
);
293343
```
294344

345+
### onMathError:
346+
347+
A function that defines what the widget should do when a math fails to render. The function exposes the parsed Tex `String`, as well as the error and error with type from `flutter_math` as a `String`.
348+
349+
#### Example Usage - onMathError:
350+
351+
```dart
352+
Widget html = Html(
353+
data: """<!-- Some MathML string that fails to parse -->""",
354+
onMathError: (String parsedTex, String error, String errorWithType) {
355+
//your logic here. A Widget must be returned from this function:
356+
return Text(error);
357+
//you can also try and fix the parsing yourself:
358+
return Math.tex(correctedParsedTex);
359+
},
360+
);
361+
```
362+
295363
### onImageTap:
296364

297365
A function that defines what the widget should do when an image is tapped.
@@ -636,6 +704,41 @@ This package renders svg elements using the [`flutter_svg`](https://pub.dev/pack
636704

637705
When rendering SVGs, the package takes the SVG data within the `<svg>` tag and passes it to `flutter_svg`. The `width` and `height` attributes are considered while rendering, if given.
638706

707+
### MathML
708+
709+
This package renders MathML elements using the [`flutter_math`](https://pub.dev/packages/flutter_math) plugin.
710+
711+
When rendering MathML, the package takes the MathML data within the `<math>` tag and tries to parse it to Tex. Then, it will pass the parsed string to `flutter_math`.
712+
713+
Because this package is parsing MathML to Tex, it may not support some functionalities. The current list of supported tags can be found [above](#currently-supported-html-tags), but some of these only have partial support at the moment.
714+
715+
If the parsing errors, you can use the [onMathError](#onmatherror) API to catch the error and potentially fix it on your end - you can analyze the error and the parsed string, and finally return a new instance of `Math.tex()` with the corrected Tex string.
716+
717+
If you'd like to see more MathML features, feel free to create a PR or file a feature request!
718+
719+
### Tex
720+
721+
If you have a Tex string you'd like to render inside your HTML you can do that using the same [`flutter_math`](https://pub.dev/packages/flutter_math) plugin.
722+
723+
Use a custom tag inside your HTML (an example could be `<tex>`), and place your **raw** Tex string inside.
724+
725+
Then, use the `customRender` parameter to add the widget to render Tex. It could look like this:
726+
727+
```dart
728+
Widget htmlWidget = Html(
729+
data: r"""<tex>i\hbar\frac{\partial}{\partial t}\Psi(\vec x,t) = -\frac{\hbar}{2m}\nabla^2\Psi(\vec x,t)+ V(\vec x)\Psi(\vec x,t)</tex>""",
730+
customRender: {
731+
"tex": (_, __, ___, element) => Math.tex(
732+
element.text,
733+
onErrorFallback: (FlutterMathException e) {
734+
//return your error widget here e.g.
735+
return Text(e.message);
736+
},
737+
),
738+
}
739+
);
740+
```
741+
639742
### Table
640743

641744
This package renders table elements using the [`flutter_layout_grid`](https://pub.dev/packages/flutter_layout_grid) plugin.

‎example/ios/Podfile.lock

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ EXTERNAL SOURCES:
2626
SPEC CHECKSUMS:
2727
Flutter: 434fef37c0980e73bb6479ef766c45957d4b510c
2828
video_player: 9cc823b1d9da7e8427ee591e8438bfbcde500e6e
29-
wakelock: bfc7955c418d0db797614075aabbc58a39ab5107
30-
webview_flutter: d2b4d6c66968ad042ad94cbb791f5b72b4678a96
29+
wakelock: b0843b2479edbf6504d8d262c2959446f35373aa
30+
webview_flutter: 9f491a9b5a66f2573946a389b2677987b0ff8c0b
3131

3232
PODFILE CHECKSUM: 8e679eca47255a8ca8067c4c67aab20e64cb974d
3333

0 commit comments

Comments
 (0)