|
| 1 | +## excel-clj |
| 2 | + |
| 3 | +Purpose: declarative creation of Excel spreadsheets / PDFs with Clojure from |
| 4 | +higher level abstractions (tree, table) or via a manual grid specification, with |
| 5 | +boilerplate-free common sense styling. |
| 6 | + |
| 7 | +All of the namespaces have an `example` function at the end; they're intended to |
| 8 | +be browsable and easy to interact with to glean information beyond what's here |
| 9 | +in a the readme. |
| 10 | + |
| 11 | +Start by skimming this and then browsing [core.clj](src/excel_clj/core.clj). |
| 12 | + |
| 13 | +### Tables |
| 14 | +Though Excel is much more than a program for designing tabular layouts, a table |
| 15 | +is a common abstraction that we impose on our data. |
| 16 | + |
| 17 | +```clojure |
| 18 | +(require '[excel-clj.core :as excel]) |
| 19 | +=> nil |
| 20 | +(def table-data |
| 21 | + [{"Date" "2018-01-01" "% Return" 0.05M "USD" 1500.5005M} |
| 22 | + {"Date" "2018-02-01" "% Return" 0.04M "USD" 1300.20M} |
| 23 | + {"Date" "2018-03-01" "% Return" 0.07M "USD" 2100.66666666M}]) |
| 24 | +=> #'user/table-data |
| 25 | +(let [;; A workbook is any [key value] seq of [sheet-name, sheet-grid]. |
| 26 | + ;; Convert the table to a grid with the table function. |
| 27 | + workbook {"My Generated Sheet" (excel/table table-data)}] |
| 28 | + (excel/quick-open workbook)) |
| 29 | +``` |
| 30 | + |
| 31 | + |
| 32 | + |
| 33 | + |
| 34 | +### Trees |
| 35 | + |
| 36 | +Sometimes -- frequently for accounting documents -- we use spreadsheets to sum |
| 37 | +categories of numbers which are themselves broken down into subcategories. |
| 38 | + |
| 39 | +For example, a balance sheet shows a company's assets & liabilities by summing |
| 40 | +the balances corresponding to an account hierarchy. |
| 41 | + |
| 42 | +```clojure |
| 43 | +(def balance-sheet |
| 44 | + ["Mock Balance Sheet" |
| 45 | + [["Assets" |
| 46 | + [["Current Assets" |
| 47 | + [["Cash" {2018 100M, 2017 85M}] |
| 48 | + ["Accounts Receivable" {2018 5M, 2017 45M}]]] |
| 49 | + ["Investments" {2018 100M, 2017 10M}] |
| 50 | + ["Other" {2018 12M, 2017 8M}]]] |
| 51 | + ["Liabilities & Stockholders' Equity" |
| 52 | + [["Liabilities" |
| 53 | + [["Current Liabilities" |
| 54 | + [["Notes payable" {2018 5M, 2017 8M}] |
| 55 | + ["Accounts payable" {2018 10M, 2017 10M}]]] |
| 56 | + ["Long-term liabilities" {2018 100M, 2017 50M}]]] |
| 57 | + ["Equity" |
| 58 | + [["Common Stock" {2018 102M, 2017 80M}]]]]]]]) |
| 59 | + |
| 60 | +=> #'user/balance-sheet |
| 61 | +(excel/quick-open {"Balance Sheet" (excel/tree balance-sheet)}) |
| 62 | +``` |
| 63 | + |
| 64 | + |
| 65 | + |
| 66 | + |
| 67 | +### PDF Generation |
| 68 | + |
| 69 | +If you're on a system that uses an OpenOffice implementation of Excel, PDF |
| 70 | +generation is similarly simple. |
| 71 | + |
| 72 | +```clojure |
| 73 | +(excel/quick-open-pdf |
| 74 | + {"Mock Balance Sheet" (excel/tree balance-sheet) |
| 75 | + "Some Table Data" (excel/table table-data)}) |
| 76 | +``` |
| 77 | + |
| 78 | + |
| 79 | + |
| 80 | + |
| 81 | +### Table Styling |
| 82 | + |
| 83 | +The `table` function provides hooks to add custom styling without touching |
| 84 | +the generated grid, within the context of the table abstraction. |
| 85 | + |
| 86 | +(More on the syntax of the style data in _Manual Styling_.) |
| 87 | + |
| 88 | +- The `:data-style` keyword arg is a fn `(row-map, column-name) => style map` |
| 89 | +- The `:header-style` keyword arg is a fn `(column name) => style map` |
| 90 | + |
| 91 | +For instance, to highlight rows in our table where percent return is less than |
| 92 | +5%: |
| 93 | + |
| 94 | +```clojure |
| 95 | +(letfn [(highlight-below-5% [row-data col-name] |
| 96 | + (when (< (row-data "% Return") 0.05M) |
| 97 | + {:fill-pattern :solid-foreground |
| 98 | + :fill-foreground-color :yellow}))] |
| 99 | + (excel/quick-open |
| 100 | + {"My Generated Sheet" (excel/table table-data :data-style highlight-below-5%)})) |
| 101 | +``` |
| 102 | + |
| 103 | + |
| 104 | + |
| 105 | +### Tree Styling |
| 106 | + |
| 107 | +The tree function provides similar hooks to style the tree elements based on |
| 108 | +their nested depth. Both keyword arguments expect a fn |
| 109 | +`(integer-depth) => style map` where the integer depth increases with nesting. |
| 110 | + |
| 111 | +- `:total-formatters` is a function that controls styling for tree rows that |
| 112 | + display totals of multiple subcategories |
| 113 | +- `:formatters` is a function that controls styling for the rest of the tree |
| 114 | + |
| 115 | +### Manual Styling |
| 116 | + |
| 117 | +The code in this library wraps [Apache POI](https://poi.apache.org/). For |
| 118 | +styling, the relevant POI object is [CellStyle](https://poi.apache.org/apidocs/dev/org/apache/poi/ss/usermodel/CellStyle.html). |
| 119 | + |
| 120 | +In order to insulate code from Java objects, style specification is done via maps, |
| 121 | +for instance the style we saw above to highlight a row was: |
| 122 | +```clojure |
| 123 | +{:fill-pattern :solid-foreground, :fill-foreground-color :yellow} |
| 124 | +``` |
| 125 | + |
| 126 | +Under the hood however, all of the key/value pairs in the style maps correspond |
| 127 | +directly to setters within the POI objects. So if you browse the CellStyle |
| 128 | +documentation, you'll see `CellStyle::setFillPattern` and |
| 129 | +`CellStyle::setFillForegroundColor` methods. |
| 130 | + |
| 131 | +The map attributes are camel cased to find the appropriate setters, and the |
| 132 | +corresponding values are run through the multimethod |
| 133 | +[excel-clj.style/coerce-to-obj](src/excel_clj/style.clj) which dispatches on the |
| 134 | +attribute name and returns some value that's appropriate to hand to POI. |
| 135 | + |
| 136 | +If you're interested in greater detail, see the namespace documentation for |
| 137 | +[style.clj](src/excel_clj/style.clj), otherwise it's sufficient to know that enums are keyword-ized and |
| 138 | +colors are either given as keywords (`:yellow`) or as RGB three-tuples |
| 139 | +(`[255 255 255]`). |
| 140 | + |
| 141 | +### Grid Format & Cell Merging |
| 142 | + |
| 143 | +The functions `table` and `tree` convert the source data into the grid format |
| 144 | +which can go directly into the workbook map. The grid is `[[cell]]`, where each |
| 145 | +`[cell]` represents a row. |
| 146 | + |
| 147 | +The cell data are either plain values (String, Date, Number, etc.) or a map |
| 148 | +that includes optional style data / cell merging instructions. |
| 149 | + |
| 150 | +```clojure |
| 151 | +(let [title-style {:font {:bold true :font-height-in-points 10} :alignment :center}] |
| 152 | + (excel/quick-open |
| 153 | + {"Some Grid" |
| 154 | + [ [{:value "This is a Title" :width 5 :style title-style}] ;; Title row |
| 155 | + ["This" "Is" "A" "Row"] ;; Another row |
| 156 | + ]})) |
| 157 | +``` |
| 158 | + |
| 159 | + |
0 commit comments