ConstructFlexTable-class: Construct Flex Table
In csmoxford/prettyTables: Pretty tables

Description Details Fields Methods Examples

A reference class used to prepare data and formatting to create a FlexTable object in the ReporteRs package. This class has a large number of modifier functions aimed at making tables quicker and easier than the functions provided for the FlexTable class.

This requires ReporteRs to be installed and ReporteRs requires a java JDK to be installed to work correcly.

This package will accept the data as a data.frame or matrix and convert all entries to text to avoid problems with interactions between factors, numerics and header rows. For this reason it is recommended that all post processing of numerics is completed before passing the data to the class.

Because this is a reference class, autocomplete in Rstudio will display all the available functions and parameters by typing 'objectName'$. All the functions start with a capital letter (with the exception of r's built in methods) and are named in a structured manner. The first word of the function name indicates its purpose. The following names are used:

Insert Insert additional rows, columns and header rows
Set Set parameter values for everything from spanning rows and columns to borders to text alignment
Cut Remove rows or columns
Get GetTable Calls a function to create the FlexTable

The copy command ('objectName'$copy()) may be used to clone the reference object. Reference classes by default refer to one version even if referenced from different variables so this method must be used if you want to duplicate and modify one version of the object only.

All stored values start with lowercase. The data is stored in data and can be modified like a regular matrix or data.frame. We recommend changing non data values using the Set functions. This is particularly important for rowSpan and colSpan to ensure FlexTable does not throw errors or mess up intended. The Set functions are pretty flexible right now but if you feel there is something missing please let us know.

data: The data to display
numRow: The number of rows in data
numCol: The number of columns in data
isHeaderRow: A logical vector of length numRow. Is used to set header rows in FlextTable instead of adding to body.
rowSpan: A numRow*numCol matrix denoting row spans. The number in the cell denotes the number of rows to span. Zero is entered when a cell is spanned and not visible. Note: can only by 1*m and not n*m
colSpan: A numRow*numCol matrix denoting column spans. The number in the cell denotes the number of columns to span. Zero is entered when a cell is spanned and not visible. Note: can only by n*1 and not n*m
color: A numRow*numCol matrix of hex colors. Used for background colour of cells.
borderWidthVertical: A (numRow+1)*(numCol+1) matrix of vertical border edge widths.
borderWidthHorizontal: A (numRow+1)*(numCol+1) matrix of horizontal border edge widths.
textAlign: A numRow*numCol matrix of text alignment. One of 'left', 'right', 'center', 'justify'.
fontStyle: A numRow*numCol matrix of font style. One of 'normal', 'italic', 'bold'. Only the first letter is currently used so shorthand is possible.
fontColor: A numRow*numCol matrix of font colour. These should be hex colors.
fontSize: A numRow*numCol matrix of font size (numeric).
padding: A numRow*numCol matrix for the cell padding.

CutColumns(index): Remove columns by index updating all the property parameters in the process
CutRows(index): Remove rows by index updating all the property parameters in the process
GetTable(...): A wrapper function that calls GetFlexTable. Can pass multiple ConstructFlexTable objects into this function. the object this is called on goes first.
initialize(data, header = NULL): Initialisation function. This is called by ConstructFlexTable(). Pass the data and optionally a header row to create a new object. Header can either be a vector or TRUE (which takes the column names for data. Note that for matching the header will count as a row. For this reason it may be easier to generate a header row seperately or add later
InsertColumn(afterIndex, values): Insert a column after a given index. Using an index of 0 inserts first.
InsertHeaderRow(afterIndex = 0, values): Inserts a header row. Makes this row bold by default
InsertRow(afterIndex, values): Insert a row or number of rows after a given index. Using an index of 0 inserts at the top.
SetBorderWidthHorizontal(width = 2): Set the Border width for horizontal borders globally
SetBorderWidthHorizontalByMatching(width = 2, matching = NULL): Set the border width of borders according to matching. Will place borders around consecutively identical values of matching
SetBorderWidthHorizontalByMatchingOnColumn(width = 2, j): A wrapper for SetBorderWidthHorizontalByMatching. Matches using data stored in the class with column j
SetBorderWidthHorizontalByRow(width = 2, index): Set the Border width for vertical borders globally. Note an index of zero is the left most border and an index of numCol+1 is the rightmost border
SetBorderWidthVertical(width = 2): Set the Border width for vertical borders globally
SetBorderWidthVerticalByColumn(width = 2, index): Set the Border width for vertical borders globally. Note an index of zero is the left most border and an index of numCol+1 is the rightmost border
SetBorderWidthVerticalByMatching(width = 2, matching = NULL): Set the border width of borders according to matching. Will place borders around consecutively identical values of matching
SetBorderWidthVerticalByMatchingOnRow(width = 2, i): A wrapper for SetBorderWidthVerticalByMatching. Matches using data stored in the class with column index
SetColorAll(color): Set the background color of all cells. Color should be a hex color.
SetColorColumnByIndex(color, index): Set the background color of a specific column. Color should be a hex color.
SetColorRowAlternatingByColumn(colors, j): Set the background color alternating colors by matching group of rows. Consecutive values in the row which are the same are considered a group. Colors should be a vector of hex colors.
SetColorRowAlternatingByMatching(colors, matching): Set the background color alternating colors by matching group of rows. A set of rows is colored together if matching is the same for consecutive rows. Colors should be a vector of hex colors.
SetColorRowAlternatingRow(colors): Set the background color alternating colors by row. Colors should be a vector of hex colors.
SetColorRowByIndex(color, index): Set the background color of a specific row. Color should be a hex color.
SetFontColorAll(color): Set the fontColor of all cells. color should be a hex color.
SetFontColorRowAlternating(colors): Set the fontColor alternating by colors. color should be a vector of hex colors.
SetFontColorRowAlternatingByMatching(colors, matching): Set the font color, alternating colors by matching group of rows. A set of rows is colored together if matching is the same for consecutive rows. colors should be a vector of hex colors.
SetFontSize(size): Set the fontsize of all cells. size is a numeric value
SetFontStyleByRow(style = "bold", index): Set the font style by row. Style should be one of 'normal', 'italic', 'bold'. Only the first letter is currently used so shorthand is possible.
SetHeaderRowAll(value = TRUE): Set all rows to header rows or not
SetHeaderRowByIndex(index, value = TRUE): Assign header rows by row index
SetPaddingAll(paddingWidth = 0): Set the padding of all cells. FlexTable itself can accept padding for each side of a cell but I have not provided this funcitonality in this class.
SetSpanColumnByMatching(i, matching): On row i sets colSpan based on matching. Consecutive values in matching which are the same are merged.
SetSpanColumnByRange(i, from, to): On row i sets colSpan between from and to.
SetSpanColumnByRow(j): On column j sets colSpan based on the data. Consecutive values in the row which are the same are merged.
SetSpanRowByColumn(j): On column j sets rowSpan based on the data. Consecutive values in the column which are the same are merged.
SetSpanRowByMatching(j, matching): On column j sets rowSpan based on matching. Consecutive values in matching which are the same are merged.
SetSpanRowByRange(j, from, to): On column j sets rowSpan between from and to.
SetStyleVanilla(adjustRowSpan = FALSE): This function assumes a single header row is present and mimics the vanilla.table function in ReporteRs
SetTextAlign(align = "left"): Set the text alignment of all cells. align should be one of 'left', 'right', 'center', 'justify'.
SetTextAlignColByIndex(align = "left", index): Set the text alignment of a specific column or columns. align should be one of 'left', 'right', 'center', 'justify'.
SetTextAlignRowByIndex(align = "left", index): Set the text alignment of a specific row or rows. align should be one of 'left', 'right', 'center', 'justify'.

## Not run: 
# Use some of the iris data set to create a table
iris2 = iris[c(1:10,51:60,101:110),]



# Create a new ConstructFlexTable object
bft = ConstructFlexTable(data = iris2[,c(5,1:4)])

# This is a reference class object so the methods which are called update the reference directly. As a consequence we don't need to set the values back to the object.

# Use the data in species column (1) to span rows with identical consecutive values
bft$SetSpanRowByColumn(j = 1)

# Use the data in species column (1) to set alternating colours
bft$SetColorRowAlternatingByColumn(colors = c("#FFFFFF","#CCCCCC"), j = 1)

# Use the data in species column (1) to set thicker horizontal border widths
bft$SetBorderWidthHorizontalByMatchingOnColumn(width = 2, 1)

# Set thicker vertical border widths
bft$SetBorderWidthVerticalByColumn(width = 2,index = c(0,1,3,5))

# Centre all text in the table
bft$SetTextAlign(align = "center")

bft$GetTable()

# we can remove some rows.
bft$CutRows(c(6:10))

bft$GetTable()
# We may then need to update the row span. Not in this case. It will depend on which rows are cut.

# Lets create some header rows
headft = ConstructFlexTable(data = matrix(c(
  "Species","Sepal","Sepal","Petal","Petal",
  "","Length","Width","Length","Width"
),byrow = TRUE, ncol = 5))

# Use the data in row 1 to span columns with identical consecutive values
headft$SetSpanColumnByRow(j = 1)

# span a number of rows using the range.
headft$SetSpanRowByRange(j = 1, from = 1, to = 2)

# Set horizontal borders
headft$SetBorderWidthHorizontalByRow(width= 2, index = c(0,2))

# Use the data in row 1 to set thicker vertical border widths
headft$SetBorderWidthVerticalByMatchingOnRow(width = 2,i = 1)

# Set a background color
headft$SetColorAll("#CCCCCC")

# Centre all text in the table
headft$SetTextAlign(align = "center")

# Make all text bold
headft$SetFontStyleByRow(style = "bold",index = c(1,2))

# with isHeaderRow defaulting to FALSE the row span for species works
# We can pass the body as a variable to GetTable
ft = headft$GetTable(bft)
ft
# Note we can pass as many ConstructFlexTable objects as we like to GetTable
# This is an alternative to
ft = GetFlexTable(headft, bft)

# we can then use addFlexTable (ReporteRs) to add to a .doxc or .pptx document.

# Note that we have not set header rows formally, as a consequence they will not repeat on page break in word.
# We can set them to be treated as header rows:
headft$SetHeaderRowByIndex(index = c(1,2))

# We do however lose any (vertical) row spans now because each row is processed using addHeaderRow (ReporteRs)
ft = headft$GetTable(bft)
ft
headft$GetTable()
# It might have been quicker here to use the InsertHeaderRow function on the original object prior to formatting.

## End(Not run)