gooxml

We are pleased to announce gooxml, a dual licensed AGPLv3/commercial OOXML library written in go supporting:

  • Documents (docx) [Word]
    • Read/Write/Edit
    • Formatting
    • Images
    • Tables
  • Spreadsheets (xlsx) [Excel]
    • Read/Write/Edit
    • Cell formatting including conditional formatting
    • Cell validation (drop down combobox, rules, etc.)
    • Retrieve cell values as formatted by Excel (e.g. retrieve a date or number as displayed in Excel)
    • Formula Evaluation (100+ functions supported currently, more will be added as required)
    • Embedded Images
    • All chart types

gooxml

It’s goal is to be the most compatible and highest performance Go library for creation and editing of docx/xlsx/pptx files.

Origins

We needed to be able to create documents and spreadsheets and would like to do it from go. Afer investigation, we discovered that there are several go libraries that support creating XLSX files and a few others that support “template” DOCX creation via replacing tokens. There wasn’t, however, a full featured library that allowed creation of all of the OOXML document types covering the vast majority of the OOXML standard. So we built one.

The OOXML standard is very large and apparently open to interpretation1. gooxml provides an easy to use API for common use cases OOXML document construction while enabling falling back to raw OOXML document manipulation should the library’s API not cover a specific use case yet.

Installation

gooxml is go get’able and can be installed via:

go get baliance.com/gooxml/

Code is hosted and issues are tracked on GitHub.

Usage

The libraries have an API that should be familiar if you’re used to the OOXML formats, and still easy to learn if not. The library was written from scratch so it feels like a native Go lbrary.

It takes a different approach from existing Go OOXML libraries by using code generated from the ECMA-376 XSDs to create the XML based types, and wrapping them with a friendlier API.

The primary advantages are:

  • round-tripping of arbitrary docx/xlsx/pptx files without losing content
  • allowing users to bail out to the .X() method on every wrapped type to manipulate the raw OOXML should an API not exist for the functionality that they need.

As an example of the second, if setting a document background is ever requested, we would add a method so that the following worked:

dox := document.New()
dox.SetBackground(color.RGB(50,50,50))

Users are not stuck and can always continue making progress with the library as is by falling back to .X() which is a method on every type returning the wrapped native OOXML type.:

dox := document.New()
doc.X().Background = wml.NewCT_Background()
doc.X().Background.ColorAttr = &wml.ST_HexColor{}
doc.X().Background.ColorAttr.ST_HexColorRGB = color.RGB(50, 50, 50).AsRGBString

Document

Documents consist primarily of paragraphs and runs. A paragraph contains multiple runs, and a run can contain multiple sequences of text, line breaks, tabs, etc.

package main

import (
    "baliance.com/gooxml/document"
)

func main() {
    doc := document.New()
    para := doc.AddParagraph()
    run := para.AddRun()
    run.AddText("Hello World")
    doc.SaveToFile("hello.docx")
}

More complex examples can be found in _examples/document.

Spreadsheet

A workbook can consists of multiple sheets, each of which contains a series of rows with cells.

package main

import "baliance.com/gooxml/spreadsheet"

func main() {
    wb := spreadsheet.New()
    sheet := wb.AddSheet()
    sheet.Cell("A1").SetString("Hello World")
    wb.SaveToFile("hello.xlsx")
}

More complex examples can be found in _examples/spreadsheet.

Licensing

gooxml is dual licensed under the AGPL and a standard commercial license. Pricing information can be found, and licenses purchased at baliance.com/pricing/.


  1. So far, Word on OSX appears to be the most particular regarding what it will display. We’ve seen 100% validating documents that work in Windows Word, LibreOffice, Apple Pages and Google Docs fail to open in Mac Word. [return]