Add mammoth.transforms.paragraph

5 files changed, 58 insertions, 0 deletions

diff --git a/NEWS b/NEWS
index 300ee46..7823687 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,7 @@
+# 0.3.6
+
+* Add helper `mammoth.transforms.paragraph`.
+
 # 0.3.5
 
 * Add `mammoth.images.inline`, and document custom image conversion.
diff --git a/README.md b/README.md
index c5fbb84..b583843 100644
--- a/README.md
+++ b/README.md
@@ -220,6 +220,22 @@ var options = {
 The return value of `transformDocument` is used during HTML generation.
 The original document (and any child elements) can be safely modified.
 
+The above can be written more succinctly using the helper `mammoth.transforms.paragraph`:
+
+```javascript
+
+function transformParagraph(element) {
+    if (element.alignment === "center" && !element.styleId) {
+        element.styleId = "Heading2";
+    }
+    return element;
+}
+
+var options = {
+    transformDocument: mammoth.transforms.paragraph(transformParagraph)
+};
+```
+
 ### API
 
 #### `mammoth.convertToHtml(input, options)`
@@ -315,6 +331,13 @@ mammoth.images.inline(function(element) {
 })
 ```
 
+#### `mammoth.transforms.paragraph(transformParagraph)`
+
+Returns a function that can be used as the `transformDocument` option.
+This will apply the function `transformParagraph` to each paragraph element.
+`transformParagraph` should return the new paragraph,
+and is allowed to mutate the original paragraph.
+
 ## Writing style maps
 
 A style map is made up of a number of style mappings separated by new lines.
diff --git a/lib/index.js b/lib/index.js
index 442c8a7..a6962b3 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -6,6 +6,7 @@ var readOptions = require("./options-reader").readOptions;
 exports.convertToHtml = convertToHtml;
 exports.extractRawText = extractRawText;
 exports.images = require("./images");
+exports.transforms = require("./transforms");
 
 function convertToHtml(input, options) {
     var fullOptions = readOptions(options);
diff --git a/lib/transforms.js b/lib/transforms.js
new file mode 100644
index 0000000..988b456
--- /dev/null
+++ b/lib/transforms.js
@@ -0,0 +1,15 @@
+exports.paragraph = function(transform) {
+    function transformElement(element) {
+        if (element.children) {
+            for (var i = 0; i < element.children.length; i++) {
+                element.children[i] = transformElement(element.children[i]);
+            }
+        }
+        if (element.type === "paragraph") {
+            return transform(element);
+        } else {
+            return element;
+        }
+    }
+    return transformElement;
+};
diff --git a/tests/mammoth.tests.js b/tests/mammoth.tests.js
index 0fcdcf9..a14639d 100644
--- a/tests/mammoth.tests.js
+++ b/tests/mammoth.tests.js
@@ -69,6 +69,21 @@ describe('mammoth', function() {
         });
     });
     
+    test('mammoth.transforms.paragraph only transforms paragraphs', function() {
+        var docxFile = createFakeDocxFile({
+            "word/document.xml": testData("simple/word/document.xml")
+        });
+        var options = {
+            transformDocument: mammoth.transforms.paragraph(function(paragraph) {
+                paragraph.styleId = "Heading1";
+                return paragraph;
+            })
+        };
+        return mammoth.convertToHtml({file: docxFile}, options).then(function(result) {
+            assert.equal("<h1>Hello.</h1>", result.value);
+        });
+    });
+    
     test('inline images are included in output', function() {
         var docxPath = path.join(__dirname, "test-data/tiny-picture.docx");
         return mammoth.convertToHtml({path: docxPath}).then(function(result) {