table-info.txt


********************* JavaScript Ajax table ********************

by Dvestezar www.dvesstezar.cz
využívá knihovny
  - jQuery
  - JB

použití  tblxxx = new JBajaxtable.init(sqlname,idtbl,{order,fields,sqlparam,order_ren,elementerror,
						bodyheight,trsel,trCSS,addquery,ontrcreate,ontdcreate,onheadertdclick,onadddataloaded,onselect})

	kde
		idtbl		= může být 1)string nebo 2)HTML element objekt
					1) pokud je zadáno jako text, tak se bere jako ID elementu a pokusí se jej najít pomocí funkce document.getlementByID
					2) pokud je na vstupu objekt tak se bere přímo jako HTML element objekt DIVu a !!! musí mít nastaven atribut ID !!!,
						!!!! toto id je použito při ukládání informací o uživatelských nastavení pro sloupce tabulky
			
		sqlname		= jméno sql řetězce z XML
		objekt nepovinných parametrů
			title		= nastaví nadpis tabulky, na následující změny lze použít funkci .setNadpis, pokud není zadáno, je použito '' a TR s nadpisem je skryt
			firstread	= jestli se mají data načíst pri inicializaci, nebo bude první načtění vyvoláno až kódem přes refresh
						default je true
			requesttype = POST nebo GET
			order		= jméno fieldu/ů podle kterého se má řadit / pro sestupné se přidá ' DESC' tj 'fieldxxx desc', oddělené čárkami
			fields		= definování názvů a skrytí fieldu
						- object {'filed':'nazev','field2':'nazev2'}
							kde
								field = název fieldu u SQL - používat uzavírání v apostrofech, protože SQL dotazy používají jména jako 'tabulka.field'
								nazev = název který bude zobrazen,
									  pokud
										1) je zadán prázdný název, bude field(sloupec) vynechán
										2) pokud bude první znak vykřičník, nebude na tomto fieldu(sloupci) fungovat řazení kliknutím na hlavičku sloupce
			selectable	=	default=prázdný řetězec jinak obsahuje řetězec názvu klíčového fieldu
							pokud je název nalezen, tak je zprovozněno vybírání řádků a propertie tohoto objectu ".val", popis viz níže,
							v základu jde vybrat jen jeden řádek, viz další proměnná
							
							vybrané řádky se pamatují přes refresh
			multiselect =   default je false, pokud není zadána předchozí proměnná, je tato volba ignorována
							pokud true, lze vybrat více řádků, ovlivňuje propertie tohoto objektu ".val" viz níže
							tato hodnota lze měnit za běhu funkcí na tomto objektu ".changeMultiselect(bool)"
			set_element_on_sel = default undefined pokud nastaveno tak obsahuje HTML form element nebo jeho string ID, jako je textarea, text, hidden atp.,
							který bude nasteven po selectu
			sel_element_json = default=false, pokud true, vrátí do value elementu vybrané hodnoty(pole) jako JSON text
			set_HTMLinner_on_sel = default undefined pokud nastaveno tak bude nastaveno innerHTML objektu - 
							- pokud nastaveno tak obsahuje jakýkoliv HTML element nebo jeho string ID, jako je DIV SPAN atp
			
			showfilters = jestli se má zobrazit tlačítko pro filtrování sloupců, max počtu řádků atp. v hlavičce
						default je false (bezpečnost)
			sqlparam	= objekt default parametrů které budou odeslány jako json string v parametru "p"
							př : {dt:'2011-11-01',neco:'cokoliv'}
						!!! pozor tento parametr je ovlivněn udáslostí sqlparamfn viz. níže !!!
			scriptfilename = možnost změnit základní ovládací script serveru 'get_tbl.asp'
							AJAX volá tento název jako URL + parametry
			offlinedata = pole které je normálně vraceno jako JSON, pokud je použito toto, nebude volán ajax JSON, ale vemou se data z této proměnné
						bude ignorováno vše co je spojené s online definicí a aktualizací jako sqlname sqlparam, scriptfilename order ordering atp ...
						!!! sqlname musí být zadáno jako prázdný řetězec !!!!
						U offline nefunguje refresh a menu pro zobrazení sloupců a autorefresh
						není ignorováno fields
						data musí mít formát jako JSON co vrací ajax, povinné je data nebo ArrData a nepovinné adddata
						
						ostatní povinná property ajax JSON se nastaví automaticky
						tj.
							{
								//jedno ze dvou následujících
								data:assocarray,
								ArrData:headarray,
								//dále ...
								adddata:{
									table1:{assocarray},
									table2:{assocarray}
								},
								msg:'OK',		//automat
								sel:0,			//automat
								pg:0,			//automat
								maxrow:9999999,	//automat
								cnt:1,			//automat
								colsinfo : undef //nevyužito
								add_data : undef // nevyužito, jinak objekt přídavných dat podle addquery, nebo vrácených skriptem
													příklad 
													{
														data1:data,
														data2:data
													}
							}
						
						
						Příklad headarray
						1.index musí obsahovat názvy fieldů
						2. a následující jsou data fieldů
						př.
						[
							[fieldname1,filedname2, ....],
							[valfield1,valfiled2, ....],	//1.row dat nebo row index 0
							[valfield1,valfiled2, ....],	//2.row dat nebo row index 1
							....
						]
			
						Příklad assocarray
						[
							{'filedname1':'value','filedname2':value}, //row 1 index0
							{'filedname1':'value','filedname2':value}, //row 2 index1
							....
							n_row
						]
						
			ordering = jestli má být dostupná fukce řazení a jestli zobrazovat jak je řazeno, default je true
			order_ren	= objekt podmínek řazení / jen online
						  {<fieldname>:{s:'zobrazené jmeno v řádku řezeno',da:'definice řazení sestupně',dc:'definice řazení vzestupně'},fieldname2:{s:'xx',da:'def asc',dc:'def desc'}...}
						!!! <fieldname> se doporučuje používat v apostrofech - SQL může používat jména fieldu jako 'tabulka.field'
						- pokud není použito je pro řazení použito fieldů z headeru tabulky pro daný sloupec
						  tzn. pokud klikneme na header sloupce 1 kde jméno je fielname bude do SQL použito 'ORDER BY filedname popř DESC'
						  
						  kde
							da = pokud má první sloupec jmeno fieldu 'fieldname', pak po kliknutí na sloupec
							     nebude použito 'order by fieldname' ale podle 'da' 'order by 'definice řazení sestupně''
							     tak lze zadat kombinované řazení jako např. 'filed1 desc, field2, field3 desc'
							     po znovukliknutí na header sloupce je použito definice z 'dc'
							dc = pokud není zadáno 'dc' tak je umožněno řazení jen podle 'da'
							s  = zobrazené jméno které je zobrazeno pro tuto definici

							filedname je skutečný název fieldu z sql
							
						  takto lze zadat složitá řazení s jednoduchým zobrazení názvu
						  's' a 'da' musí být zadány, jinak nebudou použity
						  
						  pro zobrazení názvů řazení fieldů je použit buď přímo fieldname, nebo názvu
						  z předchozího object parametru 'fields' - definování názvů a skrytí fieldu
						  
			ordermax	= default = 2
						 kolik se má pamatovat kliknutí řazení
						 př.: klikneme na sloupec1(filed1) budeme řatit podle field1
						      dál klikneme na sloupec2(field2) tak budeme řadit podle field2 a potom field1
						      dál klikneme na sloupec3(field3) tak budeme řadit podle field3 a potom field2
						      dál klikneme na sloupec3(field3) tak budeme řadit podle field3 desc a potom field2
							    -změní se jen řazení field3
						      dál klikneme na sloupec2(field2) tak budeme řadit podle field2 a potom field3
						      dál klikneme na sloupec1(field1) tak budeme řadit podle field1 a potom field2
							  atd...
			
			addquery	= řetězec dodatečných názvů dotazů, které se načtou jen jednou při inicializaci, vynutit refresh lze viz dále
						script serveru vrátí dodatečné dotazy v root vrácených dat jako add_data.dotazx.data
						toto je provedeno jen jednou při prvním spuštění(načtení stránky a inisializaci)
						tyto data jsou připojeny k hlavním DIV jako property .add_data
						tzn. přístup k nim z venku je 
						  instance_tohoto_objektu.add_data
						zevnitř
						  ELtbl.add_data
						-pokud potřebujeme znovu načíst dodatečná data zavoláme .ResetAddDataFlag() .refresh()
			addquery_eve - default je false, pokud true tak adddata jsou načtená pokaždé, pokud false tak platí předchozí
			
			printname	= obsah nadpisu na tisknuté stránce, pokud není zadáno je použit default 'Tisk AJAX Table'
							lze ovlivnit funkcí SetPrintName(name)
			showprint	= default true - když false tak není v hlavičce zobrazen odkaz na Tisk, pokud není zadáno tak je použit
			
			autorefresh = default 0 , 0=zakázáno, jinak čas v sekundách kdy se bude tabulka obnovovat (min je 60s)
			
			elementerror= html element DIV který bude obsahovat chybové zprávy tabulky
						- pokud není zadán, bude vytvořen pod FOOT tabulky řádek ve kterém se zprávy budou zobrazovat
			bodyheight	= (zápis css stylem "height:200px")
						pokud je nastaveno, tak se omezí velikost těla tabulky na určenou výšku
						tzn.hlavička bude stálá a tělo bude scrollovatelné
			trsel		= default true - pokud true budou řádky zvýrazňovány při přejetí myši CSStřídou z trCSS
			trCSS		= default string 'sel_lr' - definování CSS třídy pro zvýraznění řádku při přejetí myši, pokud je trsel true
			
	Events:
			sqlparamfn  = funkce pro získání objektu parametrů při refresh, fn je volána před odesláním parametrů
							- funkce je volána funkce(objekt_sqlparametru)
							- tato funkce je volána s objektem SQL parametrů, ne JSON stringem, který je zaslán na server
								tento objekt je generován z objektu sqlparam při inicializaci, který mohl být zamozřejmě
								změněn uživatelskou funkcí SetParam (viz.níže)
							- tato funkce může objekt paramterů plně nahradit a zapomenout objekt_sqlparametru, tím je ignorováno sqlparam při inicializaci a funkce SetParam
								nebo může jen objekt_sqlparametru opravit, přidat properties atp
							- pokud funkce vrátí null, tak není dotaz proveden, bude zastaveno refresh - refresh je tímto zakázán, např chybné údaje
							- jinak musí funkce vrátit objekt parametrů, který je následně převeden do json (uživatel se nemusí starat) string a odeslán jako parametr "p"
							
							pozor
								pokud rozšíříme parametry o property "form", budou tyto přeneseny přímo do řetězce dotazu a ostatní
									jako JSON v parametru řetězce dotazu "p"
									
								příklad:
									params['form']={
										name1:'val1',
										name2:'val2'
									};
									params['ost']=5;
									
									to řetězce dotazu bude přidáno
											?...&name1=val1&name2=val2&p=json_encode_objekt_parametru_bez_property_form
										tzn	?...&name1=val1&name2=val2&p={'ost':5}
							
			onbefortrcreate(tbl,newdata,olddata,idx) = fn folaná před vytvořením elementu řádky
						kde
						- tbl je element tabulky
							-> tbl.toto = tento object
							-> tbl.var = pole dat z kterých je generovaná tabulka
						- olddata jsou data pro předešlý řádek
						- newdata jsou data pro nový řádek
						- idx je index řádku z pole dat
						
			ontrcreate(tr)	= fn volaná před vytvořením řádku tabulky, tj TR je vytvořen ale není vyplněn buňkami
						kde
						tr je element řádky tabulky
						tr.val jsou objekt ze kterého se generuje řádek
						potom 
						tr.val.fieldnameN0=value
						až
						tr.val.fieldnameNx=value
						tr.val={field1:val1,field2:val2 ....}
						
			onaftertrcreate(tr) = jako předchozí onbefortrcreate ale je volána až po vytvoření řádky, parametry stejné
			
			ontdcreate(td)	= fn volaná při vytvoření buňky tabulky
						kde
						td je element buňky tabulky
						td.val je hodnota kterou obsahuje buňka
						td.field je název fieldu (sloupce)
						td.tr = tr.val tzn. td.tr.filedname vrátí hodnotu fieldu z právě generovaného řádku nebo při nestandartním názvu fieldu td.tr['filed.name']
						
			onheadertdclick(td) = fn volaná při kliknutí na buňku v hlavičce tabulky kde td je elemen buňky tabulky
						-funkce může vrátit false pro zákázání provedení interního (změnu)řazení, které je standartně provedeno
						
			ondblclick()	= fn volaná při dvojkliku na datové buňky - přístup k datům je přes this,
							this=objekt tr, tzn:
								this.val  = jsou data řádku stejně jako tr.val
								this.toto = tento objekt
								
			onadddataloaded(add_data) = fn je volána jen při načtení dodatečných dat (script serveru je vrátí), kde add_data je objekt vrácených dat
							tato fn je volána i když jsou hlavní data EMPTY
							
			ondataloaded(ElTbl,data_empty,data,this,adddata) =
						ElTbl		= (HTML element) odkaz na element div pro tabulku
						data_empty	= (boolean) 	jestly byla data prázdná - empty=true
						data		= (assocobjekt) přijatá data, možno modifikovat
						this		= (objekt)		tento objekt
						adddata		= (objekt)		přídavná data, pokud byla přijata
							
							funkce je volána po načtení dat pro tabulku, těsně před jejím generování(tabulka je zrovna smazána, přístup k datům jako předchozí)
							také je volána i když jsou data prázdná - ajax chyba empty
							
			onemptydata  = fn je volána, když byly vráceny prázdná data, v tomto případě není volána ani onadddataloaded ani ondataloaded, tato funkce je pro ošetření
			
			ontablefinish(odkaz na element div pro tabulku, boolean jestli byla data empty - empty=true)
						je volána po vygenerování tabulky
							fn(el)  potom ve funkci el.ajxtbl je odkaz na tento objekt
							také je volána i když jsou data prázdná - ajax chyba empty
							
			onselect()	=  fn volaná při kliknutí myší na řádek - ve funkci this.val je přístup k datům toto nahrazuje onclick na TR
								this.val  = jsou data řádku stejně jako td.val
								this.toto = tento objekt
								
			ontdcontext(event,td) = tato funkce je volána, pokud je kliknuto pravým tlačítkem myši na buňku dat
			
			ontrcontext(event,tr) = tato funkce je volána, pokud je kliknuto pravým tlačítkem myši na řádek dat
		
jediné povinné údaje jsou sqlnane, a idtable
přístup k objektu je možno vytvořenou proměnnou v DIVu volaného při vytváření
	document.getElementById('xxx').ajxtbl
		kde xxx je ID DIVu ve kterém je tabulka vytvářena
! přístup do objektu je samozřejmě také možný přes proměnnou která je vrácena funkcí při vytváření tabulky, pokud je var používána globálně

proměnné využitelné pro případné funkce ontrcreate,ontdcreate
	na každém td bude vytvořeno property
		.val = hodnota buňky
		.field = skutečný název fieldu z sql(toto je i u buněk hlavičky, hlavička nemá hodnotu .val)
		.toto = tento objekt
		.tbl = je HTML element tabulky
		.tr je odkaz na (data) objekt fieldů ze kterého je generován řádek, stejné jako tr.val
			čte se td.tr[<jinýfield>]
			obsahuje stejná data jako z následující .val
		.tr_el = odkaz na HTML element TR který obsahuje tuto buňku
	na každém tr těla tabulky bude vytvořen property
		.val = objekt z kterého byl generován řádek tzn.: {field1:val1,field2:val2 ....}
			přístup k hodnotám je .val['fieldx']
			obsahuje stejné data jako u předchozí .tr
		.toto = tento objekt
		.tbl = je element tabulky

funkce použitelné zvenku přes
1)<instance_tohoto_objektu> - objekt vzniklý při vytvoření
2)document.getElementById('xxx').ajxtbl

	.setNadpis(tx) = změna nadpisu tabulky, '' skryje TR nadpisu

	.setSouhrn(tx) = změna souhrnu tabulky

	.setPopis(tx)  = změna popisu tabulky

	.err  = objekt pro práci s textem chyby
			.add(tx) = přidá   text do error elementu viz elementerror výše
			.set(tx) = přepíše  -||-
	! popis a souhrn se maží s update nebo clear tabulky
	
	.refresh(msg)
		msg(boolean default=false) pokud true tak se při pokusu volání refresh v průběhu načítání dat zobrazí hlášení, že nelze provést
		refresh nelze provést znovu pokud se zrovna reflreshuje
		  
		provede znovunačtení a vygenerování tabulky podle zapamatovaných nebo změněných údajů
		- ! vrací
			true - pokud je vše OK
			false - pokud v uživatelské funkci get sql param došlo k chybě, jako třeba špatně vyplněný formulář

	.loading()
		- vrací true pokud se zrovna nahrávají dat - nelze volat refresh, jinak false
		
	.ResetAddDataFlag()
		- resetuje příznak načtení dodatečných dat, tzn.při příštím refresh nebo operaci s tabulkou budou znovu načtena
		
	.SetCollVisible(fieldname,visible)
		- nastaví viditelnost sloupce na ano/ne / nastavení neviditelnosti v objektu "fields" při vytváření má prioritu
		- "visible" = true/false
		- "fieldname" = je jméno fieldu, který má být skryt
		
	.getTableRef() vrátí referenci na htmlelement objekt tabulky
	
	.getLastData() vrátí poslední načtená data
		- obsahuje objekt poslední načtená data přes ajax, z těchto dat je generována tabulka
		  obsahuje i info o stránce, počtu řádků, omezení řádků atp
		  pokud byl dodaz headedarray tak jsou data automaticky převedeny na assos array a uloženo v data
			tzn. data (viz.níže) je vždy dostupné
		  objekt
			.data = pole objektů - assoc řádků
			.cnt  = celk.počet záznamů
			.maxrow = na kolik je omezeno zobrazení počtu řádků
			.pg	 = max.strana (pro zobrazení počet stran je pg+1)
			.sel	 = vybraná strana (pro zobrazení strany je sel+1)
			.msg  = musí se rovnat "OK", jinak obsahuje chybu vrácenou serverem
		  pokud je cnt>maxrov tak je použito stránkování
	
	.SetPrintName(name) nastaví print nadpis
	
	.val() vrátí vybrané hodnoty z označených řádků jako pole řetězců podle voleb při vytváření viz výše - selectable	multiselect
			pokud multiselect = false tak je vráceno jednorozměrné pole, pokud není select zprovozněno, tak je vráceno jen []
			vybírá podle klíče v "selectable" při vytváření
			
	.val(array) vybere(označí) řádky podle vstupního pole řetezců
			pokud multiselect = false tak je vybrána hodnota v poli[0]
			př:["1","ba"] vybere řádky, které obsahují tyto hodnoty, podle klíče v "selectable" při vytváření
			
	.GetLastSelectedVal() vrací hodnotu posledního vybraného řádku podle selectable
	
	.changeMultiselect(bool) nastaví multiselect
	
funkce ovlivňující SQL hledání z venku
	volají se přes podle id hlavního DIV volaného při inicializaci
	- př: pokud vytváříme tabulku v DIV ID="xxx" tak funkce voláme
	document.getElementById('xxx').ajxtbl.SetOrder('filed desc,field2,field3 desc')
	nebo přímo inic_var.SetOrder('filed desc,field2,field3 desc')
	
	- př2:pokud v SQL řetězci máme definovány proměnné @od a @do
		funkce nepřepisuje ale definuje nový objekt, takže pokud některé proměnné nehceme měnit, musejí být stejně definovány
	document.getElementById('xxx').ajxtbl.SetParam({od:'2011-11-01',do:'2011-12-01'})
	nebo přímo inic_var.SetParam({od:'2011-11-01',do:'2011-12-01'})

	SetOrder(order)
		Nastavení řazení SQL dotazu (ORDER BY) obsahuje jen to co by mělo být za order by
		volá refresh
	SetParam(param)
		params = objekt jako sqlparams při vytváření
		Nastavení parametrů hledání přes proměnné (WHERE) nebo podle zpracování na straně serverscriptu
		volá refresh
		
	př.SQL řetězce:
	select kdo,kdy from tabulka where kdy between '@od' and '@do'
		doplnění order a datumů zajistí serverscript 


CSS
hlavní DIV/pouzdřící tabulka>TR(head,body,foot,err)/tabulka(head,body) - foot a err nemají tabulku jen innerHTML)

ajaxtblmain = TABLE pouzdřící tabulka každý řádek obsahuje hlavní složku jaho head, body atp, v body je tabulka dat

ajaxtblnadpis = TR řádek pro nadpis tabulky nastavuje se setNadpis
ajaxtblpopis = TR kam se dává popis tabulky, nastavuje se setPopis
ajaxtblord	= TR řádek kde je zobrazen text jak je řazeno a obnov tabulku
ajaxtblhead = TR řádek head, je v něm uložena pohyblivá hlavička tabulky při omezené výšce tabulky
ajaxtblbody = TR řádek obsahující tabulku s daty
	ajaxtblbodydata = TABLE obsahující data, tj tabulka se názvy řádků a daty
ajaxtblsuma = TR pro zobrazení zesumírování tabulky nastavuje se setSouhrn
ajaxtblfoot = TR řádek foot, pro zobrazení poštu stránek skriptem
ajaxtblerr  = TR nevyužit pokud není zadán externí element, jinak řádek s případnou chybou

ajax_tbl_td_head_disabled, ajax_tbl_td_head_enabled = je aplikováno na buňku v hlavičce tabulky, enabled pokud je umožněno kliknutím řazení

ajaxtblheadinner = TR  řádek hlavičky
	--> jeho buňky TD obsahují CSS "tr0" až "trNN" kde NN je číslo sloupce
ajaxtblbodyinner = TR (vždy je definován s ajaxtblbodyinner_tr0 nebo ajaxtblbodyinner_tr1 tr0 má každý první a tr1 každý druhá řádek)
    --> jeho buňky TD obsahují CSS "tr0" až "trNN" kde NN je číslo sloupce

ajaxtblbodyinner_tr0 = obsahuje každý první řádek TR těla dat
ajaxtblbodyinner_tr1 = obsahuje druhý první řádek TR těla dat


******** formát tlačítek v hlavičce a footu *********
pro všechny tlačítka platí
ajaxheaderbuttonlink = DIV odkazu nápisu
	-->ajaxheaderbuttoninnerlink = formát LINK v DIVu
	
navíc přidány css k předchozím tzn DIV tlačítka obsahuje např "ajaxheaderbuttonlink ajaxtblheadprint"
	ajaxtblheadotherbuttonmain = DIV pozdro pro ostatní tlačítka
		--> ajaxtblheadprint	=	DIV odkazu nápisu tisk v hlavičve tabulky
			--> ajaxtblheadprintlink = LINK tisk v hlavičve tabulky

		jako předchozí pro buton print
		--> ajaxtblheadrefr
			-->ajaxtblheadrefrlink
			
		jako předchozí, pro ostatní v DIVu ajaxtblheadotherbuttonmain
		--> ajaxtblhead_other
			-->ajaxtblhead_other_link
		

	ajaxtblheadordermain = pouzdro pro text a tlačítka řazení
		-->ajaxtblheadordermaintx =SPAN "řazeno podle"
		-->ajaxtblheadorder = jako předchozí pro butony print
			-->ajaxtblheadorder = jako předchozí pro butony print

			
	ajaxtblheadmenudiv = je DIV menu vyvolané po stisku tlačítka menu v hlavičce, přístup lze také přes ID #ajax_tbl_menu_div
	   každý button
			.ajaxtblheadmenubtn
				.ajaxtblheadmenulink
				
************* př. css *******************
- obarvení řádku tabulky při najetí myši - jen řádek s daty, jinak řešeno programově
	pomocí CSS
	.ajaxtblbodyinner:hover{
		color: #C60000;
		background-color: #FF9999;	
	}