A tutorial for service.flextabledit.jquery - Flexible Table Editor

Version: 1.0.0

March 17, 2016

Overview

This is a relatively small jquery plugin (12 kBytes minified) that allows users to create, edit and manage grid cells that are arranged in table columns and rows. It is particularly usefull in enviroments where the user must be given the possibility to completely define both the structure and the content of a table.

Any table served/presented by the plugin is assumed to have one or more columns, a header row to describe the meaning of each column, and one or more data rows holding cell data for each column.

[1] When the plugin must be constructed to render a table view for cell data that already exists on a server or in an app then the table data must be passed to the plugin by means of a simple two-dimensional array representing a matrix of rows and columns, like in:

<script type="text/javascript">

  // Create table to show existing content.
  var data = [
    ["Year", "Ford", "Volvo", "Toyota", "Honda"],
    ["2014", 10, 11, 12, 13],
    ["2015", 20, 11, 14, 13],
    ["2016", 30, 15, 12, 13]
  ];
  $('#table').flextabledit({
    content: data
  });

</script>

The header row is assumed to be represented by the 1st element in the array. In the example above the header row holds the column names "Year", "Ford", "Volvo", etc.

[2] In case a completely new table must be constructed (i.e. no data is available upfront but the user will subsequently bring in the data) then the plugin must still be given a two-dimensional array in order to lay down the initial structure of the new table; i.e. the number of columns and rows. The array must then have to be populated with empty column names and cell data strings, like in:

<script type="text/javascript">

  // Create table without content holding 1 column and 1 data row.
  var data = [
    ["", ""],
    ["", ""]
  ];
  $('#table').flextabledit({
    content: data
  });

</script>

[3] The plugin expects that the content datasource (holding real or empty data) contains at a minimum 1 header row, 1 data row, and 1 cell (column) within each row. All rows must also have the same number of cells.

Table editing features

The plugin supports the following features:

Editing of any table cell - The user can click or touch any column header cell or data cell and set/change its text value. Internally the plugin uses text input fields for cell data and so it accepts anything the user types in the cell.
Pressing Tab moves the focus to the next cell.

Insert columns and rows - To insert a new column/row the user must select an existing column/row, click or touch a command button that comes up when the column/row is selected, and choose Insert on the popup menu. A new column/row is inserted before the selected column/row.

Delete columns and rows - To delete column/row the user must select the column/row, click or touch the command button, and choose Remove on the popup menu.

Cut, Copy and Paste - The plugin supports cut, copy and paste on individual cells, on a whole row, and on a whole column. The commands are available when the user clicks or touches the command button that appears when a cell, row or column is selected.
When the cut/copy command is requested the selected source item will get a dotted border. In case of 'cut' the border will disappear automatically when paste is executed. In case of 'copy' you must press the Esc key.

Not supported

The following features are not supported:

The plugin is not offering Excel type of features like data validation, sorting, grouping, formula support, etc.
All values inserted in data cells essentially are just strings.

Size

The minified version of the plugin is about 12kB.

Demo

Click here for a demo.

Download

You can download the latest version of the plugin at GitHub.

Usage

To use the plugin start with adding the following in your header section:

<link rel="stylesheet" type="text/css" href="[your-path]/service.dialog.jquery.css" />
<link rel="stylesheet" type="text/css" href="[your-path]/service.flextabledit.jquery.css" />
<script src="[your-path]/service.flextabledit.jquery.min.js"></script>
<script src="[your-path]/service.dialog.jquery.min.js"></script>

Note: The plugin expects that the dialog plugin and associated .css file (explained here) are present. They are used for rendering both the small '...' popup button and the menu popup itself.

In your html, include an empty div to act as the container for hosting the table that will be generated by the plugin.

<div id="myTable></div>

Then, write some javascript to construct the plugin object and assign as 'content' datasource a javascript array to it.

<script type="text/javascript">

  var data = [
  ["", "Ford", "Volvo", "Toyota", "Honda"],
  ["2014", 10, 11, 12, 13],
  ["2015", 20, 11, 14, 13],
  ["2016", 30, 15, 12, 13]
  ];
  $('#myTable').flextabledit({
  content: data
  });

</script>

After construction the plugin will immediately render a html table element with a header row and as many rows and columns as given by the datasource. The user can immediately start editing the table.

Get table data from plugin

At some point in time the user has finished editing the table content and so you will want to obtain the data and probably save it somewhere on a server or a storage location in your app.
To retrieve the data invoke a 'getData' action on the plugin as follows:

<script type="text/javascript">
  ...
  // Get table content
  var contentArray = $('#myTable').flextabledit('getData');
  if (contentArray.length != 0) {
    var jsonContent = JSON.stringify(contentArray);
    // Save content
    ...
  }
  ...
</script>

The 'getData' action returns a javascript array containing all the table data. Its format is the same as the array you have to provide upon construction of the plugin.
To make it persistent you can convert the array to a string that represents the table content as a JSON array.

Styling

The plugin comes with a stylesheet that contains the style definitions for the rendered table and the command popup menu and button. When a cell, row or column is selected a medium tick border is presented around the selection and if you look into the stylesheet you will find an extensive set of styles to deal with this.

API

Initialization method

[jqObject(s)].flextabledit(options)

The options argument is a javascript associative array (an object with key/value pairs) that allows you to initialize the plugin with some properties.

Properties

content

Type: Array
Default: The array is mandatory.
This property defines the table content.

addTableClass

Type: String
Default: null
This property is optional. When provided the plugin assumes that one or more classnames are given which it will add to the class of the table element. You can use that for instance if you want to add your own styling, like: cell borders, striped rows, etc.

texts

Type: Object
Default: null
This option lets you modify the various command texts, e.g. when you want to have the texts in another language than English. The following is an example of the key/value object that is passed to have the texts in a language such as Dutch: { cut: 'Knippen', copy: 'Kopiëren', paste: 'Plakken', insert: 'Invoegen', remove: 'Verwijderen', columnName: 'Kolomnaam' }.

Other methods

getData

Signature: [jqObject(s)].flextabledit('getData');
You can retrieve the content of the table with this method. A javascript array is returned with the same format as the 'Content' array in the constructor.

destroy

Signature: [jqObject(s)].flextabledit('destroy');
This method can be used to destroy the plugin.