From c7473fa37278fab44df74c72e0dc62f6be3c2ee6 Mon Sep 17 00:00:00 2001 From: Harald Pehl Date: Fri, 25 Aug 2023 20:27:10 +0200 Subject: [PATCH] Documentation --- CHANGELOG.md | 6 ++--- src/demo/java/ElementsBagDemo.java | 2 +- src/demo/java/ElementsDemo.java | 2 +- ...ontainerDemo.java => HasChildrenDemo.java} | 2 +- src/demo/java/SvgDemo.java | 24 +++++++++++++++++++ src/demo/java/TodoElement.java | 8 +++---- .../java/org/jboss/elemento/ElementsBag.java | 14 ++++++++--- .../java/org/jboss/elemento/HasChildren.java | 6 ++++- .../jboss/elemento/svg/SVGCircleElement.java | 6 +++++ .../org/jboss/elemento/svg/SVGElement.java | 5 ++++ .../jboss/elemento/svg/SVGEllipseElement.java | 6 +++++ .../org/jboss/elemento/svg/SVGGElement.java | 6 +++++ .../jboss/elemento/svg/SVGLineElement.java | 7 ++++++ .../jboss/elemento/svg/SVGPathElement.java | 6 +++++ .../jboss/elemento/svg/SVGPolygonElement.java | 7 ++++++ .../jboss/elemento/svg/SVGRectElement.java | 7 ++++++ .../jboss/elemento/svg/SVGTextElement.java | 6 +++++ .../elemento/svg/SvgContainerBuilder.java | 6 ++++- .../jboss/elemento/svg/SvgElementBuilder.java | 6 ++++- .../jboss/elemento/svg/WithSvgElement.java | 7 ++++-- 20 files changed, 121 insertions(+), 18 deletions(-) rename src/demo/java/{HtmlContainerDemo.java => HasChildrenDemo.java} (94%) create mode 100644 src/demo/java/SvgDemo.java diff --git a/CHANGELOG.md b/CHANGELOG.md index cf78234d2..bf3d7b7df 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), ## [Unreleased] -### CHanged +### Changed - Refactor builder classes for simple (empty) and container-like HTML and SVG elements @@ -22,7 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), ## [1.1.0] - 2023-08-23 -Please don't use this release. +Not an official release - please don't use! ## [1.0.15] - 2023-08-20 @@ -40,7 +40,7 @@ Please don't use this release. ## [1.0.14] - 2023-08-20 -Please don't use this release. +Not an official release - please don't use! ## [1.0.13] - 2023-08-03 diff --git a/src/demo/java/ElementsBagDemo.java b/src/demo/java/ElementsBagDemo.java index 1fa8606f5..398aa4de4 100644 --- a/src/demo/java/ElementsBagDemo.java +++ b/src/demo/java/ElementsBagDemo.java @@ -10,7 +10,7 @@ import static org.jboss.elemento.Elements.dl; import static org.jboss.elemento.Elements.dt; -@SuppressWarnings({"MismatchedQueryAndUpdateOfCollection", "RedundantOperationOnEmptyContainer", "unused"}) +@SuppressWarnings({"RedundantOperationOnEmptyContainer", "MismatchedQueryAndUpdateOfCollection"}) public class ElementsBagDemo { public void bagDemo() { diff --git a/src/demo/java/ElementsDemo.java b/src/demo/java/ElementsDemo.java index aa1499d72..a3401bfd6 100644 --- a/src/demo/java/ElementsDemo.java +++ b/src/demo/java/ElementsDemo.java @@ -79,7 +79,7 @@ public void findAllDemo() { public void streamDemo() { // @start region = stream - HTMLElement parent = find(document.body, By.data("foo", "bar")); + HTMLElement parent = find(body(), By.data("foo", "bar")); if (parent != null) { List htmlElements = stream(parent) .filter(htmlElements()) diff --git a/src/demo/java/HtmlContainerDemo.java b/src/demo/java/HasChildrenDemo.java similarity index 94% rename from src/demo/java/HtmlContainerDemo.java rename to src/demo/java/HasChildrenDemo.java index a593c5d47..c88d1bb96 100644 --- a/src/demo/java/HtmlContainerDemo.java +++ b/src/demo/java/HasChildrenDemo.java @@ -3,7 +3,7 @@ import static org.jboss.elemento.Elements.ul; @SuppressWarnings("unused") -public class HtmlContainerDemo { +public class HasChildrenDemo { public void addAllDemo() { // @start region = addAll diff --git a/src/demo/java/SvgDemo.java b/src/demo/java/SvgDemo.java new file mode 100644 index 000000000..44ed82a33 --- /dev/null +++ b/src/demo/java/SvgDemo.java @@ -0,0 +1,24 @@ +import org.jboss.elemento.By; + +import static org.jboss.elemento.By.AttributeOperator.STARTS_WITH; +import static org.jboss.elemento.Elements.circle; +import static org.jboss.elemento.Elements.g; +import static org.jboss.elemento.Elements.svg; + +@SuppressWarnings("unused") +public class SvgDemo { + + public void svgDemo() { + // @start region = svg + svg().css("spinner", "large") + .aria("label", "Loading...") + .attr("role", "progressbar") + .attr("viewBox", "0 0 100 100") + .add(circle().css("spinner", "path") + .attr("cx", 50) + .attr("cy", 50) + .attr("r", 45) + .attr("fill", "none")); + // @end region = svg + } +} diff --git a/src/demo/java/TodoElement.java b/src/demo/java/TodoElement.java index fdf8abcf8..7333b7976 100644 --- a/src/demo/java/TodoElement.java +++ b/src/demo/java/TodoElement.java @@ -33,7 +33,7 @@ public class TodoElement implements IsElement, Attachable { private HandlerRegistration handlerRegistration; TodoElement(Todo todo) { - this.root = li().data("item", todo.id) + root = li().data("item", todo.id) .add(div().css("view") .add(toggle = input(checkbox).css("toggle") .checked(todo.completed) @@ -42,9 +42,9 @@ public class TodoElement implements IsElement, Attachable { .add(destroy = button().css("destroy").element())) .add(summary = input(text).css("edit").element()) .element(); - this.root.classList.toggle("completed", todo.completed); - this.toggle.checked = todo.completed; - Attachable.register(this, this); + root.classList.toggle("completed", todo.completed); + toggle.checked = todo.completed; + Attachable.register(root, this); } @Override diff --git a/src/main/java/org/jboss/elemento/ElementsBag.java b/src/main/java/org/jboss/elemento/ElementsBag.java index 21e120b3d..d42a0b865 100644 --- a/src/main/java/org/jboss/elemento/ElementsBag.java +++ b/src/main/java/org/jboss/elemento/ElementsBag.java @@ -22,7 +22,7 @@ import elemental2.dom.HTMLElement; /** - * Class to collect {@link HTMLElement}s + * Class to collect {@link Element}s *

* {@snippet class = ElementsBagDemo region = bag} */ @@ -39,13 +39,13 @@ public ElementsBag that() { return this; } - // ------------------------------------------------------ mirror add() methods from HtmlContent - /** @return the elements in this bag. */ public Iterable elements() { return iterable; } + // ------------------------------------------------------ mirror add() methods from HasChildren + /** Adds the given element. */ public ElementsBag add(Element element) { iterable.elements.push(element); @@ -60,6 +60,14 @@ public ElementsBag add(IsElement element) { return that(); } + /** Adds all elements. */ + public ElementsBag addAll(Element... elements) { + for (Element element : elements) { + add(element); + } + return that(); + } + /** Adds all elements. */ public ElementsBag addAll(HTMLElement... elements) { for (HTMLElement element : elements) { diff --git a/src/main/java/org/jboss/elemento/HasChildren.java b/src/main/java/org/jboss/elemento/HasChildren.java index 5afd89651..25a9dd4fc 100644 --- a/src/main/java/org/jboss/elemento/HasChildren.java +++ b/src/main/java/org/jboss/elemento/HasChildren.java @@ -19,7 +19,11 @@ import elemental2.dom.HTMLElement; import elemental2.dom.Node; -/** Interface for elements with children */ +/** + * Interface for elements with children +

+ * {@snippet class = HasChildrenDemo region = addAll} + */ public interface HasChildren> extends TypedBuilder, IsElement { /** Adds the given node. */ diff --git a/src/main/java/org/jboss/elemento/svg/SVGCircleElement.java b/src/main/java/org/jboss/elemento/svg/SVGCircleElement.java index 69bd28565..4bcb2cbac 100644 --- a/src/main/java/org/jboss/elemento/svg/SVGCircleElement.java +++ b/src/main/java/org/jboss/elemento/svg/SVGCircleElement.java @@ -18,6 +18,12 @@ import jsinterop.annotations.JsPackage; import jsinterop.annotations.JsType; +/** + * The SVGCircleElement interface is an interface for the {@code } element. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGCircleElement + */ @JsType(isNative = true, namespace = JsPackage.GLOBAL) public class SVGCircleElement extends SVGElement { } diff --git a/src/main/java/org/jboss/elemento/svg/SVGElement.java b/src/main/java/org/jboss/elemento/svg/SVGElement.java index 2c9a1f392..8cbd2ae6a 100644 --- a/src/main/java/org/jboss/elemento/svg/SVGElement.java +++ b/src/main/java/org/jboss/elemento/svg/SVGElement.java @@ -22,6 +22,11 @@ import jsinterop.annotations.JsType; import jsinterop.base.JsPropertyMap; +/** + * All of the SVG DOM interfaces that correspond directly to elements in the SVG language derive from the SVGElement interface. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGElement + */ @JsType(isNative = true, namespace = JsPackage.GLOBAL) public class SVGElement extends Element { diff --git a/src/main/java/org/jboss/elemento/svg/SVGEllipseElement.java b/src/main/java/org/jboss/elemento/svg/SVGEllipseElement.java index 33b734354..a2016ee50 100644 --- a/src/main/java/org/jboss/elemento/svg/SVGEllipseElement.java +++ b/src/main/java/org/jboss/elemento/svg/SVGEllipseElement.java @@ -18,6 +18,12 @@ import jsinterop.annotations.JsPackage; import jsinterop.annotations.JsType; +/** + * The SVGEllipseElement interface provides access to the properties of {@code } elements. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGEllipseElement + */ @JsType(isNative = true, namespace = JsPackage.GLOBAL) public class SVGEllipseElement extends SVGElement { } diff --git a/src/main/java/org/jboss/elemento/svg/SVGGElement.java b/src/main/java/org/jboss/elemento/svg/SVGGElement.java index c8c2d75db..4b6004512 100644 --- a/src/main/java/org/jboss/elemento/svg/SVGGElement.java +++ b/src/main/java/org/jboss/elemento/svg/SVGGElement.java @@ -18,6 +18,12 @@ import jsinterop.annotations.JsPackage; import jsinterop.annotations.JsType; +/** + * The SVGGElement interface corresponds to the {@code } element. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGGElement + */ @JsType(isNative = true, namespace = JsPackage.GLOBAL) public class SVGGElement extends SVGElement { } diff --git a/src/main/java/org/jboss/elemento/svg/SVGLineElement.java b/src/main/java/org/jboss/elemento/svg/SVGLineElement.java index 6a1a68ef0..6191877fb 100644 --- a/src/main/java/org/jboss/elemento/svg/SVGLineElement.java +++ b/src/main/java/org/jboss/elemento/svg/SVGLineElement.java @@ -18,6 +18,13 @@ import jsinterop.annotations.JsPackage; import jsinterop.annotations.JsType; +/** + * The SVGLineElement interface provides access to the properties of {@code } elements, as well as methods to + * manipulate them. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGLineElement + */ @JsType(isNative = true, namespace = JsPackage.GLOBAL) public class SVGLineElement extends SVGElement { } diff --git a/src/main/java/org/jboss/elemento/svg/SVGPathElement.java b/src/main/java/org/jboss/elemento/svg/SVGPathElement.java index 16bb1693d..489951add 100644 --- a/src/main/java/org/jboss/elemento/svg/SVGPathElement.java +++ b/src/main/java/org/jboss/elemento/svg/SVGPathElement.java @@ -18,6 +18,12 @@ import jsinterop.annotations.JsPackage; import jsinterop.annotations.JsType; +/** + * The SVGPathElement interface corresponds to the {@code } element. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGPathElement + */ @JsType(isNative = true, namespace = JsPackage.GLOBAL) public class SVGPathElement extends SVGElement { } diff --git a/src/main/java/org/jboss/elemento/svg/SVGPolygonElement.java b/src/main/java/org/jboss/elemento/svg/SVGPolygonElement.java index 23a4b6d0c..8fae1a543 100644 --- a/src/main/java/org/jboss/elemento/svg/SVGPolygonElement.java +++ b/src/main/java/org/jboss/elemento/svg/SVGPolygonElement.java @@ -18,6 +18,13 @@ import jsinterop.annotations.JsPackage; import jsinterop.annotations.JsType; +/** + * The SVGPolygonElement interface provides access to the properties of {@code } elements, as well as methods to + * manipulate them. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGPolygonElement + */ @JsType(isNative = true, namespace = JsPackage.GLOBAL) public class SVGPolygonElement extends SVGElement { } diff --git a/src/main/java/org/jboss/elemento/svg/SVGRectElement.java b/src/main/java/org/jboss/elemento/svg/SVGRectElement.java index 617e6838a..97b4001e4 100644 --- a/src/main/java/org/jboss/elemento/svg/SVGRectElement.java +++ b/src/main/java/org/jboss/elemento/svg/SVGRectElement.java @@ -18,6 +18,13 @@ import jsinterop.annotations.JsPackage; import jsinterop.annotations.JsType; +/** + * The SVGRectElement interface provides access to the properties of {@code } elements, as well as methods to + * manipulate them. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGRectElement + */ @JsType(isNative = true, namespace = JsPackage.GLOBAL) public class SVGRectElement extends SVGElement { } diff --git a/src/main/java/org/jboss/elemento/svg/SVGTextElement.java b/src/main/java/org/jboss/elemento/svg/SVGTextElement.java index ae64cbce5..e09256b0b 100644 --- a/src/main/java/org/jboss/elemento/svg/SVGTextElement.java +++ b/src/main/java/org/jboss/elemento/svg/SVGTextElement.java @@ -18,6 +18,12 @@ import jsinterop.annotations.JsPackage; import jsinterop.annotations.JsType; +/** + * The SVGTextElement interface corresponds to the {@code } elements. + * + * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGTextElement + */ @JsType(isNative = true, namespace = JsPackage.GLOBAL) public class SVGTextElement extends SVGElement { } diff --git a/src/main/java/org/jboss/elemento/svg/SvgContainerBuilder.java b/src/main/java/org/jboss/elemento/svg/SvgContainerBuilder.java index 5d8884209..1704dc6dd 100644 --- a/src/main/java/org/jboss/elemento/svg/SvgContainerBuilder.java +++ b/src/main/java/org/jboss/elemento/svg/SvgContainerBuilder.java @@ -18,7 +18,11 @@ import org.jboss.elemento.ElementBuilder; import org.jboss.elemento.HasChildren; -/** Builder for container-like SVG elements. */ +/** + * Builder for container-like SVG elements. + *

+ * {@snippet class = SvgDemo region = svg} + */ public class SvgContainerBuilder extends ElementBuilder> implements WithSvgElement>, HasChildren> { diff --git a/src/main/java/org/jboss/elemento/svg/SvgElementBuilder.java b/src/main/java/org/jboss/elemento/svg/SvgElementBuilder.java index 64c304edf..254b8262d 100644 --- a/src/main/java/org/jboss/elemento/svg/SvgElementBuilder.java +++ b/src/main/java/org/jboss/elemento/svg/SvgElementBuilder.java @@ -17,7 +17,11 @@ import org.jboss.elemento.ElementBuilder; -/** Builder for simple SVG elements. */ +/** + * Builder for simple SVG elements. + *

+ * {@snippet class = SvgDemo region = svg} + */ public class SvgElementBuilder extends ElementBuilder> implements WithSvgElement> { diff --git a/src/main/java/org/jboss/elemento/svg/WithSvgElement.java b/src/main/java/org/jboss/elemento/svg/WithSvgElement.java index df80f7c68..b61ca4141 100644 --- a/src/main/java/org/jboss/elemento/svg/WithSvgElement.java +++ b/src/main/java/org/jboss/elemento/svg/WithSvgElement.java @@ -18,6 +18,9 @@ import org.jboss.elemento.IsElement; import org.jboss.elemento.TypedBuilder; +/** + * Combines common methods for manipulating an SVG element. + */ public interface WithSvgElement> extends TypedBuilder, IsElement { @@ -30,8 +33,8 @@ default B style(String style) { /** * Adds a {@code data-} attribute to the element. * - * @param name The name of the data attribute w/o the {@code data-} prefix. However, it won't be added if it's already - * present. + * @param name The name of the data attribute w/o the {@code data-} prefix. However, it won't be added if it's + * already present. */ default B data(String name, String value) { element().dataset.set(name.replaceFirst("^data-", ""), value);