Free-source, dinamic, table generator, built in pure JavaScript.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
src
.gitignore
LICENSE
README.md
TODO.md
gulpfile.js
logo-small.png
logo.png
package.json

README.md

MasterRow

A new way to show your data.

MasterRow is a open-source library that allows the easy creation and configuration of a dynamic table. Following the most common features in this kind of system, MasterRow offers:

  • Pagination;
  • Column filters;
  • Expansive row information ('click in row' to show more);
  • Row actions (ex: edit a register, exclude, see details, ...);
  • Column sorting;
  • Cell style personalization;
  • Export all table data to PDF or Excel.

Diferent of other interactive table tools, like DataTable, MasterRow has another approach in its setup. Instead asking to developer to create the table, MasterRow just need to receive your data. That's allow more freedom of choice the way you can receive and process the information.

Installation

MasterRow is available in the Node Package Manager. At first, you need to install NodeJs. Once installed, you can use the npm command to install MasterRow. Open the terminal, navegate to your project directory and type:

npm install masterrow --save-dev

In your HTML page, make these imports:

Optional Libraries

PDF Maker (Only if you're going to set Export into Masterrow)

  • <script src='dist/plugins/pdfmaker/pdfmake.js' />
  • <script src='dist/plugins/pdfmaker/vfs_fonts.js' />

Date Picker (Only if you're going to set a Date Picker or Date Period filters into Masterrow)

  • <script src='dist/plugins/datePicker/datepicker.js' />
  • <link rel="stylesheet" href="dist/datePicker/datepicker.css">

Any of these 2 libraries must be set BEFORE the Masterrow import, or the tool may not work.

In your page, create a link to one of these 2 group of files:

Compacted files (smaller):

  • <link rel="stylesheet" href="dist/masterrow.min.css">
  • <script src='dist/masterrow.min.js' />

Editable files (bigger):

  • <link rel="stylesheet" href="dist/masterrow.css">
  • <script src='dist/masterrow.js' />

Configuration

In the html page, create a component that will serve as a 'container' to the table. Set a ID to it.

<div class="container" id="tableId">

(Attention: The container cannot be a <table>. The library will create the table for your!) So, in a JavaScript file, create the MasterRow object, refering the id of the container.

var table = new MasterRow({
	containerId: 'tableId',
	{options}
});

You can set more than one table at once. Make sure each Masterrow have a different ID.

Options

Each of these configurations are optionals.

Filters

You setup here which columns can be filtered.

  • Simple: Filter by text value.
{
	// This filters will go into each column
	columnFilters: [
		{
			column: 'name' // The column name from your data
		},
	]
}
  • Autocomplete: Allow you to set a function to serve all options to the user. You can set an array of options or a response from an async source.
{
	columnFilters: [
		// ***** Example 1: Autocomplete fixed values *****
		{
			column: 'Type',
			autoComplete: function (fieldValue, callback){				
				return [
					'Star',
					'Planet',
					'Galaxy',
				]
			}
		},
		
		// ***** Example 2: Autocomplete will get the callback result *****
		{
			column: 'Destination',
			autoComplete: function (fieldValue, callback){				
				destinationSearchService(fieldValue).then( function(resultList){
					callback(resultList);
				})
			}
		},
	]
}
  • DatePicker: Create a button to open a calendar form. That will make easy to user choose a date.
{
	columnFilters: [
		{
			column: 'dateIni',
			datePicker: {
				dateformat: '%d/%m/%Y'; // (or null, if you won't set an format.
			}
		},
	]
}
  • datePeriod: The same of DatePicker, but will create 2 buttons, instead one.
{
	columnFilters: [
		{
			column: 'dateEnd',
			datePeriod: {
				dateformat: null
			}
		},
	]
}
  • select: Will set a select field, to able the user to choose one option. You must set the name (value to be shown in the field), the value (the real valor to be used in the program). You can set the selected item to be the default option.
{
	columnFilters: [
		{
			column: 'Country',
			select: [
				{name: 'Brasil', value: 'brazil}, // Default selected value: false
				{name: 'Japão', value: 'japan', selected: true},
				{name: 'EUA', value: 'usa', selected: false},
			]
		},
	]
}
  • checkList: Will set a list of checkbox, to able the user to choose one or more options. You must set the name (value to be shown in the field), the value (true/false, if the item is checked, and the real value of the system).
{
	columnFilters: [
		{
			column: 'City',
			checkList: [
				{name: 'São Paulo', value: true},
				{name: 'Kyoto', value: false},
				{name: 'New York', value: false},
			]
		},
	]
}

Pagination

It will create a list of links to take the use into some data division:

pagination: {
	registerPerPage: 5 // The amount of register the table will set per page
}

Detailing

It allows to show only some columns in the table. Also, if detailing is set, the table will show all columns from any row clicked by the user:

detailing: {
	columnsToShow: ['Country', 'ID', 'Name'] // Which columns must appear
}

Row Action

  • : You can set one or more links, insert to each row, in a new column, to execute a function. This function will receive the respective row where the user clicked
rowAction: {
	actionColumnName: "Options", 	// The name of the columns that will hold the action link
	actionList: [{
		icon: 'pencil-square-o', 	// The name of the icon, based in Font Awesome list (http://fontawesome.io/cheatsheet/ or http://fontawesome.io/icons/)
		toProcessAction: function (row){	// The function will receive the row of your data. You receive the data of row 4 if the user click in this link in the row 4, for example.
			console.log('The row content is', row);
		}
	},
	{
		icon: 'times',
		toProcessAction: function (row){
			console.log('I must delete something');
		}
	},
	]
}

Sorting

It will set controls to allow the orderning of data by the user

sorting: {
	enabled: true
}

Personalization

A few options to change the look of Masterrow table:

  • customCellStyle: You can set in a table cell, a CSS class style of your preference. Masterrow will set by the cell value.
personalization: {
	
	customCellStyle:[
		{
			when: function(value){
				if(value.search('Kem') >= 0)
					return true;
				return false;
			},
			setClass: 'customCell'
		}
	]
},
  • columnRename: Rename the name of some column:
personalization: {
	
	columnRename: [
		{
			column: 'ID',
			newColumnName: 'Id do registro'
		}, 
		{
			column: 'Name',
			newColumnName: 'Nome do parceiro'
		}, 
		{
			column: 'City',
			newColumnName: 'Cidade'
		}, 
		{
			column: 'Date Ini',
			newColumnName: 'Data Inicial'
		}, 
	],
},

Export

With the config set, Masterrow will create 3 buttons: Export all data to Excel or PDF formats, or print the Page. If there's any pagination, Export will run into ALL pages to export all data.

exporting: {
	fileName: "DefaultFileName"
},

Complete configuration example

Here goes an example of all options set:

var table = new MasterRow({
	containerId: 'tabela',
	filters: {
		columnFilters: [
			{
				column: 'Date Ini',
				datePeriod: {
					dateformat: null
				}
			},
			{
				column: 'Name',
				autoComplete: function (fieldValue, callback){				
				destinationSearchService(fieldValue).then( function(resultList){
					callback(resultList);
				})
			},
			{
				column: 'ID',
				select: [
					{
						name: 'Malckon', 
						value: 1
					},
					{
						name: 'jansen', 
						value: 2,
						selected: true
					},
					{
						name: 'Tibet', 
						value: 3
					}
				]				
			},
			{
				column: 'Country'
			}

		]
	},

	pagination: {
		registerPerPage: 5
	},
	sorting:{
		enabled: true
	},

	exporting: {
		fileName: "MasTerrOw"
	},

	detailing: {
		columnsToShow: ['ID','Name', 'Date Ini'],
		noDetail: false
	},
	personalization: {
		columnRename: [
			{
				column: 'ID',
				newColumnName: 'Id do registro'
			}, 
			{
				column: 'Name',
				newColumnName: 'Nome do parceiro'
			}, 
			{
				column: 'City',
				newColumnName: 'Cidade'
			}, 
			{
				column: 'Date Ini',
				newColumnName: 'Data Inicial'
			}, 
		],

		customCellStyle:[
			{
				when: function(value){
					if(value.search('Kem') >= 0)
						return true;
					return false;
				},
				setClass: 'customCell'
			}
		]
	},

	rowAction: {
		actionColumnName: "Ações",
		actionList: [{
			icon: 'pencil-square-o',
			toProcessAction: function (row){
				console.log('The person name is' + row['Name'] + '.');
			}
		},
		{
			icon: 'times',
			toProcessAction: function (row){
				console.log('I must delete the ' + row['Name'] + ' person.');
			}
		},
		]
	},

});

Processing

That's the main part of the library, where you set the data to send. MasterRow works with a function, that receives another function built by you. Developers may find this way of work stange, but be sure this feature turns MasterRow very flexible.

table.toProcessData ( function (processParameters){
// You define the process here
});

The parameter of this function is a object, with these attributes:

  • filters (Enabled if you've set this in the options):

    • Simple filter
      • columnName.column (Set by you): The column index, set in the options above;
      • columnName.value (Set by the MasterRow): The value the user has entered in each filter;
    • Date Picker Filter
      • columnName.datePicker.value (Set by the MasterRow): The value the user has entered in each filter;
    • Date Period Filter
      • columnName.datePeriod.value.from, columnName.datePeriod.value.to (Set by the MasterRow): The respective value from / to entered by the user;
    • checkList
      • columnName.checkList[youFieldIndex].value (Set by the MasterRow): The value of a field. Masterrow will bring back the array you've set in this config.
    • select
      • columnName.select[youFieldIndex].value (Set by the MasterRow): The same of the checkList. Example:
  • pagination (Enabled if you've set this in the options):

    • maxPages (Set by you): The max number of rows that MasterRow must show, per page;
    • currentPage (Set by the MasterRow): The current page in the pagination process;
  • sorting (Enabled if you've set this in the options):

    • sorting.columnName (Set by the MasterRow): By the sorting options the user can choose, it can return one of these values:
      • "Disabled sorting": The column are not sorted.
      • "Ascending sorting": User wants to sort this column Ascending.
      • "Descending sorting": User wants to sort this column Descending.
  • callback (Set by the MasterRow): It's one of endpoints of this function. Used in async process. It will be explained above.

Parameter example:

table.toProcessData ( function (processParameters){
	dataToGenerate = someArray;

	// Filter
	var filteredData =
	{
		data: {
			columns: ['ID', 'Name', 'E-Mail', 'City', 'Country'],
			rows: dataToGenerate.data.rows.filter( function (row){
				return (row[processParameters.filters['Name'].column - 1].search(processParameters.filters[0].value) >= 0) && (row[processParameters.filters[1].column - 1].search(processParameters.filters[1].value) >= 0);
			})
		}
	};

	
	filteredData =
	{
		data: {
			columns: ['ID', 'Name', 'E-Mail', 'City', 'Country'],
			rows: filteredData.data.rows.slice (processParameters.pagination.currentPage - 1, processParameters.pagination.currentPage + 4)
		}
	};

Returning the data to the MasterRow

To generate the table, you must return data in 2 ways:

  • Calling the callback function. (Async way);
  • Returning the data directly in this function (direct way).

In both ways, the data you're sent must come to this format:

var dataToReturn = {
	data: []; //the columns and rows that must be show
	metadata:  { // configuration object
		maxPages: 0 ;// the totalNumber of pages we must set. If user omits this field, the pagination link will not be show.
	}
}

It's up to you the choose the best way to return data. Generally, you use the callback way, when you have to extract data from a AJAX request, for example. So, you can send this return object like a parameter to this callback function:

table.toProcessData ( function (processParameters){
	processParameters.callback(dataToReturn);
});

The direct way is when MasterRow don't need to wait a data to process. The table will be generated immediatly:

table.toProcessData ( function (processParameters){
	return dataToReturn;
});

PS: If you've called 'toProcessData' function once, you can call it again, without paramether. MasterRow will recall the last set function, to generate the data into the table again. Ex:

table.toProcessData ();

So, you can set a text field, as a filter, and use the function to refresh the data.

The data format

It has been thougth in some data layouts that the developer could have in hands. So, the MasterRow system are supposed to receive one of these 3 formats:

  • Format 1:
data: [
	[
		{"column1": "value1"},
		{"column2": "value2"},
		{"column3": "value3"},
		(...)
		{"columnN": "valueN"},
	],
	[
		{"column1": "value1"},
		{"column2": "value2"},
		{"column3": "value3"},
		(...)
		{"columnN": "valueN"},
	],
	(...)
];
  • Format 2:
data: [
	{
		"column1": "value1",
		"column2": "value2",
		"column3": "value3",
		(...)
		"columnN": "valueN",
	},
	{
		"column1": "value1",
		"column2": "value2",
		"column3": "value3",
		(...)
		"columnN": "valueN",
	},
	(...)
];

-Format 3:

columns: ["column1", "column2", "column3", (...), "columnN"],
rows: [
	["value1", "value2", "value3", (...), "valueN"],
	["value1", "value2", "value3", (...), "valueN"],
	["value1", "value2", "value3", (...), "valueN"],
	(...)
]

Customizing

There's some ways you can customize the MasterRow:

  • Use the personalization config;
  • All style format of the table can be edited, if you use the masterrow.css file;
  • You can edit the source code in your machine or server, if you set the masterrow.js file;
  • The entire source code is in the src folder. If you want to code the project entirely, the better way is code with the task manager Gulp. Remember, the project is open-source. You can colaborate to this project, sending a request by GitHub.

Used libraries and plugins

Masterrow uses 3 libraries:

  • Font Awesome (Font Awesome by Dave Gandy ): Masterrow icon source. You don't need to install these fonts, or link to this website directly; that are built together with the source-code.

  • PDF Maker (PDF Maker by @devongovett ): PDF Maker library. Allow the table export to PDF and table print. You must import this library, if Exporting is enabled.

  • Date Picker (Date Picker bt Brian McAllister ): The calendar generator, to Date Picker and Period filters. You must import this library, if these fields are enabled.

License

The project is under a MIT License. It's free to use. You just need to set the attribuition to the author. For example:

MasterRow - Developed by Amós Batista - 2016.

More information about the license, read the MIT license here:.

Author and contact

My name is Amós Batista, I'm a front-end developer. I keep a website, where you can know more about me, and my work. (http://amosbatista.com/)

If you have any question, suggest, or something else to say, you can contact me by e-mail: (amos.silva@gmail.com)

There's also my twitter: (https://twitter.com/@amosbatista)

😔