Documentation
Getting Started
Build beautiful and customizable HTML tables without writing a single line of code.
Compatibility
TableBuilder has been tested in and confirmed to work in the following browsers:
- Chrome
- Firefox
- Safari
- Internet Explorer 9/10/11
- Opera
**TableBuilder will work in IE 8 as long as you include respond.js on your site and put all the CSS inside the < head > tags above the respond.js script. For more information, please see their documentation.
Compilling Data
The TableBuilder plugin currently can handle data from a Google Spreadsheet (the preferred source), CSV file or an already existing HTML table (javascript only).
Building a table with TableBuilder is easy with the TableBuilder generator tool. However, if you know how to use a jQuery plugin, you can add the options yourself.
If you are using a Google Spreadsheet, you will need to "Publish to the web". If you are using a CSV file, make sure the data is formatted properly. If you are using an already existing table, simply leave the 'src' option blank. Please see input data for more information on each data source.
Building a table with TableBuilder is easy with the TableBuilder generator tool. However, if you know how to use a jQuery plugin, you can add the options yourself.
If you are using a Google Spreadsheet, you will need to "Publish to the web". If you are using a CSV file, make sure the data is formatted properly. If you are using an already existing table, simply leave the 'src' option blank. Please see input data for more information on each data source.
Start Building
Once you have your data, head over to http://robkandel.github.io/tablebuilder/ to create a beautiful HTML table with just a few clicks.
First click on "Insert Data" or "Start now, it's free" button and choose the appropriate data source. Then create your table and adjust any options or styles to best incorporate the table into your website.
Once you have changed all the options and styles, click the "Save" button and download your project, or get the embed code for the quickest way to get your table into your website.
First click on "Insert Data" or "Start now, it's free" button and choose the appropriate data source. Then create your table and adjust any options or styles to best incorporate the table into your website.
Once you have changed all the options and styles, click the "Save" button and download your project, or get the embed code for the quickest way to get your table into your website.
Next Step: Input Data
Input Data
Set up your data to use in the TableBuilder plugin or the generator tool
Google Spreadsheet
Using Google Spreadsheets is the preferred data source for your table. This is because it is easiest to update the data without having to update your TableBuilder project. We highly recommend using Google Spreadsheets as your data source!
To get started, first create a new spreadsheet. Input your data, and remember, you can always import your data from a Microsoft Excel file.
Once your data is ready, you will need to "Publish to the web". TableBuilder will ONLY work if you have clicked "Publish to the web" on your Google Spreadsheet. To do this, first click "File" and then find the "Publish to the web" option and click.
Now, on the box that just popuped up, click the blue "Publish" button. Find the URL that is highlighted
This is the URL you should paste into the field in the "Google Spreadsheet" table labeled "Paste your published Google Spreadsheet URL here". Then click on the blue "Create Table" button to the right.
To get started, first create a new spreadsheet. Input your data, and remember, you can always import your data from a Microsoft Excel file.
Once your data is ready, you will need to "Publish to the web". TableBuilder will ONLY work if you have clicked "Publish to the web" on your Google Spreadsheet. To do this, first click "File" and then find the "Publish to the web" option and click.
CSV File
If you do not have, or want to use, Google Spreadsheets, you have another option. A CSV File is a "Comma Separated Values" file which is one of the "Save As" options in Microsoft Excel. Complile your data in Excel and then go to "File" and "Save As". Change the file type to "Comma Separated Values (.csv)". For more information, see Micrsoft's documentation.
Once you have your CSV file, click the "CSV File" tab on the "Input Data" page. Then either drag and drop your file inside the dotted box or click where it says "Choose your file" to manually select your CSV file.
The dotted box will be replaced with your data. If you need to make any changes, you can edit the data inside the box or click the button that says "Use a different file" and start over. Once you are ready, click on the blue "Create Table" button under your data.
Once you have your CSV file, click the "CSV File" tab on the "Input Data" page. Then either drag and drop your file inside the dotted box or click where it says "Choose your file" to manually select your CSV file.
The dotted box will be replaced with your data. If you need to make any changes, you can edit the data inside the box or click the button that says "Use a different file" and start over. Once you are ready, click on the blue "Create Table" button under your data.
Existing Table
If you have an existing HTML table in the DOM, you can add the functionality of TableBuilder. Unfortunately, you can only do this through javascript, you can't use the generator tool.
To use an existing table, leave the "src" blank and call the TableBuilder plugin on the id of your table.
To use an existing table, leave the "src" blank and call the TableBuilder plugin on the id of your table.
Example:
<script type="text/javascript">
jQuery(document).ready(function() {jQuery('#table').table_builder();});
</script>
| Name | Age |
|---|---|
| John | 5 |
| Jane | 3 |
| Joe | 12 |
| Jackie | 14 |
<script type="text/javascript">
jQuery(document).ready(function() {jQuery('#table').table_builder();});
</script>
Next Step: Saving Your Table
Saving Your Table
You can either download the entire project to share with others or just get the embed code to quickly insert a table into your website.
Download
After clicking the "Save" option, choose the download button and your entire project will be available for download. Included in the download are all the necessary files to view and share the table as well as return to update the table.
To open the table, find the download and unzip the folder. Then open the "TableBuilder.html" file in any supported browser (such as Chrome, Firefox, etc). Included in the project file are all the CSS/JS files if you would like to try to improve or furthur customize TableBuilder. Please remember this project is an open source project licensed licensed under an MIT License.
Make sure to keep the "TableBuilder_config.json" file to update your table in the future. For more information on updating your table, see updating your table.
TableBuilder/
├── css/
│ ├── table_builder.0.0.5.css
│ ├── table_builder.min.0.0.5.css
│ └── images/
│ └── table_builder_preloader.gif
│
├── js/
│ ├── jquery-1.11.2.min.js
│ ├── jquery.table_builder.0.0.5.js
│ ├── jquery.table_builder.min.0.0.5.js
│ └── respond.js
│
├── TableBuilder_config.json
├── TableBuilder.html
├── LICENSE
└── README.mdTo open the table, find the download and unzip the folder. Then open the "TableBuilder.html" file in any supported browser (such as Chrome, Firefox, etc). Included in the project file are all the CSS/JS files if you would like to try to improve or furthur customize TableBuilder. Please remember this project is an open source project licensed licensed under an MIT License.
Make sure to keep the "TableBuilder_config.json" file to update your table in the future. For more information on updating your table, see updating your table.
Embed Code
If you don't want to save your project or quickly want to add TableBuilder to your website, use the "Embed Code" in the "Save" option. This will show a popup box with three options.
The first option, "Embed Code", provides everything you need to embed your table into any website. Simply copy and paste the enter text block into your website where you would like to display your table.
The second option, "JavaScript", provides just the JavaScript source code for the TableBuilder plugin. This is helpful if you are updating an existing project.
The third option, "Custom Styles", provides just the custom CSS that has been modified in your project. This is helpful if you are updating an existing project.
If you are unsure how to embed your table, copy everything from the "Embed Code" tab and paste it to your website where you want to display your table.
TableBuilder requires jQuery to work and is not included in the embed code, because most websites have jQuery already on the page. If you embed your project and nothing is happening, you might not have jQuery on your site. If you think this is the case, add the following line to the rest of your embed code.
The first option, "Embed Code", provides everything you need to embed your table into any website. Simply copy and paste the enter text block into your website where you would like to display your table.
The second option, "JavaScript", provides just the JavaScript source code for the TableBuilder plugin. This is helpful if you are updating an existing project.
The third option, "Custom Styles", provides just the custom CSS that has been modified in your project. This is helpful if you are updating an existing project.
If you are unsure how to embed your table, copy everything from the "Embed Code" tab and paste it to your website where you want to display your table.
TableBuilder requires jQuery to work and is not included in the embed code, because most websites have jQuery already on the page. If you embed your project and nothing is happening, you might not have jQuery on your site. If you think this is the case, add the following line to the rest of your embed code.
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js">
Next Step: Updating Your Table
Updating your table
When you download your project, make sure to keep the file named "TableBuilder_config.json", this file can be used to update any option or style from an existing project or it can be used to create a template with new data.
Update an Existing Project
When you download your project, you will receive a file named "TableBuilder_config.json", this file stores your data, all your settings as well as the custom styles you added to your table. If you want to update an option or style on your table, simply go to the data input page and choose the "Update existing table" tab. Then drag and drop the "TableBuilder_config.json" file where directed. All your settings and styles will be loaded in when you click the "Create Table" button.
Create a Template
You can also create a template for TableBuilder if you create a style for your website or have options that you want to repeat. All you need to do is create a table with the styles and/or options you want to repeat. Then download the project and keep the "TableBuilder_config.json" file. Each time you want to create a new table with this template, simply go to the data input page and choose the "Update existing table" tab. Then drag and drop the "TableBuilder_config.json" file where directed.
Now you can change the data source by adding your new Google Spreadsheet or clicking the "Use a different file" button under the "CSV File" tab and then drag and drop and new CSV file where directed. The options and styles will be applied to the new data source. You can always change or modify any option in addition to the ones from the template.
Now you can change the data source by adding your new Google Spreadsheet or clicking the "Use a different file" button under the "CSV File" tab and then drag and drop and new CSV file where directed. The options and styles will be applied to the new data source. You can always change or modify any option in addition to the ones from the template.
Next Step: Development Overview
TableBuilder Options
List of all the options, with description and developer information, that can be used in TableBuilder JS
blank_data
Characters to display if column data is blank (absent). To display nothing, change the option to ''.
**If the row is blank and the column is sorted, the row will always be sorted last regardless of how the blank data is displayed
Type : string
Default : '-'
bold_sort
Add a CSS class to the column that is currently sorted that will bold the cell in the column
Type : boolean
Default : true
column_classes
Add a class to specific columns in both the table header and each row. The object should be formatted with the index of the appropriate column as the key and the class name as the value.
Example:
column_classes: {
1: 'warning',
3: 'complete'
}
column_classes: {
1: 'warning',
3: 'complete'
}
Type : object
Default : {}
column_width
Change the width of the each column to optimize the display. Use percents to adjust each column's width. If not set, the table will make each column equal size. To hide a column, set the width to 0
Example:
column_width: [10, 20, 30, 40]
column_width: [10, 20, 30, 40]
Type : array
Default : []
date_format
Format date to specific format
Type : string
Default : 'MMMM DD, YYYY'
decimals
Number of decimal places a number can display, will round if number of decimals is larger
Type : number
Default : 2
fixed_header
Keep the header at the top of the browser when scrolling. If your website has a fixed item at the top of the page, you will need to adjust the CSS of the header to be below the height of the fixed item
Type : boolean
Default : true
format_column
Format the numbers of only certain columns. This will only be applied if the format_number option is set to false
Example:
format_column: [0,3,4]
format_column: [0,3,4]
Type : array
Default : []
format_number
Format all numbers in the table to show a comma every three decimal places
Type : boolean
Default : true
random_id
Helper function used to create scope to allow multiple tables on same page
Type : string
Default : null
ranking
Add a incremental numerical column. If the table has a default sort column, the numbers will be set based on the sort on initial display of the table. If no column is set to sort, the numbers will be set based on the order of the rows in the data
Type : boolean
Default : false
refresh_data
Number of minutes to refresh data from Google Spreadsheet. To stop the refresh counter, change the option to -1
Type : number
Default : 0
repeat_header
Repeat header every X amount of rows regardless of pagination. The repeated header can be clickable to sort the table if the sortable option is set to true
Type : number
Default : false
responsive_table
Make the table responsive to optimize display for mobile layouts. If your website is not a responsive site, change the option to false so the table will not adjust if the screen size changes
Type : boolean
Default : true
row_classes
Add a class to specific rows based on the index of the source data. The class will stay with the row regardless of how it is sorted. The object should be formatted with the index of the appropriate row as the key and the class name as the value.
Example:
row_classes: {
1: 'warning',
3: 'complete'
}
row_classes: {
1: 'warning',
3: 'complete'
}
Type : object
Default : {}
search_button_text
Change the text of the search button
Type : string
Default : 'Search'
search_input_text
Change the text of the search input field
Type : string
Default : 'Search table'
show_row_options
Show drop down option to change the number of visible rows. If the total number of rows is less than the lowest value in the visible_row_options setting, then the drop down will be hidden regardless
Type : boolean
Default : true
show_search
Allow users to search for values in the table
Type : boolean
Default : true
sort_column
Index of the column to sort when the table is initialized
Type : number
Default : null
sort_order
Order the table sorts a column the first time it is sorts each column. Either 'asc' or 'desc' (either A -> Z or Z -> A)
Type : string
Default : 'desc'
sort_types
Used as a helper to specifically declare the data type of each column to help sort and format data. Certain browsers can interpret data incorrectly based on the format, so this will setting will overwrite this error.
Example:
sort_types: ['', '', 'date', 'number', 'time', '', '']
sort_types: ['', '', 'date', 'number', 'time', '', '']
Type : array
Default : []
sortable
If columns are clickable for the user to resort the table
Type : boolean
Default : true
src
The data source, for more information, please see the section describing how toinput data
Type : string, object or HTML table
Default : null
table_class
Add a custom CSS class to the table
Type : string
Default : null
table_copyblock
Add a text block above the table
Type : string
Default : null
table_credit
Add a credit below the table. Value will be proceeded by 'PRODUCED BY:'
Type : string
Default : null
table_source
Add a source below the table. Value will be proceeded by 'SOURCE:'
Type : string
Default : null
table_source_link
Add a URL (link) to the table_source option to wrap the entire string in the link
Type : string
Default : null
table_title
Add a title above the table
Type : string
Default : null
time_format
Change the time format to a specific format
Type : string
Default : 'hh:mm A'
visible_row_options
The drop down options for users to change the number of visible rows. Can be any integer, with 1000000 displayed as "All Rows". If the total number of rows is less than the lowest value in the this setting, then the drop down will be hidden regardless
Type : array
Default : [10, 25, 50, 100, 1000000]
visible_rows
Number of rows visible when the table is initialized
Type : number
Default : 25
zero_out
Formats all numbers to display the number of decimal places set in the decimals option. This will add decimal places if not in the original data
Type : boolean
Default : false
Next Step: TableBuilder Events
TableBuilder Events
Events allow you to interact with your table through javascript
Events
Example:
jQuery('#table').table_builder('next');
jQuery('#table').table_builder('next');
add_row_data
Add a row of data to the table
Parameters : data (array), index (number)
add_table_rows
Add multiple rows to the table
Parameters : data (array), pagination offset (number), number of rows (number)
clear_search
Clears the search filter and displays all rows
clear_table_rows
Clears all the table rows and pagination
destroy
Destroys the table and all data associated with it. If the source is an HTML table, will restore original HTML table
next
Paginates the table to the next page based on the total rows available and the number of visible rows
paginate
Paginates the table to a specific page based on the total rows available and the number of visible rows
Parameters : total rows (number), current page (number)
prev
Paginates the table to the previous page based on the total rows available and the number of visible rows
refresh_data
Refreshes data, used only if data source is a Google Spreadsheet
Parameters : minutes (number)
search
Search the table to values that contain a specific term
Parameters : term (string)
sort
Sort the table by the column index and direction
Parameters : column index (number), direction ('asc' or 'desc'), type (optional if need to specify data type of column)
update
Update the TableBuilder settings
Parameters : settings (object with key name of setting name)
visible_rows
Change the number of visible rows on the table
Parameters : number of rows (number)
TableBuilder Callbacks
Callbacks allows you to listen to events to know when actions are completed.
Callbacks
Example:
jQuery('#table').on('build_complete.dataviz.table_builder', function(e) {
//tableBuilder has finished building your table, add your code here
});
jQuery('#table').on('build_complete.dataviz.table_builder', function(e) {
//tableBuilder has finished building your table, add your code here
});
initialize
When the table is first initialized
failed
If the table fails to initialize
building_table
The table is starting to build DOM elements
parse_data_complete
All data has been parsed from source
build_complete
All DOM elements have been successfully built
add_table_rows
Rows are being added to the table
row_added
The row that has just been added to the table
sort_complete
Sort has finished
rows_cleared
All the rows have been cleared
visible_rows_changed
Number of rows has changed
pagination_complete
Pagination has completed
search
User has searched the table
clear_search
The search has been cleared and restoring original data
data_refresh
Data has refreshed
destroy_table
Table has been destroyed
error
There was an error trying to access TableBuilder Events
Change Log
Version 0.0.5
Stable version completely rewritten to allow for callback and events
- Add Events
- Add Callbacks
- Allows for multiple tables on page
- Improves search
- Improves pagination
- Multiple style changes
- Add destory
Contributing
This project is hosted by Rob Kandel on Github. It is an open source project, so if you have a way to improve TableBuilder, please fork the project and help make it better!
Contact
Found a bug?
If you find a bug or need help with anything related to TableBuilder, please report it on Github.