Skip to content

Commit 8c4681f

Browse files
jameskleehjameskleeh
committed
Documentation
1 parent 81573c5 commit 8c4681f

File tree

8 files changed

+256
-74
lines changed

8 files changed

+256
-74
lines changed

‎config/codenarc/rules.groovy‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ ruleset {
8686
IfStatementCouldBeTernary
8787
InvertedIfElse
8888
LongLiteralWithLowerCaseL
89-
'NoDef' enabled: false
89+
'NoDef' enabled: true
9090
//ParameterReassignment
9191
TernaryCouldBeElvis
9292
VectorIsObsolete
@@ -148,7 +148,7 @@ ruleset {
148148
ThrowThrowable
149149

150150
// rulesets/formatting.xml
151-
BlankLineBeforePackage
151+
//BlankLineBeforePackage
152152
BracesForClass
153153
BracesForForLoop
154154
BracesForIfElse

‎docs/columns.adoc‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
[[columns]]
2+
== Columns
3+
4+
If you wish to build your document by column instead of by row, you can do so with the `column` method.
5+
6+
=== Underlying API
7+
8+
There is no such thing as a column object in the Apache POI API, however you can get a reference to each cell which will allow you to access the row.
9+
10+
[source,groovy]
11+
----
12+
import org.apache.poi.xssf.usermodel.XSSFCell
13+
import org.apache.poi.xssf.usermodel.XSSFRow
14+
15+
ExcelBuilder.build {
16+
sheet {
17+
column {
18+
XSSFCell myCell = cell("A1")
19+
XSSFRow rowOne = myCell.row
20+
}
21+
}
22+
}
23+
----
24+
25+
=== Defaults
26+
27+
You can apply default styling at the column level in addition to the sheet level. Styles that conflict with defaults at the sheet level will override.
28+
29+
[source,groovy]
30+
----
31+
ExcelBuilder.build {
32+
sheet {
33+
defaultStyle [:]
34+
column {
35+
defaultStyle [:]
36+
}
37+
}
38+
}
39+
----
40+
41+
=== Skipping Cells
42+
43+
[source,groovy]
44+
----
45+
ExcelBuilder.build {
46+
sheet {
47+
column {
48+
cell("foo")
49+
skipCells(2)
50+
cell("bar")
51+
}
52+
}
53+
}
54+
----
55+
56+
The previous example will produce a document with "foo" in cell A1 and "bar" in A4.
57+
58+
==== Usage with a header row
59+
60+
You can create columns with a header row. The columns will start after rows previously created.
61+
62+
[source,groovy]
63+
----
64+
ExcelBuilder.build {
65+
sheet {
66+
columns {
67+
column("Foo", "foo")
68+
skipCells(1)
69+
column("Bar", "bar")
70+
}
71+
column {
72+
cell("A2")
73+
cell("A3")
74+
}
75+
}
76+
}
77+
----
78+
79+
The example above will put the text "A2" in cell A2.
80+
81+
=== Skipping Columns
82+
83+
It is very easy to skip any number of columns. See the following example:
84+
85+
[source,groovy]
86+
----
87+
ExcelBuilder.build {
88+
sheet {
89+
column {
90+
cell("A")
91+
cell("B")
92+
cell("C")
93+
}
94+
skipColumns(2)
95+
column {
96+
cell("A")
97+
cell("B")
98+
cell("C")
99+
}
100+
}
101+
}
102+
----
103+
104+
The above example will produce a sheet that looks something like this:
105+
106+
[width="50%"]
107+
|=======
108+
| |A |B |C |D
109+
110+
|*1* |A | | |A
111+
|*2* |B | | |B
112+
|*3* |C | | |C
113+
|=======

‎docs/formulas.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
[[formuals]]
1+
[[formulas]]
22
== Formulas
33

44
The Groovy Excel Builder supports formulas in excel documents by providing an easy way to create formulas with support for helper methods to get cell references.

‎docs/index.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,12 @@ include::sheets.adoc[]
99

1010
include::rows.adoc[]
1111

12+
include::columns.adoc[]
13+
1214
include::cells.adoc[]
1315

16+
include::links.adoc[]
17+
1418
include::formulas.adoc[]
1519

1620
include::styles.adoc[]

‎docs/links.adoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
[[links]]
2+
== Links
3+
4+
The `link` method allows you to create a cell that will contain a link. Links can link to files, cells, web addresses, or email addresses.
5+
6+
=== Creating Links
7+
8+
To create a link to a URL, simply create a link like the following example:
9+
10+
[source,groovy]
11+
----
12+
import org.apache.poi.xssf.usermodel.XSSFCell
13+
import org.apache.poi.common.usermodel.Hyperlink
14+
15+
ExcelBuilder.build {
16+
sheet {
17+
row {
18+
XSSFCell myCell = link("Google", "http://www.google.com", Hyperlink.LINK_URL)
19+
link("John Smith", "mailto:[email protected]", Hyperlink.LINK_EMAIL)
20+
link("Open File", "localFile.docx", Hyperlink.LINK_FILE)
21+
link("Go To Cell", "'Sheet Name'!A2", Hyperlink.LINK_DOCUMENT)
22+
}
23+
}
24+
}
25+
----
26+
27+
=== Document Links
28+
29+
There is an additional `link` method to assist you in creating links to cells in the current document. The method takes in a closure that has the same methods available when creating formulas. See the link:#formulas[section on formulas] for the full documentation.
30+
31+
[source,groovy]
32+
----
33+
ExcelBuilder.build {
34+
sheet {
35+
row {
36+
link("Go To Cell") {
37+
"'${sheetName}'!${exactCell(0,0}"
38+
}
39+
}
40+
}
41+
}
42+
----

‎docs/rows.adoc‎

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,79 @@ ExcelBuilder.build {
3636
}
3737
----
3838

39+
=== Header Row
40+
41+
It is possible to define a header row and assign an identifier to each cell for later use.
42+
43+
[source,groovy]
44+
----
45+
ExcelBuilder.build {
46+
sheet {
47+
columns {
48+
column("Foo", "foo")
49+
column("Bar", "bar")
50+
}
51+
}
52+
}
53+
----
54+
55+
In future rows, you can do things like skip to a given column or reference that column in a formula. The first argument is assigned to the cell value and the second argument is the unique identifier.
56+
57+
=== Creating Rows
58+
59+
You can easily create rows with the following syntax:
60+
61+
[source,groovy]
62+
----
63+
ExcelBuilder.build {
64+
sheet {
65+
//Empty row
66+
row {
67+
}
68+
69+
//Values in cells A2, B2, C2
70+
row(1,2,3)
71+
72+
//Empty row with height specified
73+
//Height can be a Short if you want to set the height in "twips"
74+
row([height: 10F] {
75+
}
76+
77+
//Empty row
78+
row()
79+
}
80+
}
81+
----
82+
83+
To reference everything you can do in a row, see the section in the documentation on link:#rows[Rows].
84+
85+
=== Skipping Rows
86+
87+
It is very easy to skip any number of rows. See the following example:
88+
89+
[source,groovy]
90+
----
91+
ExcelBuilder.build {
92+
sheet {
93+
row("A", "B", "C")
94+
skipRows(2)
95+
row("A", "B", "C")
96+
}
97+
}
98+
----
99+
100+
The above example will produce a sheet that looks something like this:
101+
102+
[width="50%"]
103+
|=======
104+
| |A |B |C
105+
106+
|*1* |A |B |C
107+
|*2* | | |
108+
|*3* | | |
109+
|*4* |A |B |C
110+
|=======
111+
39112
=== Skipping Cells
40113

41114
[source,groovy]
@@ -55,7 +128,6 @@ The previous example will produce a document with "foo" in cell A1 and "bar" in
55128

56129
==== Skipping to a column
57130

58-
59131
[source,groovy]
60132
----
61133
ExcelBuilder.build {

‎docs/sheets.adoc‎

Lines changed: 0 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -61,75 +61,5 @@ ExcelBuilder.build {
6161
}
6262
----
6363

64-
=== Header Row
6564

66-
It is possible to define a header row and assign an identifier to each cell for later use.
6765

68-
[source,groovy]
69-
----
70-
ExcelBuilder.build {
71-
sheet {
72-
columns {
73-
column("Foo", "foo")
74-
column("Bar", "bar")
75-
}
76-
}
77-
}
78-
----
79-
80-
In future rows, you can do things like skip to a given column or reference that column in a formula. The first argument is assigned to the cell value and the second argument is the unique identifier.
81-
82-
=== Creating Rows
83-
84-
You can easily create rows with the following syntax:
85-
86-
[source,groovy]
87-
----
88-
ExcelBuilder.build {
89-
sheet {
90-
//Empty row
91-
row {
92-
}
93-
94-
//Values in cells A2, B2, C2
95-
row(1,2,3)
96-
97-
//Empty row with height specified
98-
//Height can be a Short if you want to set the height in "twips"
99-
row([height: 10F] {
100-
}
101-
102-
//Empty row
103-
row()
104-
}
105-
}
106-
----
107-
108-
To reference everything you can do in a row, see the section in the documentation on link:#rows[Rows].
109-
110-
=== Skipping Rows
111-
112-
It is very easy to skip any number of rows. See the following example:
113-
114-
[source,groovy]
115-
----
116-
ExcelBuilder.build {
117-
sheet {
118-
row("A", "B", "C")
119-
skipRows(2)
120-
row("A", "B", "C")
121-
}
122-
}
123-
----
124-
125-
The above example will produce a sheet that looks something like this:
126-
127-
[width="50%"]
128-
|=======
129-
| |A |B |C
130-
131-
|*1* |A |B |C
132-
|*2* | | |
133-
|*3* | | |
134-
|*4* |A |B |C
135-
|=======

‎src/main/groovy/com/jameskleeh/excel/Sheet.groovy‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,14 @@ class Sheet {
6666
rowIdx += num
6767
}
6868

69+
/**
70+
* Skips columns
71+
* @param num The number of columns to skip
72+
*/
73+
void skipColumns(int num) {
74+
columnIdx += num
75+
}
76+
6977
/**
7078
* Used to define headers for a sheet
7179
*
@@ -97,6 +105,19 @@ class Sheet {
97105
columnIdx++
98106
}
99107

108+
/**
109+
* Skip to a previously defined column created by {@link #column}
110+
*
111+
* @param id The column identifier
112+
*/
113+
void skipTo(Object id) {
114+
if (columnIndexes && columnIndexes.containsKey(id)) {
115+
columnIdx = columnIndexes[id]
116+
} else {
117+
throw new IllegalArgumentException("Column index not specified for $id")
118+
}
119+
}
120+
100121
/**
101122
* Creates a row
102123
*

0 commit comments

Comments
 (0)