Skip to content

Commit 0c68d36

Browse files
Sub6ResourcesSub6Resources
committed
Update documentation
1 parent 5be653d commit 0c68d36

File tree

3 files changed

+132
-45
lines changed

3 files changed

+132
-45
lines changed

‎lib/flutter_html.dart

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,32 @@ import 'package:flutter_html/style.dart';
77
import 'image_properties.dart';
88

99
class Html extends StatelessWidget {
10+
/// The `Html` widget takes HTML as input and displays a RichText
11+
/// tree of the parsed HTML content.
12+
///
13+
/// **Attributes**
14+
/// **data** *required* takes in a String of HTML data.
15+
///
16+
/// **css** currently does nothing
17+
///
18+
/// **onLinkTap** This function is called whenever a link (`<a href>`)
19+
/// is tapped.
20+
/// **customRender** This function allows you to return your own widgets
21+
/// for existing or custom HTML tags.
22+
/// See [its wiki page](https://github.com/Sub6Resources/flutter_html/wiki/All-About-customRender) for more info.
23+
///
24+
/// **onImageError** This is called whenever an image fails to load or
25+
/// display on the page.
26+
///
27+
/// **shrinkWrap** This makes the Html widget take up only the width it
28+
/// needs and no more.
29+
///
30+
/// **onImageTap** This is called whenever an image is tapped.
31+
///
32+
/// **blacklistedElements** Tag names in this array are ignored during parsing and rendering.
33+
///
34+
/// **style** Pass in the style information for the Html here.
35+
/// See [its wiki page](https://github.com/Sub6Resources/flutter_html/wiki/Style) for more info.
1036
Html({
1137
Key key,
1238
@required this.data,
@@ -15,13 +41,13 @@ class Html extends StatelessWidget {
1541
@deprecated this.backgroundColor,
1642
@deprecated this.defaultTextStyle,
1743
this.onLinkTap,
18-
@deprecated this.renderNewlines = false, //TODO(Sub6Resources): Document alternatives
44+
@deprecated this.renderNewlines = false,
1945
this.customRender,
2046
@deprecated this.customEdgeInsets,
2147
@deprecated this.customTextStyle,
2248
@deprecated this.blockSpacing = 14.0,
2349
@deprecated this.useRichText = false,
24-
@deprecated this.customTextAlign,
50+
@deprecated this.customTextAlign, //TODO Add alternative for this
2551
this.onImageError,
2652
@deprecated this.linkStyle = const TextStyle(
2753
decoration: TextDecoration.underline,

‎lib/html_parser.dart

Lines changed: 38 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -66,12 +66,12 @@ class HtmlParser extends StatelessWidget {
6666
return RichText(text: parsedTree);
6767
}
6868

69-
/// [parseHTML] converts a string to a DOM document using the dart `html` library.
69+
/// [parseHTML] converts a string of HTML to a DOM document using the dart `html` library.
7070
static dom.Document parseHTML(String data) {
7171
return htmlparser.parse(data);
7272
}
7373

74-
///TODO document
74+
/// [parseCSS] converts a string of CSS to a CSS stylesheet using the dart `csslib` library.
7575
static css.StyleSheet parseCSS(String data) {
7676
return cssparser.parse(data);
7777
}
@@ -92,7 +92,10 @@ class HtmlParser extends StatelessWidget {
9292
return tree;
9393
}
9494

95-
///TODO document
95+
/// [_recursiveLexer] is the recursive worker function for [lexDomTree].
96+
///
97+
/// It runs the parse functions of every type of
98+
/// element and returns a [StyledElement] tree representing the element.
9699
static StyledElement _recursiveLexer(
97100
dom.Node node, List<String> customRenderTags, List<String> blacklistedElements) {
98101
List<StyledElement> children = List<StyledElement>();
@@ -156,7 +159,7 @@ class HtmlParser extends StatelessWidget {
156159
}
157160

158161
/// [applyCustomStyles] applies the [Style] objects passed into the [Html]
159-
/// widget onto the [StyledElement] tree.
162+
/// widget onto the [StyledElement] tree, no cascading of styles is done at this point.
160163
StyledElement _applyCustomStyles(StyledElement tree) {
161164
if (style == null) return tree;
162165
style.forEach((key, style) {
@@ -173,6 +176,8 @@ class HtmlParser extends StatelessWidget {
173176
return tree;
174177
}
175178

179+
/// [_cascadeStyles] cascades all of the inherited styles down the tree, applying them to each
180+
/// child that doesn't specify a different style.
176181
StyledElement _cascadeStyles(StyledElement tree) {
177182
tree.children?.forEach((child) {
178183
child.style = tree.style.copyOnlyInherited(child.style);
@@ -197,6 +202,9 @@ class HtmlParser extends StatelessWidget {
197202
}
198203

199204
/// [parseTree] converts a tree of [StyledElement]s to an [InlineSpan] tree.
205+
///
206+
/// [parseTree] is responsible for handling the [customRender] parameter and
207+
/// deciding what different `Style.display` options look like as Widgets.
200208
InlineSpan parseTree(RenderContext context, StyledElement tree) {
201209
// Merge this element's style into the context so that children
202210
// inherit the correct style
@@ -347,14 +355,18 @@ class HtmlParser extends StatelessWidget {
347355
return tree;
348356
}
349357

350-
///TODO document
358+
/// [_processInlineWhitespace] is responsible for removing redundant whitespace
359+
/// between and among inline elements. It does so by creating a boolean [Context]
360+
/// and passing it to the [_processInlineWhitespaceRecursive] function.
351361
static StyledElement _processInlineWhitespace(StyledElement tree) {
352362
final whitespaceParsingContext = Context(false);
353363
tree = _processInlineWhitespaceRecursive(tree, whitespaceParsingContext);
354364
return tree;
355365
}
356366

357-
///TODO document
367+
/// [_processInlineWhitespaceRecursive] analyzes the whitespace between and among different
368+
/// inline elements, and replaces any instance of two or more spaces with a single space, according
369+
/// to the w3's HTML whitespace processing specification linked to above.
358370
static StyledElement _processInlineWhitespaceRecursive(StyledElement tree, Context<bool> wpc) {
359371
if (tree.style.display == Display.BLOCK) {
360372
wpc.data = false;
@@ -394,27 +406,16 @@ class HtmlParser extends StatelessWidget {
394406
}
395407

396408
/// [processListCharacters] adds list characters to the front of all list items.
397-
/// TODO document better
409+
///
410+
/// The function uses the [_processListCharactersRecursive] function to do most of its work.
398411
static StyledElement _processListCharacters(StyledElement tree) {
399-
// if (tree.name == "ol" || tree.name == "ul") {
400-
// for (int i = 0; i < tree.children?.length; i++) {
401-
// if (tree.children[i].name == "li") {
402-
// switch(tree.style.listStyleType) {
403-
// case ListStyleType.DISC:
404-
// tree.children[i].style.markerContent = '•';
405-
// break;
406-
// case ListStyleType.DECIMAL:
407-
// tree.children[i].style.markerContent = '${i + 1}.';
408-
// break;
409-
// }}
410-
// }
411-
// }
412-
// tree.children?.forEach(_processListCharacters);
413412
final olStack = ListQueue<Context<int>>();
414413
tree = _processListCharactersRecursive(tree, olStack);
415414
return tree;
416415
}
417416

417+
/// [_processListCharactersRecursive] uses a Stack of integers to properly number and
418+
/// bullet all list items according to the [ListStyleType] they have been given.
418419
static StyledElement _processListCharactersRecursive(
419420
StyledElement tree, ListQueue<Context<int>> olStack) {
420421
if (tree.name == 'ol') {
@@ -439,7 +440,9 @@ class HtmlParser extends StatelessWidget {
439440
return tree;
440441
}
441442

442-
/// TODO document better
443+
/// [_processBeforesAndAfters] adds text content to the beginning and end of
444+
/// the list of the trees children according to the `before` and `after` Style
445+
/// properties.
443446
static StyledElement _processBeforesAndAfters(StyledElement tree) {
444447
if (tree.style?.before != null) {
445448
tree.children.insert(0, TextContentElement(text: tree.style.before));
@@ -550,6 +553,9 @@ class HtmlParser extends StatelessWidget {
550553
}
551554

552555
/// [removeEmptyElements] recursively removes empty elements.
556+
///
557+
/// An empty element is any [EmptyContentElement], any empty [TextContentElement],
558+
/// or any block-level [TextContentElement] that contains only whitespace.
553559
static StyledElement _removeEmptyElements(StyledElement tree) {
554560
List<StyledElement> toRemove = new List<StyledElement>();
555561
tree.children?.forEach((child) {
@@ -561,7 +567,6 @@ class HtmlParser extends StatelessWidget {
561567
child.style.whiteSpace != WhiteSpace.PRE &&
562568
tree.style.display == Display.BLOCK &&
563569
child.text.trim().isEmpty) {
564-
//TODO should this be moved to the whitespace functions?
565570
toRemove.add(child);
566571
} else {
567572
_removeEmptyElements(child);
@@ -572,6 +577,8 @@ class HtmlParser extends StatelessWidget {
572577
return tree;
573578
}
574579

580+
/// [_processFontSize] changes percent-based font sizes (negative numbers in this implementation)
581+
/// to pixel-based font sizes.
575582
static StyledElement _processFontSize(StyledElement tree) {
576583
double parentFontSize = tree.style?.fontSize?.size ?? FontSize.medium.size;
577584

@@ -586,7 +593,10 @@ class HtmlParser extends StatelessWidget {
586593
}
587594
}
588595

589-
///TODO document better
596+
/// The [RenderContext] is available when parsing the tree. It contains information
597+
/// about the [BuildContext] of the `Html` widget, contains the configuration available
598+
/// in the [HtmlParser], and contains information about the [Style] of the current
599+
/// tree root.
590600
class RenderContext {
591601
final BuildContext buildContext;
592602
final HtmlParser parser;
@@ -599,7 +609,10 @@ class RenderContext {
599609
});
600610
}
601611

602-
///TODO document
612+
/// A [ContainerSpan] is a widget with an [InlineSpan] child or children.
613+
///
614+
/// A [ContainerSpan] can have a border, background color, height, width, padding, and margin
615+
/// and can represent either an INLINE or BLOCK-level element.
603616
class ContainerSpan extends StatelessWidget {
604617
final Widget child;
605618
final List<InlineSpan> children;

‎lib/style.dart

Lines changed: 66 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,102 @@
11
import 'package:flutter/material.dart';
22

33
///This class represents all the available CSS attributes
4-
///for this package
4+
///for this package.
55
class Style {
6-
///CSS attribute "`background-color`"
6+
/// CSS attribute "`background-color`"
7+
///
8+
/// Inherited: no,
9+
/// Default: Colors.transparent,
710
Color backgroundColor;
811

9-
///CSS attribute "`color`"
12+
/// CSS attribute "`color`"
13+
///
14+
/// Inherited: yes,
15+
/// Default: unspecified,
1016
Color color;
1117

12-
///CSS attribute "`display`"
18+
/// CSS attribute "`display`"
19+
///
20+
/// Inherited: no,
21+
/// Default: unspecified,
1322
Display display;
1423

15-
///CSS attribute "`font-family`"
24+
/// CSS attribute "`font-family`"
25+
///
26+
/// Inherited: yes,
27+
/// Default: Theme.of(context).style.textTheme.body1.fontFamily
1628
String fontFamily;
1729

18-
///CSS attribute "`font-size`"
30+
/// CSS attribute "`font-size`"
31+
///
32+
/// Inherited: yes,
33+
/// Default: FontSize.medium
1934
FontSize fontSize;
2035

21-
///CSS attribute "`font-style`"
36+
/// CSS attribute "`font-style`"
37+
///
38+
/// Inherited: yes,
39+
/// Default: FontStyle.normal,
2240
FontStyle fontStyle;
2341

24-
///CSS attribute "`font-weight`"
42+
/// CSS attribute "`font-weight`"
43+
///
44+
/// Inherited: yes,
45+
/// Default: FontWeight.normal,
2546
FontWeight fontWeight;
2647

27-
///CSS attribute "`height`"
48+
/// CSS attribute "`height`"
49+
///
50+
/// Inherited: no,
51+
/// Default: Unspecified (null),
2852
double height;
2953

30-
///CSS attribute "`list-style-type`"
54+
/// CSS attribute "`list-style-type`"
55+
///
56+
/// Inherited: yes,
57+
/// Default: ListStyleType.DISC
3158
ListStyleType listStyleType;
3259

33-
///CSS attribute "`padding`"
60+
/// CSS attribute "`padding`"
61+
///
62+
/// Inherited: no,
63+
/// Default: EdgeInsets.zero
3464
EdgeInsets padding;
3565

36-
///CSS attribute "`margin`"
66+
/// CSS attribute "`margin`"
67+
///
68+
/// Inherited: no,
69+
/// Default: EdgeInsets.zero
3770
EdgeInsets margin;
3871

39-
///CSS attribute "`text-decoration`" -
72+
/// CSS attribute "`text-decoration`"
73+
///
74+
/// Inherited: no,
75+
/// Default: TextDecoration.none,
4076
TextDecoration textDecoration;
4177

42-
///CSS attribute "`text-decoration-style`" -
78+
/// CSS attribute "`text-decoration-style`"
79+
///
80+
/// Inherited: no,
81+
/// Default: TextDecorationStyle.solid,
4382
TextDecorationStyle textDecorationStyle;
4483

45-
///CSS attribute "`vertical-align`"
84+
/// CSS attribute "`vertical-align`"
85+
///
86+
/// Inherited: no,
87+
/// Default: VerticalAlign.BASELINE,
4688
VerticalAlign verticalAlign;
4789

48-
///CSS attribute "`white-space`"
90+
/// CSS attribute "`white-space`"
91+
///
92+
/// Inherited: yes,
93+
/// Default: WhiteSpace.NORMAL,
4994
WhiteSpace whiteSpace;
5095

51-
///CSS attribute "`width`"
96+
/// CSS attribute "`width`"
97+
///
98+
/// Inherited: no,
99+
/// Default: unspecified (null)
52100
double width;
53101

54102
//TODO modify these to match CSS styles
@@ -60,7 +108,7 @@ class Style {
60108
String markerContent;
61109

62110
Style({
63-
this.backgroundColor,
111+
this.backgroundColor = Colors.transparent,
64112
this.color,
65113
this.display,
66114
this.fontFamily,

0 commit comments

Comments
 (0)