docs.md

Quantum.utils

Quantum Utils is a module that contains many useful functions.

Quantum.utils.log

Show a log on the Browser's Javascript Console, styled based on the given level. Levels are debug, info, warn, error. If the first parameter is not a valid level, then a simple unstyled log is shown.

Example:

var myfunc = function (a, b, c) {
	Quantum.utils.log('debug', 'myfunc', a, b, c);
};

Quantum.utils.error

Show a log on the browser's JavaScript console with detailed infos on the given error.

Example 1:

try {
	// some code
} catch (e) {
	Quantum.utils.error(e, 'Oh no! An error!');
}

Example 2:

window.onerror = function (message, filename, lineno, colno, error) {
	if (error) {
		error.fileName = error.fileName || filename || null;
		error.lineNumber = error.lineNumber || lineno || null;
		error.columnNumber = error.columnNumber || colno || null;
	} else {
		error = {
			message: message,
			fileName: filename,
			lineNumber: lineno,
			columnNumber: colno
		};
	}
	Quantum.utils.error(error, 'Uncatched Exception');
};

Quantum.utils.guid

Returns a random GUID, useful for identify objects and elements.

Example:

console.log(Quantum.utils.guid()); // i.e. "1db1fef5-5e88-46d7-8a71-5a5c9d7ae880"

Quantum.utils.require

Load and execute CSS and JavaScript files. Files are loaded and executed in the given order, unless you use async or defer options. You can assign a function to be executed after every single script is loaded or when all scripts are loaded.

Example:

Quantum.utils.require({
	scripts: [
		{
			type: 'css',
			path: 'path/to/file.css',
			onload: function () {
				console.info('Script 1 loaded.');
			}
		},
		{
			type: 'css',
			path: 'path/to/file.css',
			onload: function () {
				console.info('Script 2 loaded.');
			}
		},
		{
			type: 'js',
			path: 'path/to/file.js',
			async: false,
			defer: false,
			onload: function () {
				console.info('Script 3 loaded.');
			}
		},
		{
			type: 'js',
			path: 'path/to/file.js',
			async: false,
			defer: false,
			onload: function () {
				console.info('Script 4 loaded.');
			}
		}
	],
	onload: function () {
		console.info('Every script has been loaded.');
	}
});

Quantum.validate

Quantum Validate is a module that contains many validation functions.

Quantum.validate.integer

Returns true if the given value is an integer number, false otherwise.

Example:

console.log(Quantum.validate.integer(1970)); // true
console.log(Quantum.validate.integer(-1970)); // true
console.log(Quantum.validate.integer(1970.5)); // false
console.log(Quantum.validate.integer(-1970.5)); // false
console.log(Quantum.validate.integer('1970')); // true
console.log(Quantum.validate.integer('-1970')); // true
console.log(Quantum.validate.integer('1970.5')); // false
console.log(Quantum.validate.integer('-1970.5')); // false
console.log(Quantum.validate.integer('hello')); // false

Quantum.validate.float

Returns true if the given value is a floating point number, false otherwise.

Example:

console.log(Quantum.validate.float(1970)); // true
console.log(Quantum.validate.float(-1970)); // true
console.log(Quantum.validate.float(1970.5)); // true
console.log(Quantum.validate.float(-1970.5)); // true
console.log(Quantum.validate.float('1970')); // true
console.log(Quantum.validate.float('-1970')); // true
console.log(Quantum.validate.float('1970.5')); // true
console.log(Quantum.validate.float('-1970.5')); // true
console.log(Quantum.validate.float('hello')); // false

Quantum.validate.hex

Returns true if the given value is an hexadecimal value, false otherwise. Validates i.e. 12ADff, #12ADff, 0x12ADff

Example:

console.log(Quantum.validate.hex('12ADff')); // true
console.log(Quantum.validate.hex('#12ADff')); // true
console.log(Quantum.validate.hex(0x12ADff)); // true
console.log(Quantum.validate.hex('0x12ADff')); // true

Quantum.validate.email

Returns true if the given value is a valid email address, false otherwise.

Example:

console.log(Quantum.validate.email('john.doe@gmail.com')); // true

Quantum.validate.ipv4

Returns true if the given value is a valid IPv4 address, false otherwise.

Example:

console.log(Quantum.validate.ipv4('192.168.0.1')); // true

Quantum.validate.ipv6

Returns true if the given value is a valid IPv6 address, false otherwise.

Example:

console.log(Quantum.validate.ipv6('2001:0db8:85a3:0000:0000:8a2e:0370:7334')); // true

Quantum.table

Quantum Table is a module that let you create standard HTML5 tables with ease.

Quantum.table

Create and render a table, and returns an object that let you update it later. The first parameter can be either a CSS3 selector (i.e. '#my-table') that resolves to a <table> element, or directly an HTMLTableElement element. The second parameter is an object that contains all the settings of the table. You can find documentation about settings on the Table Settings section.

Examples:

// selector resolves to a <table> element, given that an element like <table id="my-table"></table> exists.
const qt = Quantum.table('#my-table', { ... });

// selector is an HTMLTableElement element, given that an element like <table id="my-table"></table> exists.
const qt = Quantum.table(document.getElementById('my-table'), { ... });

// selector is an HTMLTableElement element created on the fly, rendered on memory and then later added to the DOM.
const table = document.createElement('table');
const qt = Quantum.table(table, { ... });
document.body.appendChild(table);

Table Settings

Key	Values	Description
width	<number> or <string>	Optional. The table width. It can be number of px, or string with specific unit (i.e. '100%', '5rem', etc.)
height	<number> or <string>	Optional. The table height. It can be number of px, or string with specific unit (i.e. '100%', '5rem', etc.)
caption	<string>	Optional. Text caption of the table. If not given, no caption is created.
records	<array>	Mandatory. Array of objects containing the data that will be rendered on the table.
columns	<array>	Mandatory. Array of objects containing the columns settings of the table. More documentation about columns settings on the Columns Settings section.
group	<object>	Optional. If available, will activate data grouping. Data will be grouped by the field key, sorted with the sort given function and you can give a custom render for the group header with the render function.
sort	<array>	Optional. If available, will activate data sorting. If also grouping is activate, the data are sorted inside each separate group. Each sorting has a field key and a direction (asc, desc, or sorting function).
onRowClick	<function>	Optional. Function executed each time the user clicks on a row of the table. Parameters of the function are record that is the corresponding record and tr that is the corresponding HTMLTableRowElement element.
onRenderCompleted	<function>	Optional. Function executed when redering of the table is completed.

Columns Settings

Key	Values	Description
field	<string>	Mandatory. The corresponding field in each record object.
caption	<string>	Optional. The column caption that will be showed on the table header. If no caption is given for every column, no table header is shown.
size	<number> or <string>	Optional. The column width. It can be number of px, or string with specific unit (i.e. '100%', '5rem', etc.)
hidden	true or false	Optional. Default false. Whenever the column is shown or hidden.
style	<string>	Optional. CSS style string applyed on each cell of the column.
render	<function>	Optional. Custom function to render each cell of the column. The given function will have the parameters value that is the corresponding value that should be rendered, record that is the full corresponding record and td that is the corresponding HTMLTableCellElement element.

Table Example

const qt = Quantum.table('#my-table', {
	width: 400, // same as '400px'
	height: 200, // same as '200px'
	caption: 'Teams',
	records: [
		{ id: 1, team: 'Red', firstname: 'Mario', lastname: 'Rossi' },
		{ id: 2, team: 'Blue', firstname: 'Marco', lastname: 'Bianchi' },
		{ id: 3, team: 'Red', firstname: 'Giuseppe', lastname: 'Verdi' },
		{ id: 4, team: 'Blue', firstname: 'Daniele', lastname: 'Veneroni' }
	],
	columns: [
		{
			field: 'id',
			caption: 'ID',
			size: '10%',
			hidden: true
		},
		{
			field: 'firstname',
			caption: 'First Name',
			size: '45%',
			hidden: false,
			render: function (value, record, td) { return '<em>' + value + '</em>'; }
		},
		{
			field: 'lastname',
			caption: 'Last Name',
			size: '45%',
			hidden: false
		}
	],
	group: {
		field: 'team',
		sort: 'asc', // 'asc', 'desc' or sorting function
		render: function (value) { return '<strong>' + value + '</strong>'; }
	},
	sort: [
		{ field: 'firstname', direction: 'asc' }, // sort by firstname first
		{ field: 'lastname', direction: 'desc' },  // and then by lastname
		{ field: 'id', direction: function (a, b) { return a < b ? -1 : 1; } } // finally sort by id using the given function
	],
	on_row_click: function (record, tr) {
		Quantum.utils.log('debug', 'Quantum.table', 'on_row_click', record, tr);
	},
	on_render_completed: function () {
		Quantum.utils.log('debug', 'Quantum.table', 'on_render_completed');
	}
});

update

The update method let you change or add some of the settings of the table and re-render the table. Just call the method passing an object with the new settings (you don't need to pass all the settings again, you just need to pass the changed or added settings) and the table will be re-rendered with the new settings updated.

Example:

const qt = Quantum.table('#my-table', {
	width: 400,
	// other settings here
});

qt.update({ width: 500 });

destroy

Destroy the table, that will leave the original table element empty.

Quantum.crypto

Quantum Crypto is a module that contains many crypto functions.

Quantum.crypto.random_buffer(bytes_number)

Return a Uint8Array of bytes_number length filled with random values. Useful to generate salts, random keys, etc. The maximum allowed as bytes_number is 65536.

Example:

console.log(Quantum.crypto.random_buffer(128));

Quantum.crypto.random_password(length, charset)

Returns a random password of the given length (default 16) with characters taken from the given charset (default Quantum.crypto.DEFAULTCHARSET).

Quantum.crypto.buffer_to_string(buffer)

Return a string representing the input buffer.

Quantum.crypto.string_to_buffer(string)

Return a Uint8Array buffer representing the input string.

Quantum.crypto.buffer_to_hex(buffer)

Return a hex string representing the input buffer.

Quantum.crypto.hex_to_buffer(string)

Return a Uint8Array buffer representing the input hex string.

Quantum.crypto.hash(algorithm, buffer)

Returns a promise with the hash digest of the given buffer. Supported algorithms: SHA-1, SHA-256, SHA-384, SHA-512

Example:

Quantum.crypto.hash('SHA-256', Quantum.crypto.string_to_buffer('foobar')).then(function (buffer_hash) {
    const hex_digest = Quantum.crypto.buffer_to_hex(buffer_hash);
});

Quantum.crypto.xorcipher(input, key)

Return a Uint8Array representing the input xor key. The xor is applied on each byte (8bit) of the input using the corresponding byte of the key (the key is circular).

const encrypted = Quantum.crypto.xorcipher(Quantum.crypto.string_to_buffer('My secret message'), Quantum.crypto.string_to_buffer('My secret key'));
const decrypted = Quantum.crypto.xorcipher(encrypted, Quantum.crypto.string_to_buffer('My secret key'));