MasterRow

*Warning: Documentation is out of date. Update of this page will occurr soon. *

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);

Diferent of other interactive table libraries, 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 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}
});

Options

Each of these configurations are optionals.

• filters: You setup here which columns can be filtered. The object follows this structure:

{
	// This filters will go into each column
	columnFilters: [
		{
			column: 3 // The column index from your data
		},
		{
			column: 2 // The column index from your data
		}
	]
}

• 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: [3, 4, 5] // Which columns must appear
}

• personalization: Changes in table apparence or behavior.

personalization: {
		columnRename: [ // Changing the column name
			{
				column: 1, // The column index
				newColumnName: 'ID' // The new name
			}, 
			{
				column: 4,
				newColumnName: 'Partner Name'
			}
		]
	},

• rowAction: 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');
		}
	},
	]
}

Here goes an example of all options set:

//Table creation
var table = new MasterRow({
	containerId: 'tabela',
	filters: {
		columnFilters: [
			{
				column: 3
			},
			{
				column: 2
			}

		]
	},

	pagination: {
		registerPerPage: 5
	},

	detailing: {
		columnsToShow: [3]
	},
	
	personalization: {
		columnRename: [
			{
				column: 1,
				newColumnName: 'Id do registro'
			}, 
			{
				column: 2,
				newColumnName: 'Nome do parceiro'
			}, 
			{
				column: 4,
				newColumnName: 'Cidade'
			}, 
		]
	},

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

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):
  • column (Set by the developer): The column index, set in the options above;
  • value (Set by the MasterRow): The value the user has entered in each filter;
• pagination (Enabled if you've set this in the options):
  • maxPages (Set by the developer): The max number of rows that MasterRow must show, per page;
  • currentPage (Set by the MasterRow): The current page in the pagination process;
• 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[0].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:

• 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 use icons from Font Awesome (Font Awesome by Dave Gandy ). You don't need to install these fonts, or link to this website directly; that are built together with the source-code.

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: ([email protected])

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

:pensive: