Creating Tables

Creating Tables Overview

Aspose.Words provides several different methods to create new tables in a document. This article presents the full details of how to insert formatted tables using each technique as well as a comparison of each technique at the end of the article. A newly created table is given similar defaults as used in Microsoft Word:

Table PropertyDefault in Aspose.Words
Border StyleSingle
Border Width1/2 pt
Border ColorBlack
Left and Right Padding5.4 pts
AutoFit ModeAutoFit to Window
Allow AutoFitTrue

Inserting a Table using DocumentBuilder

In Aspose.Words a table is normally inserted using DocumentBuilder. The following methods are used to build a table. Other methods will also be used to insert content into the table cells.

OperationDescriptionTable State
DocumentBuilder.StartTableStarts building a new table at the current cursor position.The table is created empty and has no rows or cells yet.todo:image_alt_text
DocumentBuilder.InsertCellInserts a new row and cell into the table.todo:image_alt_text
DocumentBuilder.WritelnWrites some text into the current cell.todo:image_alt_text
DocumentBuilder.InsertCellAppends a new cell at the end of the current row.todo:image_alt_text
DocumentBuilder.WritelnWrites some text into the current cell (now the second cell).todo:image_alt_text
DocumentBuilder.EndRowInstructs the builder to end the current row and to begin a new row with the next call to DocumentBuilder.InsertCell .todo:image_alt_text
DocumentBuilder.InsertCellCreates a new row and inserts a new cell.todo:image_alt_text
DocumentBuilder.WritelnInserts some text into the first cell of the second row.todo:image_alt_text
DocumentBuilder.EndTableCalled to finish off building the table. The builder cursor will now point outside the table ready to insert content after the table.todo:image_alt_text
Below example shows how to create a simple table using DocumentBuilder with default formatting.

The result of the above code is a table inserted into the document which contains four cells and some text.


Below example shows how to create a formatted table using DocumentBuilder.

The result is a table which is formatted with some cell shading and different cell alignment.


Below example shows how to insert a nested table using DocumentBuilder.

This will produce a table within another table. This is often referred to as a nested table.


Inserting a Table Directly into the Document Object Model

Additionally, you can insert tables directly into the DOM at a particular node position. The same table defaults are used when using a DocumentBuilder to create a table. To build a new table from scratch without the use of DocumentBuilder, first, create a new Table node using the appropriate constructor, then add it to the document tree.

Note that you must take into account that the table will initially be completely empty (i.e contains no child rows yet). In order to build the table, you will first need to add the appropriate child nodes.

Below example shows how to insert a table using the constructors of nodes.

Inserting a Clone of an Existing Table

Often there are times when you have an existing table in a document and would like to add a copy of this table then apply some modifications. The easiest way to duplicate a table while retaining all formatting is to clone the table node using the Table.deepClone(boolean) method. Below example shows how to make a clone of a table in the document and insert it after the original table.

Below example shows how to remove all content from the cells of a cloned table.


for (Cell cell : (Iterable<Cell>) tableClone.getChildNodes(NodeType.CELL, true))

The same technique can be used to add copies of an existing row to a table.

Below example shows how to make a clone of the last row of a table and append it to the table.

Inserting a Table from HTML

Aspose.Words supports inserting content into a document from an HTML source by using the DocumentBuilder.insertHtml(java.lang.String) method. The input can be a full HTML page or just a partial snippet. Using this method we can insert tables into our document by using table elements e.g <table>, <tr>, <td>. Below example shows how to insert a table in a document from a string containing HTML tags.

Comparison of Insertion Techniques

As described in previous articles, Aspose.Words provides several methods for inserting new tables into a document. Each has its advantages and disadvantages, so often the choice of which to use depends on your situation. The table below can give you an idea of each technique.

DocumentBuilder (DocumentBuilder.startTable())Standard method of inserting tables and other document content.Sometimes hard to create many varieties of tables at the same time with the same instance of the builder.
Table (Table)Fits in better with surrounding code that creates and inserts nodes directly into the DOM without the use of DocumentBuilder.The table is created “blank”. Before most operations are performed Table.ensureMinimum() must be called to create any missing child nodes.
Cloning (Table.deepClone(boolean))Can create a copy of an existing table while retaining all formatting on rows and cells.The appropriate child nodes must be removed before the table is ready for use.
From an HTML source. (DocumentBuilder.insertHtml(java.lang.String))Can create a new table from HTML source e.g the <table>, <tr>, <td> tagsNot all possible formatting on a Microsoft Word table can be applied in HTML.