README: Add usage example for AttributeProvider (#64)

Author: robinst

README.md

@@ -99,26 +99,60 @@ class WordCountVisitor extends AbstractVisitor {
 }
 ```
 
-#### Customize HTML rendering
+#### Add or change attributes of HTML elements
 
-Sometimes you might want to customize how HTML is rendered, or you added
-custom node subclasses that you want to render to HTML. Both can be done
-using node renderers.
+Sometimes you might want to customize how HTML is rendered. If all you
+want to do is add or change attributes on some elements, there's a
+simple way to do that.
 
-In this example, we're changing the rendering of indented code blocks:
+In this example, we register a factory for an `AttributeProvider` on the
+renderer to set a `class="border"` attribute on `img` elements.
 
 ```java
 Parser parser = Parser.builder().build();
-HtmlNodeRendererFactory factory = new HtmlNodeRendererFactory() {
+HtmlRenderer renderer = HtmlRenderer.builder()
+        .attributeProviderFactory(new AttributeProviderFactory() {
+            public AttributeProvider create(AttributeProviderContext context) {
+                return new ImageAttributeProvider();
+            }
+        })
+        .build();
+
+Node document = parser.parse("![text](/url.png)");
+renderer.render(document);
+// "<p><img src=\"/url.png\" alt=\"text\" class=\"border\" /></p>\n"
+
+class ImageAttributeProvider implements AttributeProvider {
     @Override
-    public NodeRenderer create(HtmlNodeRendererContext context) {
-        return new IndentedCodeBlockNodeRenderer(context);
+    public void setAttributes(Node node, Map<String, String> attributes) {
+        if (node instanceof Image) {
+            attributes.put("class", "border");
+        }
     }
-};
-HtmlRenderer renderer = HtmlRenderer.builder().nodeRendererFactory(factory).build();
+}
+```
+
+#### Customize HTML rendering
+
+If you want to do more than just change attributes, there's also a way
+to take complete control over how HTML is rendered.
+
+In this example, we're changing the rendering of indented code blocks to
+only wrap them in `pre` instead of `pre` and `code`:
+
+```java
+Parser parser = Parser.builder().build();
+HtmlRenderer renderer = HtmlRenderer.builder()
+        .nodeRendererFactory(new HtmlNodeRendererFactory() {
+            public NodeRenderer create(HtmlNodeRendererContext context) {
+                return new IndentedCodeBlockNodeRenderer(context);
+            }
+        })
+        .build();
 
 Node document = parser.parse("Example:\n\n    code");
-renderer.render(document);  // "<p>Example:</p>\n<pre>code\n</pre>\n"
+renderer.render(document);
+// "<p>Example:</p>\n<pre>code\n</pre>\n"
 
 class IndentedCodeBlockNodeRenderer implements NodeRenderer {
 
@@ -147,6 +181,15 @@ class IndentedCodeBlockNodeRenderer implements NodeRenderer {
 }
 ```
 
+#### Add your own node types
+
+In case you want to store additional data in the document or have custom
+elements in the resulting HTML, you can create your own subclass of
+`CustomNode` and add instances as child nodes to existing nodes.
+
+To define the HTML rendering for them, you can use a `NodeRenderer` as
+explained above.
+
 ### API documentation
 
 Javadocs are available online on

commonmark/src/test/java/org/commonmark/test/UsageExampleTest.java

@@ -1,18 +1,13 @@
 package org.commonmark.test;
 
-import org.commonmark.node.AbstractVisitor;
-import org.commonmark.node.IndentedCodeBlock;
-import org.commonmark.node.Node;
-import org.commonmark.node.Text;
+import org.commonmark.node.*;
 import org.commonmark.parser.Parser;
 import org.commonmark.renderer.NodeRenderer;
-import org.commonmark.renderer.html.HtmlNodeRendererContext;
-import org.commonmark.renderer.html.HtmlNodeRendererFactory;
-import org.commonmark.renderer.html.HtmlRenderer;
-import org.commonmark.renderer.html.HtmlWriter;
+import org.commonmark.renderer.html.*;
 import org.junit.Test;
 
 import java.util.Collections;
+import java.util.Map;
 import java.util.Set;
 
 import static org.junit.Assert.assertEquals;
@@ -36,16 +31,32 @@ public void visitor() {
         assertEquals(4, visitor.wordCount);
     }
 
+    @Test
+    public void addAttributes() {
+        Parser parser = Parser.builder().build();
+        HtmlRenderer renderer = HtmlRenderer.builder()
+                .attributeProviderFactory(new AttributeProviderFactory() {
+                    public AttributeProvider create(AttributeProviderContext context) {
+                        return new ImageAttributeProvider();
+                    }
+                })
+                .build();
+
+        Node document = parser.parse("![text](/url.png)");
+        assertEquals("<p><img src=\"/url.png\" alt=\"text\" class=\"border\" /></p>\n",
+                renderer.render(document));
+    }
+
     @Test
     public void customizeRendering() {
         Parser parser = Parser.builder().build();
-        HtmlNodeRendererFactory factory = new HtmlNodeRendererFactory() {
-            @Override
-            public NodeRenderer create(HtmlNodeRendererContext context) {
-                return new IndentedCodeBlockNodeRenderer(context);
-            }
-        };
-        HtmlRenderer renderer = HtmlRenderer.builder().nodeRendererFactory(factory).build();
+        HtmlRenderer renderer = HtmlRenderer.builder()
+                .nodeRendererFactory(new HtmlNodeRendererFactory() {
+                    public NodeRenderer create(HtmlNodeRendererContext context) {
+                        return new IndentedCodeBlockNodeRenderer(context);
+                    }
+                })
+                .build();
 
         Node document = parser.parse("Example:\n\n    code");
         assertEquals("<p>Example:</p>\n<pre>code\n</pre>\n", renderer.render(document));
@@ -67,6 +78,15 @@ public void visit(Text text) {
         }
     }
 
+    class ImageAttributeProvider implements AttributeProvider {
+        @Override
+        public void setAttributes(Node node, Map<String, String> attributes) {
+            if (node instanceof Image) {
+                attributes.put("class", "border");
+            }
+        }
+    }
+
     class IndentedCodeBlockNodeRenderer implements NodeRenderer {
 
         private final HtmlWriter html;