Documentation

Download and install

Download
unzip
install: copy it in your php server folder

Setting the mysql connection

Open the file "masterdata/_mysql.php and set the connection parameter to your mysql-server: server, username, password and database.

SQL for item example

Masterdata/sql contains the sql script to create the example table: k8components.

Getting started

php Example

Open the file 'masterdata_form.php' in your root path with an editor. The file looks like this:

<!DOCTYPE html>
<html lang="de">
<head>
    <meta charset="UTF-8">
    <title>Master data PHP Example</title>
	
	<link href="../../tabulator-master/dist/css/tabulator.min.css" rel="stylesheet">
	<script src="../../tabulator-master/dist/js/tabulator.min.js"></script>

<script src="../../jsonform-master/deps/jquery.min.js"></script>
	<script src="../../jsonform-master/deps/underscore.js"></script>
	<script src="../../jsonform-master/deps/opt/jsv.js"></script>
	<script src="../../jsonform-master/lib/jsonform.js"></script>
	
	
	<link href="../../jsonform-master/deps/opt/bootstrap.css" rel="stylesheet">

<link href="../css/meinestyles.css" rel="stylesheet">
    <script src="masterdata/js/masterdata.js"></script>
</head>
<body>
    <div class="container-fluid">
        <div class="container">
			<h1>Master data PHP Example</h1>
            <div id="masterdata1"></div>
        </div>
    </div>
    <script>
        var table="<?php echo getfromArray($_REQUEST,'table');?>";
        var datadefID="<?php echo getfromArray($_REQUEST,'table');>>";
        var url='masterdata/ProcessData.php?process_action=GetObject';
        if(table!=''){
            url+='&table='+table;
        }else if(datadefID!=''){
            url+='&datadefID='+datadefID;
        }else{
            url+='&datadefID=1';
        }
	    displayMasterData('#masterdata1',url);
    </script>
	
    <noscript>
        When you have no javascript, master data can not be executed!
    </noscript>
</body>
</html>

In the head and body the links to tabbulator, jsonform, bootstrap and masterdata are set.

The Master data form is displayed in the HTML element '#masterdata1'.

The function displayMasterData(selector,url) in the script loads the datadefintion with the "datadefID=1". "ProcessData.php" manages all requests and gives back the json datastructure of the datadefinition. After getting the datadefinition the following function is called:

$('#masterdata1').masterdata(datadefintion)

and the master data form is displayed in '#masterdata1'.

The datadefinition[1] is my test definition. The data is stored in the session and is running without mysql. For all other definitions, you have to connect to your mysql server.

The datadefinition[2] is the items definition. The data is stored in the database. On this definition we will have a look for the changes and improvements.

ProcessData.php

ProcessData.php gets all url-request from Javascript for the record handling and the datadefinitions. Its includes the data access class and the _prep_definition.php. Here the definition is created on the fly.

Getting the basic datadefinition of your table

Requirement: primary key of the table

the Primary key has to consist of an single field
- type: int
- autoincrement

The primary key is a hidden field in the master data form. It can not be changed!

Here on my datadefinition page you can input the datadefID or the table. The important parts of the datadefinition is displayed.

In your installation you can start the "get_datadefinition.php" in your Browser. Add the tablename in your url like this:

localhost/get_datadefinition.php?table=k8components

Copy your datadefinition in masterdata/datadefintions.php. Choose an ID like [3]. Modify it until you are satisfied with the appearance of the master data form. You will get an example of the changes for the table 'k8components' in the chapter. Details for the configuration of the listing are on the tabulator page. Details for the form are explained in jsonform.

Improving the datadefinition: k8compponents

{
    "name": "Item master data",
    "table": "k8components",
    "key": "componentID",
    "objectclass": "data_accessclass",
    "requiredfile": "class_data_accessclass.php",
    "tabulator": {
        "columns": [
            {
                "title": "Item no",
                "field": "componentnumber",
                "headerFilter": true,
				"width": 100
            },
            {
                "title": "Text 1",
                "field": "text1",
                "headerFilter": true
            },
            {
                "title": "Sales unit",
                "field": "salesunit",
                "headerFilter": true,
                "width": 60
            },
            {
                "field": "price",
                "title": "Price",
                "align": "right",
                "width": "80",
                "headerFilter": true,
                "formatter": "money",
                "formatterParams": {
                    "decimal": ".",
                    "thousand": ",",
                    "precision": 2
                }
            }
        ]
    },
    "jsonform": {
        "schema": {
            "componentID": {
                "type": "hidden"
            },
            "componentnumber": {
                "type": "string",
                "title": "Item no",
                "maxLength": 20,
                "pattern": "[0-9]{6}",
                "required": true
            },
            "text1": {
                "type": "string",
                "title": "Text 1",
                "maxLength": 50,
                "required": true
            },
            "text2": {
                "type": "string",
                "title": "Text 2",
                "maxLength": 50
            },
            "textdimensions": {
                "type": "string",
                "title": "Dimensions"
            },
            "category": {
                "type": "string",
                "title": "Category",
                "maxLength": 20,
                "enum": [
                    "tickets",
                    "accessories",
                    "others"
                ]
            },
            "baseunit": {
                "type": "string",
                "title": "Base unit",
                "maxLength": 10,
                "enum": [
                    "pc",
                    "kg",
                    "m"
                ]
            },
            "salesunit": {
                "type": "string",
                "title": "Sales unit",
                "enum": [
                    "pc",
                    "kg",
                    "m"
                ]
            },
            "vatclass": {
                "type": "number",
                "title": "Vat class",
                "enum": [
                    7,
                    10,
                    19
                ]
            },
            "conversionfactorsales": {
                "type": "number",
                "title": "Conversion factor",
                "default": 1
            },
            "price": {
                "type": "number",
                "title": "Price",
                "step": "0.01"
            }
        },
        "form": [
            {
                "type": "section",
                "id": "sec_main",
                "htmlClass": "row",
                "items": [
                    {
                        "type": "section",
                        "id": "sec_left",
                        "htmlClass": "col-sm-6",
                        "items": [
                            "componentID",
                            "componentnumber",
                            "text1",
                            "text2",
                            {
                                "key": "textdimensions",
                                "fieldHtmlClass": "form-control",
                                "type": "textarea"
                            }
                        ]
                    },
                    {
                        "type": "section",
                        "id": "sec_right",
                        "htmlClass": "col-sm-6",
                        "items": [
                            "category",
                            "baseunit",
                            "salesunit",
                            "conversionfactorsales",
                            "vatclass",
                            "price"
                        ]
                    }
                ]
            }
        ]
    }
}

changes in the datadefinition with green background

The following changes are made:

general changes
- the titles are changed, they are not marked!
Tabulator
- the width is changed in the columns: componentnumber and salesunit
- all column with exception of: componentnumber, text1 and salesunit are deleted
- the column price is added, the formatter money allows to specify the "precision" (decimals)
jsonform
- componentnumber: a pattern is added and it's an required field
- text1: it's an required field
- category, baseunit, salesunit and vatclass get an enum-array (enumeration)
- price get the step property for the formatting of 2 decimals
- form: this part was appended because the fields are displayed in 2 blocks. The textdimensions becomes a textarea.

Regard the locales

the relevant locale settings are:

decimal point
thousands separator
date format

The locale settings for html5 input fields depend on the web browser installation. The listing of tabulator configuration for decimal point and for the date need to be programmed by the php locale functions. Therefore the following placehloders are intended:

GLOBALS_decimal_point
GLOBALS_thousands_sep
GLOBALS_tabulatordateformat

Set the placeholders into the formatterParams of tabulator:

"formatterParams":{
"decimal":"GLOBALS_decimal_point",
"thousand":"GLOBALS_thousands_sep",
"precision":2
}

jsonform

vertical / horizontal form

the formtype and the formclass are changend in 'jsonform_conf' (both need to be defined):

0, form-inline
1, form-vertical
2, form-horizontal, default-setting in masterdata.js

by using horizontal form the following properties have to be set:

labelHtmlClass=label-control col-sm-3
- add "label-left", if wished
fieldWrapClass=col-sm-9

form with 2 or more columns

If you like to have 2 blocks, you have to use the "type":"section" or "fieldset" in the "form"-area, example with "section":

form definition with 2 blocks

CSS, Changing the appearance

Choose the right CSS file for the area which you like to change:

masterdata for headline and footline
tabulator for the listing
jsonform, bootstrap for the form

Take the file names please out of our code example at the top!

The following elements are styled in masterdata.css:

the headline at the top of the form
the selected row in the listing
the handle between listing and form
jsonform, the bottom-margin of the input fields
the footline at the bottom of the form

Datadefinitions

$datadefinitions[3]=json_decode(
{
	"name":"Stammdatenbeispiel",
	"table":"mytable",
	"key":"ID",
	"objectclass":"data_session",
	"requiredfile":"class_data_session.php",
	"masterdata":{
		"url_GetRecords":"Processdata.php?datadefID=1&action=GetRecords",
		"url_Load":"Processdata.php?datadefID=1&action=Load",
		...,
		}
	},
	"columns":[
		{
			"fieldname": "ID",
			"label":"",
			...
		},
		{
			"fieldname": "Name",
			"label":"Name",
			...
		},
		...
	],
	"tabulator":{
		"columns":[
			{"title":"Name", "field":"name", "width":150},
			{"title":"Age", "field":"age", "align":"left"},
			{"title":"Favourite Color", "field":"col"},
			{"title":"Date Of Birth", "field":"dob", "sorter":"date", "align":"center"}
		]
	},
	"jsonform":{
		"schema": {
			"name": {
				"type": "string",
				"title": "Name",
				"required": true
			},
			"age": {
				"type": "number",
				"title": "Age"
			},
			"col": {
				"type": "string",
				"title": "Favourite Color"
			},
			"dob": {
				"type": "string",
				"title": "Date of Birth"
			}
		}
	}
},true);

Example of a datadefinition

Attention Json, please regard to enclose your collection keys in quotes. So you can easily check your json datastructure in jsonlint!

Signification of the properties:

name: displayed in the form headline
table: if columns is not defined, the table structure is read and stored in the columns array
key: Primary key field of the thable
objectclass: name of the data access class
requiredfile: php file of the objectclass
masterdata: url for the data access
columns: array of the table fields. The "column" part of the definition is important for the data access class. Only this fields are saved to the database
tabulator: definition for the recordset list in the header
please change the listing here!
jsonform: definition for the fields in the form
please change the form here!
jsonform_conf: configuration of vertical and horizontal form

tabulator, used properties:

ajaxFiltering":true
"height":205
"layout"=>"fitColumns", to spread the columns along the whole list width
columns
- name
- title
- headerfilter (true ,false)
- headerSort (default:true, false)
- width (in px)
- align (left|center|right)
- formatter: money, date
- formatterparams, http://tabulator.info/docs/4.4/format#format-builtin)
- date (http://tabulator.info/docs/4.1/format)

jsonform, used schema properties:

name
title
type (string, number, integer, boolean, array, object)
step ("0.01" allows 2 decimal places)
required
maxLength
enum (for select,['value1','value2'])
readOnly
default