Wiki source code of Quellen

Hide last authors

version	line-number	content
1.1	1	{{content/}}
	2
	3	{{id name="fig_data_source"/}}
23.1	4	{{figure image="data_source_en.png"}}Configuration screen for creating data sources: (1) list of existing data sources, (2) area for editing the selected data source, (3) settings panel of the data source, (4) servlet URL for accessing the data source.{{/figure}}
1.1	5
23.1	6	The sources or rather data sources are lodged as text in the format CSV, JSON or XML and can be worked up through the {{designer/}}/the form.
	7	To have an access to data sources in the script area via javascript too, all data sources are converted into a JSON structure and customized in the object {{code language="none"}}XFC_METADATA.urls.datasource_[csv\|json\|xml]{{/code}}. The structure of this JSON structure for the different data sources is expounded in the respective section.
1.1	8
	9	{{info}}
23.1	10	Servlet URL
	11	The servlet URL of a data source will be displayed on the configuration screen (see point 4 in [[figure>>\|\|anchor="fig_data_source"]]) and is provided in the JS object {{code language="none"}}XFC_METADATA.urls.datasource_[csv\|json\|xml]{{/code}}.
1.1	12	{{/info}}
	13
23.1	14	== Creating a data source ==
1.1	15
23.1	16	Open the module "Data > Sources" and click the button "New" {{ficon name="plus-circle-outline"/}} in the header of the list (see point 1 in [[figure>>\|\|anchor="fig_data_source"]]). After that you will be prompted to either create an empty data source or import one from a file. Three types of data sources can be created: //XML//, //CSV// und //JSON//.
1.1	17
23.1	18	{{lightbox image="data_source_new_en.png" title="Data sources can be imported or created from scratch."/}}
1.1	19
23.1	20	Every data source needs:
1.1	21
23.1	22	* a unique name (in the settings panel: see point 3 in [[figure>>\|\|anchor="fig_data_source"]])
	23	* the actual data in the editing area (see point 2 in [[figure>>\|\|anchor="fig_data_source"]])
1.1	24
23.1	25	=== Import of data sources from files ===
1.1	26
23.1	27	The following Data types can be used to import data sources:
1.1	28
	29	* XML: //.xml//
	30	* CSV: //.csv//, //.xls//, //.xlsx// (Excel)
	31	* JSON: //.json//
	32
	33	{{id name="data_source_import_csv"/}}
23.1	34	__CSV data sources__
1.1	35
23.1	36	CSV data sources can be imported from different file types:
1.1	37
	38	* //.csv//
23.1	39	Opens up a dialog for configuring the import:
	40	Delimiter**: Determines which symbol is used in the file for separating data fields/ colunms (typically: comma).
	41	Text qualifier**: Determines the text qualifier. This symbol is used to support special characters inside data fields (e.g. comma in numbers with decimal places).
	42	Start at line**: Determines where to start importing the data source from.
	43	Ignore empty lines**: When activated ignores empty lines during import.
1.1	44
23.1	45	{{lightbox image="data_source_import_csv_en.png" title="Import dialog for CSV files"/}}
1.1	46
	47	* //.xls//, //.xlsx//
23.1	48	Opens up a dialog for configuring the import:
	49	Sheets to import**: Determines which worksheets/tables should be imported from the file.
1.1	50
23.1	51	{{lightbox image="data_source_import_excel_en.png" title="Importdialog für Excel-Dateien"/}}
1.1	52
	53	__Drag&Drop__
	54
23.1	55	Data sources can be imported by Drag&Drop as well. If a file is being dropped over the list (green area) than a new data source of the corresponding type will be created (for Excel files: one data source per worksheet will be created). If a file is being dropped over an existing data source than it will be updated. Changes will only take effect after the "Save" {{icon name="save"/}} button is clicked.
1.1	56
	57	== CSV ==
	58
	59	{{figure image="data_source_csv_servlet_json_comparison.png"}}
23.1	60	The JSON structure of a CSV data source. This JSON structure can be accessed through JavaScript via {{code language="none"}}XFC_METADATA.urls.datasource_csv{{/code}}. (1) On the left there is the JSON structure of the data source with out using the first row as a header. Instead the headers are of the form: {{code language="none"}}colX{{/code}}. (2) On the right there is the data source where the first row is being used as the header.
1.1	61	{{/figure}}
	62
23.1	63	CSV data sources can be viewed in a source code view or in a table view. The view can be switched by clicking the appropriate button {{ficon name="table-large"/}}/{{icon name="code"/}} beneath the editing area.
1.1	64
23.1	65	//Source code view of a CSV data source//: ([[CSV file format>>https://en.wikipedia.org/wiki/Comma-separated_values\|\|target="_blank"]])
	66	{{lightbox image="data_source_csv_source.png" title="Source code view of a CSV data source"/}}
	67	//Table view of a CSV data source//:
	68	{{lightbox image="data_source_csv_table.png" title="Table view of a CSV data source"/}}
1.1	69
23.1	70	=== Editing CSV tables ===
1.1	71
23.1	72	There is a row of buttons beneath the editing area for editing the CSV data table:
1.1	73
23.1	74	* {{ficon name="plus-circle"/}} Insert: Inserts new rows or columns relative to the selected cell.
	75	* {{ficon name="trash-alt2"/}} Remove: Removes the selected row(s) or column(s) or empties the selected cell.
	76	* {{icon name="upload"/}} Import: Opens up the [[dialog for importing CSV data sources>>\|\|anchor="data_source_import_csv"]].
	77	* {{icon name="code"/}} Source code view: Switches to source code view.
1.1	78
23.1	79	=== Header of CSV data sources ===
1.1	80
23.1	81	There is an additional option for CSV data sources in the data source settings. The option First row is header determines how the values of the data sources are being accessed via its servlet ({{code language="none"}}XFC_METADATA.urls.datasource_csv{{/code}}):
1.1	82
23.1	83	* Activated:
	84	The cells of the first row will be used as {{code language="none"}}keys{{/code}} for accessing the values of the respective columns (see [[example>>\|\|anchor="data_source_csv_example"]]).
	85	* Deactivated:
	86	The {{code language="none"}}keys{{/code}} for accessing the values of individual data fields/ rows are enumerated, starting with {{code language="none"}}0{{/code}}. These keys have the following form: {{code language="none"}}colX{{/code}} where {{code language="none"}}X{{/code}} stands for the column index.
1.1	87
23.1	88	{{lightbox image="data_source_csv_settings_en.png" title="The option first row is header determines how the values of CSV data sources are accessed with its servlet"/}}
1.1	89
23.1	90	CSV data sources can be accessed in the {{designer case="dat"/}} via its servlet: {{code language="none"}}XFC_METADATA.urls.datasource_csv{{/code}}.
1.1	91
23.1	92	=== Servlet parameters ===
1.1	93
	94	{{info}}
	95	Servlet-URL
	96	http(s):~/~/<server>/formcycle/datenquellecsv?mandantName=<Mandant-Name>&name=<Datenquellen-Name>
	97	{{/info}}
	98
	99	Bei Zugriff aus dem {{designer case="dat"/}} verwenden Sie immer das globale Variablen-Objekt //XFC_METADATA//, siehe hierzu auch [[Globale Designer Variablen>>https://jsdocs.formcycle.eu/jsdocs/de/modules/_formcycle_v6_de_d_.html#xfc_metadata\|\|target="_blank"]]. Beispielsweise kann wie folgt darauf zugegriffen werden: {{code language="none"}}XFC_METADATA.urls.datasource_csv{{/code}}.
	100
23.1	101	Always use the global variables object {{code language="none"}}XFC_METADATA{{/code}} when accessing data sources from the {{designer/}}, see also [[global designer variables>>doc:Formcycle.Designer.Form.CodingPanel.ScriptTab.FormMetadata]]. The servlet URK can be accessed as follows: {{code language="none"}}XFC_METADATA.urls.datasource_csv{{/code}}.
1.1	102
23.1	103	The following parameters are possible:
1.1	104
23.1	105	\|=name of the parameter\|=description\|=necessary
	106	\|name\|Must match the name of the CSV data source.\|Yes
	107	\|mandantName\|Must match the name of the client under which the data source was created.\|Yes, if //projektId// is not given.
	108	\|projektId\|Must match the ID of the form. These information can be recalled via {{code language="none"}}XFC_METADATA.currentProject.id{{/code}}.\|Yes, if //mandantName// is not given.
	109	\|kopfzeile\|Indicates a comma seperated list with column name of the CSV table. If this is not given, the first line of the CSV is used.\|No
	110	\|spaltenNamen\|Indicates a comma seperated list of the column, which columns are redelivered of the //servlet// with the corresponding value. At this, according to using, the names of the columns of the parameter //headline// or the name of the first line of the //CSV// databaseHierbei are expected.\|No
	111	\|csvTrennzeichen\|Indicates the seperator between the single data cells. If this is not set, a comma {{code language="none"}},{{/code}} is used by default.\|No
	112	\|csvQuote\|The seperator with which the values of the lines are seperated. If this is not set, a inverted comma {{code language="none"}}"{{/code}} is used by default.\| No
	113	\|jsonPath {{version major="7" minor="3"/}}\|This parameter allows specifying a JSON path expression which will be applied to the returned result of the query on the server side. The example //$.returnValue[0]// returns the values of the first result of the query.\|No
1.1	114
23.1	115	=== Application example ===
1.1	116
23.1	117	A CSV data source with the option activated: First row is header. It has the following content:
1.1	118
	119	{{code language="csv"}}
23.1	120	title,firstName,lastName,zip,city
1.1	121	Herr,Max,Mustermann,1000,Musterhausen
	122	Frau,Monika,Mustermann,2000,Musterdorf
	123	Frau, Luise,Musterfrau,3000,Musterstadt
	124
	125	{{/code}}
	126
23.1	127	In the {{designer/}} the following script is used in the [[script area>>doc:Formcycle.Designer.Form.CodingPanel.ScriptTab.WebHome]] for pre-filling form fields:
1.1	128
	129	{{code language="javascript"}}
	130	$.getJSON( XFC_METADATA.urls.datasource_csv + "?name=Demo&mandantName=xima.de", function(json) {
	131	var obj = json.returnValue[0];
	132
23.1	133	$('[name=tfTitle]').val(obj.title);
	134	$('[name=tfFirstName]').val(obj.firstName);
	135	$('[name=tfLastName]').val(obj.lastName);
	136	$('[name=tfZIP]').val(obj.zip);
	137	$('[name=tfCity]').val(obj.city);
1.1	138	});
	139	{{/code}}
	140
23.1	141	{{lightbox image="data_source_csv_designer_script_en.png"/}}
1.1	142
23.1	143	This form example is provided as a [[download>>attach:CSV-Demo_en.json\|\|rel="__blank"]].
1.1	144
23.1	145	=== Exeption selection element ===
1.1	146
23.1	147	{{figure image="data_source_csv_designer_en.png"}}
	148	The connection of a data source to a selection element takes place directly in the {{designer/}}
1.1	149	{{/figure}}
	150
23.1	151	If the //CSV// data source has to be loaded directly in a [[selection element>>doc:Formcycle.Designer.Form.FormElements.Selection]], this happens via through the properties of the selection element in the {{designer/}}.
1.1	152
23.1	153	The content of the CSV data source is processed in a [[selection element>>doc:Formcycle.Designer.Form.FormElements.Selection]].
1.1	154
	155	{{code language="none"}}
23.1	156	visible value, assigned value, optional value, optional value, ...
1.1	157	{{/code}}
	158
23.1	159	Columns of the data source are use as follows for [[selection elements>>doc:Formcycle.Designer.Form.FormElements.Selection]]:
	160	{{code language="none"}}col + column index{{/code}}.
1.1	161
23.1	162	If a data source has more than two columns than it contains optional values. These optional values can be accessed with JavaScript via the following jQuery selector:
1.1	163
	164	{{code language="javascript"}}
	165	$('[name=sel2]').find('option:selected').attr('col2');
	166	{{/code}}
	167
23.1	168	Optinal values start at column index 2.
	169	If the first row is marked as a header than it will be ignored for selection elements.
1.1	170
	171	== XML ==
	172
23.1	173	The XML data source acts analogously to the //CSV// data source, but cannot be bound to a [[selection element>>doc:Formcycle.Designer.Form.FormElements.Selection]].
1.1	174
	175	{{figure image="data_source_xml_servlet_json.png" width="300"}}
23.1	176	The JSON structure of the XML data source. To this JSON structure can than be accessed to {{code language="none"}}XFC_METADATA.urls.datasource_xml{{/code}} via Javascript.
1.1	177	{{/figure}}
	178
23.1	179	=== Example for an XML data source ===
1.1	180
	181	{{code language="xml"}}
	182	<root>
	183	<person>
	184	<anrede>
	185	Herr
	186	</anrede>
	187	<vorname>
	188	Max
	189	</vorname>
	190	<nachname>
	191	Mustermann
	192	</nachname>
	193	</person>
	194	<person>
	195	<anrede>
	196	Frau
	197	</anrede>
	198	<vorname>
	199	Monika
	200	</vorname>
	201	<nachname>
	202	Musterfrau
	203	</nachname>
	204	</person>
	205	</root>
	206	{{/code}}
	207
	208
23.1	209	=== Servlet parameter ===
1.1	210
	211	{{info}}
	212	Servlet-URL
	213	http(s):~/~/<server>/formcycle/datenquellexml?mandantName=<Mandant-Name>&name=<Datenquellen-Name>
	214	{{/info}}
	215
23.1	216	If you access from the {{designer/}}, always use the global variable object //XFC_METADATA//, see also [[global designer variables>>doc:Formcycle.Designer.Form.CodingPanel.ScriptTab.FormMetadata]]. For example it can be accessed as follows: {{code language="javascript"}}XFC_METADATA.urls.datasource_xml{{/code}}.
1.1	217
23.1	218	The following parameter are possible:
1.1	219
23.1	220	\|=Parameter name\|=Description\|=Neccessary
	221	\|mandantName\|Must match the name of the client under which this data source was created.\|Yes
	222	\|name\|Must match the name of the CSV data source.\|Yes
	223	\|jsonPath {{version major="7" minor="3"/}}\|This parameter allows specifying a JSON path expression which will be applied to the returned result of the query on the server side. The example //$.returnValue[0]// returns the values of the first result of the query.\|No
1.1	224
	225	== JSON ==
	226
23.1	227	The //JSON// data source acts analogously to the //CSV// data source, but cannot be bound to a [[selection element>>doc:Formcycle.Designer.Form.FormElements.Selection]] directly.
1.1	228
	229	{{figure image="data_source_json_servlet_json.png"}}
23.1	230	The JSON structure of the JSON data source. It is identically equal to the JSON data source. This JSON structure can be accessed via Javascript through {{code language="none"}}XFC_METADATA.urls.datasource_json{{/code}}.
1.1	231	{{/figure}}
	232
23.1	233	=== Example for a JSON data source ===
1.1	234
	235	{{code language="json"}}
	236	{"person":[
	237	{
	238	"anrede":"Herr",
	239	"vorname":"Max",
	240	"nachname":"Mustermann"
	241	},
	242	{
	243	"anrede":"Frau",
	244	"vorname":"Monika",
	245	"nachname":"Musterfrau"
	246	}
	247	]}
	248	{{/code}}
	249
	250	=== Servlet-Parameter ===
	251
	252	{{info}}
	253	Servlet-URL
	254	http(s):~/~/<server>/formcycle/datenquellejson?mandantName=<Mandant-Name>&name=<Datenquellen-Name>
	255	{{/info}}
	256
23.1	257	At an access from the {{designer/}} always use the global variable object //XFC_METADATA//, see also [[global designer variables>>doc:Formcycle.Designer.Form.CodingPanel.ScriptTab.FormMetadata]]. For example you can access as follows: {{code language="javascript"}}XFC_METADATA.urls.datasource_json{{/code}}.
1.1	258
23.1	259	The following parameter are possible:
1.1	260
23.1	261	\|=Parametername\|=Description\|=Neccessary
	262	\|mandantName\| Must match the name of the client under which this data source was created.\|Yes
	263	\|name\| Must match the name of the CSV data source.\|Yes
	264	\|jsonPath {{version major="7" minor="3"/}}\|This parameter allows specifying a JSON path expression which will be applied to the returned result of the query on the server side. The example //$.returnValue[0]// returns the values of the first result of the query.\|No