BoxLang Word Module 📝

A powerful BoxLang module for creating, reading, populating, and converting Word documents.

╔═══════════════════════════════════════════════════════╗
║          ⚡ B o x L a n g  W o r d                   ║
║      Dynamic · Powerful · Production-Ready            ║
╚═══════════════════════════════════════════════════════╝

Copyright Since 2023 by Ortus Solutions, Corp
www.boxlang.io | www.ortussolutions.com

---

🎯 Overview

The BoxLang Word Module (bx-word) is a fluent document builder for .docx files in BoxLang. Built on It lets you create, populate, style, and export Word documents with a clean, chainable API. Import content from text, Markdown, and HTML on the fly.

API Type	Entry Point	Use Case
Fluent API ✨	word()	Modern chainable interface (recommended)
Importers 📥	.fromText() / .fromMarkdown() / .fromHTML()	Ingest content from multiple formats
Exporters 📤	.toText() / .toMarkdown() / .toHTML()	Convert documents to text or markup

💡 The fluent API is the recommended approach. Chain methods to build, style, and save documents in a single expression.

✨ Key Features

• ✨ Fluent Method Chaining — Intuitive, readable code
• 📝 Template Population — {{placeholder}} substitution with struct data
• 📊 Table Support — Arrays, Queries, and Struct-based tables with auto-header bolding
• 🎨 Rich Formatting — Bold, italic, colors, fonts, alignment, hyperlinks
• 📥 Multi-Format Import — Plain text, Markdown (CommonMark), HTML (Jsoup)
• 📤 Multi-Format Export — Plain text, Markdown, HTML (inline styles + base64 images)
• 🖼️ Image Embedding — From file path, byte array, or base64 string
• 📄 Page Setup — Margins, page size, orientation, headers, footers
• 🔗 Hyperlinks — Clickable links with underline styling
• 📋 Lists — Ordered and unordered lists with nested/indented support
• 📖 Document Properties — Title, author, subject, keywords
• 🔀 Content Importers — fromText(), fromMarkdown(), fromHTML() as fluent instance methods

📋 Requirements

• BoxLang Runtime 1.14.0 or higher
• BoxLang+ License — This module requires a BoxLang+ license

---

📦 Installation

Using CommandBox:

box install bx-word

---

🚀 Quick Start

Create Your First Document

// Build a document from scratch
word( "/path/to/report.docx" )
    .margins( 1.78, 1.78, 1.78, 1.78 )
    .addHeading( "My Report", 1 )
    .addParagraph( "Hello World" )
    .addTable( [ [ "Name", "Role" ], [ "John Doe", "Engineer" ] ] )
    .save()

Populate a Template

// Open an existing template and fill placeholders
word( "/templates/contract.docx" )
    .populate( { name: "John Doe", date: "2024-01-01" } )
    .save( "/output/contract.docx" );

Create from Text, Markdown, or HTML (BIF args)

// The word() BIF accepts text, markdown, and html arguments directly
word( text="Hello World\n\nParagraph two" )
    .save( "from-text.docx" );

word( markdown="## Title\n\nParagraph with **bold** text." )
    .save( "from-markdown.docx" );

word( html="<h1>Title</h1><p>Hello <b>World</b></p>" )
    .save( "from-html.docx" );

Import from Markdown or HTML (Instance Methods)

// Append content to an existing document
word().fromMarkdown( "## Title\n\nParagraph with **bold** text." )
    .save( "from-markdown.docx" );

word().fromHTML( "<h1>Title</h1><p>Hello <b>World</b></p>" )
    .save( "from-html.docx" );

Export to Text, Markdown, or HTML

// Build and convert in one chain
doc = word().addHeading( "Report", 1 ).addParagraph( "Content" );

plainText = doc.toText();       // plain text
markdown  = doc.toMarkdown();   // markdown with YAML front matter
html      = doc.toHTML();       // HTML with inline styles + base64 images

---

📖 API Reference

Lifecycle

Method	Description
word()	Create a new empty document
word( path )	Open an existing .docx file
word( text=... )	Create and populate from plain text
word( markdown=... )	Create and populate from Markdown
word( html=... )	Create and populate from HTML
.open( path )	Open an existing .docx file
.save( path )	Save to the given file path
.save()	Save back to the originally opened path
.toBytes()	Get document as byte array
.toBase64()	Get document as Base64 string
.writeTo( stream )	Write document to an OutputStream

Importers

Method	Description
.fromText( text )	Add paragraphs from plain text (splits on double-newlines)
.fromMarkdown( md )	Parse CommonMark and add headings, paragraphs, lists, etc.
.fromHTML( html )	Parse HTML and add headings, paragraphs, lists, tables, images, etc.

Exporters

Method	Description
.toText()	Extract all visible text (paragraphs + tables)
.toMarkdown()	Convert to Markdown with YAML front matter, pipe tables, base64 images
.toHTML()	Convert to HTML with inline styles, semantic tags, base64 images

Content

Method	Description
.addHeading( text, level )	Add a heading (level 1–6)
.addParagraph( text )	Add a plain text paragraph
.addParagraph( text, options )	Add a paragraph with formatting (bold, italic, size, color, alignment, font)
.addPageBreak()	Insert a page break
.newLine()	Add an empty line
.addTable( data )	Add a table from Array (2-D), Query, or Struct (headers + data)
.addUnorderedList( items )	Add a bulleted list (supports nested via structs)
.addOrderedList( items )	Add a numbered list (supports nested via structs)
.addHyperlink( text, url )	Add a clickable hyperlink
.addImage( path )	Add an image from a file path
.addImage( path, w, h )	Add an image with explicit width/height in cm
.addImage( bytes, filename )	Add an image from byte array
.addImageBase64( b64, filename )	Add an image from Base64 string

Page Setup

Method	Description
.margins( top, bottom, left, right )	Set all four margins in cm
.margins( options )	Set margins via struct (top, bottom, left, right)
.pageSize( size )	Set page size (A4, LETTER, LEGAL)
.orientation( orientation )	Set page orientation (portrait, landscape)
.header( text )	Set document header text
.footer( text )	Set document footer text

Template Population

Method	Description
.populate( data )	Replace {{variable}} placeholders with struct values
.replaceText( find, replace )	Literal find-and-replace across all paragraphs and tables
.setBookmark( name, value )	Set a named bookmark value
.setContentControl( tag, value )	Set a content control (SDT) by tag name

Document Properties

Method	Description
.setTitle( title )	Set the document title
.setAuthor( author )	Set the document author/creator
.setSubject( subject )	Set the document subject
.setKeywords( keywords )	Set comma-separated keywords
.setDefaultFont( family, size )	Apply a default font to all existing runs

---

💡 Common Patterns

Building a Sales Report

word()
    .margins( 1.5, 1.5, 1.5, 1.5 )
    .addHeading( "Q4 Sales Report", 1 )
    .addParagraph( "Generated on " & now(), { italic: true, size: 10 } )
    .addTable( [
        [ "Product", "Units", "Revenue" ],
        [ "Widget A", "1,200", "$36,000" ],
        [ "Widget B", "950", "$28,500" ]
    ] )
    .addPageBreak()
    .addHeading( "Summary", 2 )
    .addParagraph( "All targets exceeded for the quarter.", { bold: true } )
    .save( "sales-report.docx" );

Template-Based Contract Generation

clients = [ { name: "Acme Corp", date: "2024-01-15" }, { name: "Globex", date: "2024-01-20" } ];

clients.each( client => {
    word( "/templates/contract-template.docx" )
        .populate( { clientName: client.name, signDate: client.date } )
        .save( "/output/contract_#client.name#.docx" );
} );

Convert Between Formats

// HTML → Word → Markdown pipeline
doc = word().fromHTML( "<h1>Article</h1><p>Content with <b>bold</b> text.</p>" );
markdown = doc.toMarkdown();  // # Article\n\nContent with **bold** text.

// Or use BIF args for one-step creation + conversion
text = word( html="<h1>Title</h1>" ).toText();           // "Title"
md   = word( markdown="## Hello" ).toMarkdown();          // "---\n\n## Hello\n"
html = word( text="Hello\n\nWorld" ).toHTML();            // <!DOCTYPE html>...</html>

Load, Modify, and Export

word( "incoming.docx" )
    .replaceText( "[DATE]", dateTimeFormat( now(), "yyyy-mm-dd" ) )
    .replaceText( "[AUTHOR]", "Ortus Solutions" )
    .addParagraph( "Approved by Management", { bold: true, color: "008000" } )
    .save( "finalized.docx" );

---

💬 Support & Community

• 📧 Email: [email protected]
• 💬 Slack: Join BoxLang Community
• 🐛 Issues: GitHub Issues
• 📖 Forums: BoxLang Forums
• 📚 Docs: BoxLang Documentation

---

Built with ❤️ by Ortus Solutions

Professional Services Available — Need help with BoxLang implementation, training, or consulting? Contact Ortus Solutions