Create a Table
Aspose.Words allows users to create tables in a document from scratch and provides several different methods for doing so. This article presents details on how to add formatted tables to your document using each method, as well as a comparison of each method at the end of the article.
Default Table Styles
The newly created table is given default values similar to those used in Microsoft Word:
|Table Property||Default in Aspose.Words|
|Border Width||1/2 pt|
|Left and Right Padding||5.4 pts|
|AutoFit Mode||AutoFit to Window|
A table can be inline if it is tightly positioned, or floating if it can be positioned anywhere on the page. By default, Aspose.Words always creates inline tables.
Create a Table with DocumentBuilder
In Aspose.Words, users can create a table in a document using the DocumentBuilder. The basic algorithm for creating a table is as follows:
- Start the table with StartTable
- Add a cell to the table using InsertCell – this automatically starts a new row
- Optionally, use the CellFormat property to specify cell formatting
- Insert the cell content using the appropriate DocumentBuilder methods such as Writeln, InsertImage, and others
- Repeat steps 2-4 until the row is complete
- Call EndRow to end the current row
- Optionally, use the RowFormat property to specify row formatting
- Repeat steps 2-7 until the table is complete
- Call EndTable to finish building the table
- StartTable can also be called inside a cell, in which case it starts the creation of a nested table within the cell.
- After calling InsertCell, a new cell is created, and any content you add using other methods of the DocumentBuilder class will be added to the current cell. To create a new cell on the same row, call InsertCell again.
- If InsertCell is called immediately after EndRow and the end of a row, the table will continue on a new row.
- The EndTable method to end the table should only be called once after calling EndRow. Calling EndTable moves the cursor from the current cell to the position immediately after the table.
The process of creating a table can be clearly seen in the following picture:
The following code example shows how to create a simple table using DocumentBuilder with default formatting:
The following code example shows how to create a formatted table using DocumentBuilder:
The following code example shows how to insert a nested table using DocumentBuilder:
Create a Table via DOM (Document Object Model)
You can insert tables directly into the DOM by adding a new Table node at a specific position.
Please note that immediately after the table node creation, the table itself will be completely empty, that is it does not yet contain rows and cells. To insert rows and cells into a table, add the appropriate Row and Cell child nodes to the DOM.
The following code example shows how to build a new table from scratch by adding the appropriate child nodes to the document tree:
Create a Table from HTML
Aspose.Words supports inserting content into a document from an HTML source using the InsertHtml method. The input can be a full HTML page or just a partial snippet.
Using this InsertHtml method, users can insert tables into the document via table tags like
The following code example shows how to insert a table into a document from a string containing HTML tags:
Insert a Copy of an Existing Table
There are often times when you need to create a table based on an already existing table in a document. The easiest way to duplicate a table while retaining all formatting is to clone the Table node using the deepClone method.
The same technique can be used to add copies of an existing row or cell to a table.
The following code example shows how to duplicate a table using node constructors:
The following code example shows how to clone the last row of a table and append it to the table:
If you are looking at creating tables in a document that grow dynamically with each record from your data source, then the above method is not advised. Instead, the desired output is more easily achieved by using Mail merge with regions. You can learn more about this technique in the “Mail Merge with Regions” section.
Compare Ways to Create a Table
Aspose.Words provides several methods to create new tables in a document. Each method has its own advantages and disadvantages, so the choice of which to use often depends on the specific situation.
Let’s take a closer look at these ways of creating tables and compare their pros and cons:
|Via DocumentBuilder||The standard method for inserting tables and other document content||Sometimes difficult to create many varieties of tables at the same time with the same builder instance|
|Via DOM||Fits in better with surrounding code that creates and inserts nodes directly into the DOM without using a DocumentBuilder||The table is created “empty”: before performing most operations, you must call EnsureMinimum to create any missing child nodes|
|From HTML||Can create a new table from HTML source using tags like
||Not all possible Microsoft Word table formats can be applied to HTML|
|Cloning an existing table||You can create a copy of an existing table while retaining all row and cell formatting||The appropriate child nodes must be removed before the table is ready for use|