Manuale DBJAM

DB.Jam

Funzionalità

browsing tabelle

Visualizzazione di lista delle tabelle di un DB, con possibilità di esclusione

browsing dati

Visualizzazione dei dati contenuti in ogni tabella, con possibilità di escludere specifiche colonne e con due visualizzazioni possibli: elenco (tutti i record) e dettaglio (un solo record)

aggiunta

Aggiunta di un record (usando la pagina dettaglio)

modifica

Modifica di un record visualizzato (usando pagina dettaglio)

cancellazione

Cancellazione di un record visualizzato (usando pagina dettaglio). Include conferma.

Caratteristiche speciali

• Funziona senza bisogno di configurare le tabelle/campi (si configurano solo eccezioni e esclusioni)
• Gestione delle tabelle di traduzione (con Drop-down list, solo modo dettaglio)
• Le pagine si possono sfruttare a vantaggio di un'altra applicazione esterna

File system

Il sistema DB.Jam consta di tre pagine:

jptables.php

Mostra la lista di tutte le tabelle del DB, con link al successivo

jplist.php

Esegue la lista dei record di una tabella, con link al successivo

jpdetail.php

Esegue il visualizza dettaglio/modifica/inserisci/cancella di un record

Il core del pacchetto:

include/johannaPhp.inc.php

Il core

(le AM_API)

include/classes/tabelle.class.php

Pure core

La configurazione

jpconfig/jpconfig.php

configurazione generale

jpconfig/*tabella*.conf

configurazione per *tabella*

jpconfig/cmd_*funzione*.txt

comandi a inclusione - funzionalità *funzione*

Le immagini

images/*.gif

varie

Plugin

AManag/DBJam sono espandibili tramite plugin, che sono file PHP confezionati con una logica sotto descritta e che vanno messi nella cartella plugins.

Plugin - Sintassi

1. In cima al plugin ci deve essere un commento PHP che riporti i seguenti campi:

Plugin Name

nome del plugin come deve apparire

Plugin URI

URL di riferimento (da cui si può scaricare una versione successiva)

Description

Che cosa fa

Author

Autore, nome

Version

Versione

Author URI

URL per contattare l'autore (tipicamente, la sua homepage)

2. Nel plugin ci sono una serie di funzioni. E' strettamente consigliato premettere un prefisso di due lettere e underscore tipico del plugin ("sl_", "xv_", "ec_") per evitare conflitti con altri plugin e funzioni wordpress.

3. In fondo vanno fatte le chiamate per registrare le funzioni principali ("hooks") del plugin. Per questo si usano le due istruzioni

add_action
add_filter

Actions

Definiscono una funzione da chiamare in risposta a un evento. Questa funzione non può ritornare valori, può solo produrre side effect. E' possibile specificare un ordina di priorità con cui le action verranno applicate, più è piccolo il numero più è alta la priorità.

sintassi:

add_action('id_evento', 'funzione',priorità,num_param);

significa:

"al verificarsi dell'evento plugins_loaded esegui: sl_init()

Nel codice PHP, le action vengono chiamati così:

$retval=do_action('id_evento',argomento1,argomento2,...);

Filters

Definiscono una funzione che modifica l'output e lo ritorna, da chiamare in risposta a un evento. E' possibile specificare un ordina di priorità con cui verranno applicati, più è piccolo il numero più è alta la priorità.

Esempio:

add_filter('login','sl_login',10,2);

significa:

"al verificarsi dell'evento 'login' chiama la funzione sl_login - questo filtro ha priorità 10 e accetta in input 2 parametri"

I filtri ritornano un valore che dipende dall'evento stesso, vedere la documentazione relativa agli eventi più sotto. Attenzione perchè in presenza di più filtri il risultato del primo filtro viene dato come argomento al secondo, quello di priorità inferiore.

Nel codice PHP, i filtri vengono chiamati così:

$retval=apply_filters('id_evento',argomento1,argomento2,...);

Plugin di esempio

Segue un plugin di esempio, myplugin.php, il cui scopo è quello di consentire a qualunque utente si logghi con person/person di entrare in AManag legato all'utente con ID=1

<?php
/*
Plugin Name: Special Login Plugin
Plugin URI: http://www.tektank.it
Description: Allows the user person/person to log in locally
Author: Cristiano Leoni
Version: 0.1
Author URI: http://www.tektank.it/cleoni

This is a comment!

*/


function sl_init() {
	//echo "SPECIAL LOGIN PLUGIN INITED";
}

function sl_login($user,$pass) {
	if ($user == 'person' && $pass == 'person') {
			$_SESSION['valid_user'] = true;
			$_SESSION['login']	= $user;
			$_SESSION['member_id']	= 1;

	}
}

// Register hooks
add_action('plugins_loaded', 'sl_init');
add_action('login','sl_login',10,2);

?>

Vedere comunque nella cartella plugins_inactive per altri esempi aggiornati.

Eventi

admin_menu (filter)

Evento che viene chiamato durante la generazione del menu in cima.

am_menu (action)

Evento che viene chiamato durante la generazione del menu di AManag.

Attualmente si raccomanda di aggiungere allo stream corrente una riga di una TABLE, così:

function ttvideo_add($data) {
       return $data . "<TR><TD><A HREF=\"plugins/tektankvideo/page.php\">
       <IMG BORDER=0 WIDTH=64 HEIGHT=64 
        SRC=\"plugins/dummyoption/images/option.gif\" /></A></TD><TD>
        <A HREF=\"plugins/dummyoption/page.php\">Dummy Option</A></TD></TR>";
}

custom:XYZ (filter)

Produce un controllo Custom legato a un campo custom di una tabella (vedi anche: custom_fields) Viene chiamato da jpdetail mentre mostra la pagina dati di un record di una tabella.

Sostituire XYZ con il tipo del controllo custom utilizzato. Esempio: custom:ajaxtags per un campo ajaxtags

custom:XYZ_search (filter)

Produce un controllo Custom legato a un campo custom di una tabella (vedi anche: custom_fields) a scopo di ricerca Viene chiamato da jpdetail mentre mostra la pagina di ricerca.

Sostituire XYZ con il tipo del controllo custom utilizzato. Esempio: custom:ajaxtags_search per un campo ajaxtags

custom:XYZ_search_perf (filter)

Produce delle condizioni (conds) e delle tabelle (tables) addizionali da utilizzzare nella query durante una ricerca. Ritorna un array associativo con chiavi: 'conds' e 'tables'. Viene chiamato da jplist prima di svolgere la ricerca.

Sostituire XYZ con il tipo del controllo custom utilizzato. Esempio: custom:ajaxtags_search_perf per un campo ajaxtags

dbjam_detail_head

Chiamato quando DBJam sta generando la HEAD della pagina dettaglio (jpdetail)

Input: non usato Output: codice HTML da aggiungere nella HEAD

dbjam_after_field

Chiamato quando DBJam ha generato un campo e ha stampato l'eventuale testo di help (jpdetail)

Input: (field,row) Output: ?

login (action)

Chiamato quando AManag esegue il login.

Input: username, password Output: Array associativo: (result,login,member_ID) result può essere "OK" o "KO", il login è sempre una stringa e member_ID è l'ID numerico della persona che è stata ammessa con quelle credenziali.

login_info (filter)

Chiamato dalla pagina di login (login.php) per ritoccare o modificare il messaggio che appare sotto la form per le credenziali. Usare questo filtro per dare un diverso messaggio circa le modalità di accesso, l'helpdesk...

plugins_loaded (action)

Chiamato da ogni pagina quando tutti i plugin sono stati caricati. Da usare per l'init dei plugin.

Filtri

I filtri sono funzioni PHP che servono a estendere le funzionalità di DBJam ove le impostazioni del file di configurazione non siano sufficienti.

Uso

Scrivere le funzioni filtro in un file denominato tabella.php nella cartella jpconfig.

All'apertura di una tabella o vista il motore DBJam automaticamente controlla la presenza di questo file php, se lo trova lo apre e include le funzioni che in esso si trovano.

Le funzioni vengono poi richiamate come secondo la documentazione sottostante.

aftersave_action($params)

Ottiene il valore da impostare nella pagina di dettaglio come azione 'aftersave': se vale NULL dopo il salvataggio di norma si torna alla lista, se vale 'stay' si resta nella pagina.

Chiamata quando

dovunque

Dove

jpdetail

Input

non usato

Output

Stringa da usare per il parmatero _aftersave: NULL oppure 'save'

dbjam_after_field($params)

Produce contenuto addizionale dopo un campo

Chiamata quando

dovunque

Dove

jpdetail

Input

array(campo,$row)

Output

Stringa da stampare

before_query_list($sql,$params)

Chiamata quando

Prima di eseguire la query

Dove

jplist

Input

SQL della query da eseguire ($sql) parametri a piacere $params

tabella_db: prototipo tabella, userid: id utente

Output

SQL della query da eseguire

before_list_display($tabella_db,$userid)

Chiamata quando

Prima di stampare la lista record

Dove

jplist

Input

tabella_db: prototipo tabella, userid: id utente

Output

non usato - modifica $tabella_db

before_detail($tabella_db,$row,$params)

Chiamata quando

della before_record_display, a tabella già identificata

Dove

jpdetail

Input

tabella_db: prototipo tabella, userid: id utente

Output

non usato - modifica $row variabile global

before_record_display($tabella_db,$row,$params)

Chiamata quando

Prima di stampare la scheda record

Dove

jpdetail

Input

tabella_db: prototipo tabella, userid: id utente

Output

non usato - modifica $row variabile global

before_record_save($params=array('table'=>$tabella_db,'data'=>$row,'userid'=>$userid))

Chiamata quando

Prima di salvare la scheda record

Dove

jpdetail

Input

$tabella_db prototipo tabella, $row dati attuali, member id

Output

non usato - modifica global $POST

Esempio

function before_record_save($params) {
	global $locale,$_POST;
	global $am_db;
	global $admin_monitor;
	global $owner_field;

	$tabella_db = $params['table'];
	$row = $params['data'];
	$userid = $params['userid'];

	$_POST[$owner_field] = $userid; // Set new author
	$_POST['offe_descr'] = clean_html($_POST['offe_descr']);
}

after_record_save($params)

Chiamata quando

Prima di salvare la scheda record

Dove

jpdetail

Input

un array associativo con i seguenti campi table: oggetto tabella_db salvata data: _POST userid: userid dell'utente che ha eseguito l'operazione keyvalues: array associativo (field name,field value) delle chiavi del record appena salvato

Output

non usato - modifica global $POST

Configurazione

Permessi, Criteri di accesso/visibilità

A seconda del livello di importanza si interviene in punti diversi

1. Visibilità di tabelle - in jpconfig/jpconfig.php - gestito con un IF
2. Operazioni consentite per profilo, default - in jpconfig/jpconfig.php - $JP_allowed_ops
   1. Equivalenze profili app esterne -> DB.Jam - in jpconfig/jpconfig.php - $JP_profile_mapping
3. Operazioni consentite per profilo, specifiche per tabella - jpconfig/*tabella*.conf - permessi - per i profili che non definisci vale il default

Configurazione jpconfig.php

Configurazione di DB.Jam.

$JP_allowed_ops

Operazioni consentite per i vari profili

E' un array associativo le cui chiavi sono i profili, i valori sono combinazioni delle lettere RWDNLXS che stanno per Read Write Delete New List eXtended Search

Esempio:

$JP_allowed_ops = array("0"=>"","1"=>"LRS","2"=>"RWNLXS","3"=>"RWDNLXS"); 

$JP_chunksize

Numero intero che esprime quanti record devono essere prelevati per default nella visualizzazione lista

Esempio:

$JP_chunksize = 20; 

$JP_profile_default

Tipo di accesso per default

Esempio:

$JP_profile_default = ""; //nessuno

$JP_profile_mapping

Equivalenze profili esterni=>locali (array associativo)

Esempio:

$JP_profile_mapping = array("Tirocini/2"=>2); //Tirocini 2 equivale a DBJam/2

$JP_tables_hidden

Array di stringhe che definisce quali tabelle possono essere visualizzate. Attualmente c'è una logica decisionale che assegna valori diversi a seconda del profilo.

Per ogni tabella può essere specificata una configurazione di dettaglio che va nel file:

jpconfig/nometabella.conf

questo file usa una sintassi ben definita

Configurazione jpconfig/tabella.conf

campi_ricerca

Cambia il sistema di matching per la ricerca su uno o più campi. Tipicamente, ci possono essere campi dove non si vuole necessariamente il match "uguale", ma magari si vuole cercare tutti i recod che contengono una stringa, tutti record minori di una stringa, ecc. Per quelli conviene impostare il sistema "select" che prevede l'utente usi una tendina per specificare il tipo di match desiderato.

Sintassi:

campi_ricerca nomecampo=opzione[,nomecampo=opzione...]

opzione

può assumere due valori: select (selezionare tipo di ricerca) oppure equal (default)

Esempio

campi_ricerca	convscad=select

campo_ord_def

Specifica il campo (o i campi) su cui ordinare la tabella.

Esempio

campo_ord_def	.member_id

Si possono specificare più campi e le preferenze di ordinamento con le parole chiave desc e asc. Esempio:

Altro esempio

campo_ord_def	gender desc,member_id asc

da notare che se definito un legame per quel campo l'ordine sarà del legame e non del campo stesso es: il campo è id_azienda ma io visualizzo il nome dell'azienda che stà in un'altra tabella, l'ordine sarà sul nome e non sull'id)

Nota: Se viene utilizzato contemporaneamente il setting query questo settaggio risulterà ignorato. In questo caso l'ordinamento va contemplato direttamente nella query.

campo_ord_verso

Imposta il verso ordinamento sul campo scelto: ASC o DESC

Esempio

campo_ord_verso	DESC

custom_fields

Specifica dei campi custom, e il loro tipo. Formato:

custom_fields	id=type,paramters,...;id=type,paramters,...

Esempio

custom_fields	tags=ajaxtags,$member_id$,tags_people,member_id,false

dupe_finder

Imposta una ricerca duplicati sui campi specificati. Formato:

dupe_finder	campo1,campo2,...

fields_displayorder

Forza un ordine di display dei campi (per default è l'ordine in struttura tabella). Formato

fields_displayorder	campo1,campo2,...

Esempio

fields_displayorder doma_id,doma_target

Nota: I campi non elencati si intendono implicitamente e automaticamente aggiunti in coda. Non è quindi possibile omettere campi per nasconderli. per questo, usare fields_hidden oppure i tipi campo shadow e relation.shadow

fields_hidden

Campi da nascondere. Formato

fields_hidden	list=campo1,campo2,...;detail=campo1,campo2,...

Esempio

fields_hidden	list=campo1,campo2,...;detail=campo1,campo2,...

fields_validation

Validazione campi. Formato

fields_validation	campo1=validazione1,campo2=validazione2,...

la validazione scelta deve essere un codice comprensibile alla rouitine Javascript di validazione, che può essere "noemptyhtml" oppure altri valori dati da include/genvalidator31.js

Esempio

fields_validation doma_risult=noemptyhtml,doma_argom=noemptyhtml

nome_tabella

Nome da visualizzare Esempio

nome_tabella	Aziende

nome_campi

Nomi dei campi da visualizzare nel formato:

nomecampo=nomedavisualizzare[,nomecampo=nomedavisualizzare]

il campo viene visualizzato solo se non presente nella lista dei campi hidden

Esempio

nome_campi	settid=Settore

query

Query da invocare per estrarre i dati. Da usarsi in alternativa a tabella esistente

In questo caso nome_campi darà una lista dei campi da visualizzare.

Esempio

query	SELECT i.id,i.name FROM imprese i WHERE titolaremf = 'f' UNION SELECT i.id,i.name FROM imprese i, pers2org m, AT_members p WHERE m.member_id=p.member_id AND m.org_id=i.id AND m.role_type <> 6

relazione_campi

Questa impostazione specifica

1. il tipo del campo (se diverso dal default)
2. Eventuali legami tra il campo e altre tabelle (esempio: tendina drop-down invece che un id) nel

Il formato è il seguente:

relazione_campi nome_campo_tabella_corrente=>tipo_visualizzazione[,parametri][; ...]

nome_campo_tabella_corrente

Nome del campo a cui si riferisce il resto fino al prossimo ; o fine riga

tipo_visualizzazione

Può essere uno dei seguenti:

dropdown,password,textarea,checkbox

parametri

Dipende dal tipo_visualizzazione scelto

checkbox

Non serve specificare nient'altro. Nota: In realtà viene reso con due radiobutton per motivi tecnici

Esempio

relazione_campi        mansione_esteso=>checkbox

dropdown

tabella_di_traduzione,campo_id_sulla_tabella_di_traduzione,campo_descriz1[:campo_descriz2][,condiz_sql]

condiz_sql è una clausola WHERE che viene aggiunta alla query. Se si vuole fare join su altre tabelle le si possono specificare usando uno * come virgola e tenendo conto che la tabella principale ha l'alias 'tabella'

Esempio

relazione_campi	settid=>dropdown,trad_settori_merc,settid,settname

Note

• Per usare le funzioni di traduzione automatica, si può specificare la stringa

$_language$

nel nome campo da visualizzare: la stringa verrà automaticamente rimpiazzata a run-time con il codice lingua in uso.

• se si specifica la condizione WHERE ma si vogliono aggiungere tabelle prima della WHERE, considerare che la virgola si può rendere con il carattere asterisco *

multiselect

tabella_di_traduzione,tabella_di_relazione,campo_id_questa_tabella,campo_id_traduzione[,campo_descriz1:campo_descriz2][,WHERE condiz_sql]

Esempio

relazione_campi	settid=>multiselect,trad_settori_merc,prod2sett,prod_id,sett_id,sett_name

Note

• Per usare le funzioni di traduzione automatica, si può specificare la stringa
• se si specifica la condizione WHERE ma si vogliono aggiungere tabelle prima della WHERE, considerare che la virgola si può rendere con il carattere asterisco *
• condiz_sql: deve inziare con WHERE, poi considerare che la tabella con i dati da visualizzare è aliasizzata come 'tt'

$_language$

nel nome campo da visualizzare: la stringa verrà automaticamente rimpiazzata a run-time con il codice lingua in uso.

password

Non serve specificare nient'altro

Esempio

relazione_campi        mansione_esteso=>password

relation.label

esattamente come dropdown, però produce una label read-only

relation.shadow

esattamente come dropdown, però produce un campo "shadow", che non si vede ma è presente in HTML come hidden

shadow

Produce un campo "shadow", che non si vede ma è presente in HTML come hidden. A differenza di relation.shadow, non si basa su una relazione

textarea

Non serve specificare nient'altro

Esempio

relazione_campi        mansione_esteso=>textarea

upload

Sintassi: upload[,campo titolo[,filtro]]

filtro: Serie di estensioni ammesse da pipe "|"

Esempio

relazione_campi        offe_image=>upload,,jpg|png

special_records

Definisce dei set di chiavi i cui record sono considerati "speciali" (tipicamente valori di default) che non saranno visualizzati nella vista LIST e non saranno comunque cancellabili.

special_records key1=val1,key2=val2[;key1=val1,key2=val2 ... ]

Esempio

special_records offo_id=1

comandi_record

Imposta i comandi speciali che devono essere resi disponibili per ogni record (quindi sia in modalità lista che dettaglio).

Il formato è il seguente

comando = Etichetta_comando , icona , file_include [,vista [,permessi] ] [; comando = ...]

comando

Identificativo che rappresenta il comando. Sarà l'ID del controllo HTML

Etichetta_comando

Stringa che l'utente vedrà sul pulsante

icona

File da usare come icona. L'immagine si troverà dentro images/

file_include

File che andrà incluso con il codice del comando stesso.

vista

Può essere: list | detail | * per tutti (default)

permessi

elenco dei profili abilitati separati da / esempio: 1/2/3. -1 = tutti (default)

Per il nome del file incluso, si raccomanda di utilizzare estensione .txt e un prefisso cmd_ in modo che si capisca che si tratta di comandi a inclusione.

File comandi a inclusione

Ogni riga del file incluso può utilizzare valori del record corrente usando un marcatore del tipo $nomecampo$ che viene automaticamente rimpiazzato con il valore attuale di quel campo. Esistono inoltre dei marcatori speciali che fanno riferimento a informazioni di contesto:

$_userid$

fa riferimento allo user id dell'utente collegato all'applicazione.

$_date$

fa riferimento alla data attuale, restituita in formato AAAA-MM-GG

Esempio

comandi_record	usa=Nuovo tirocinio,new.gif,cmd_newtiro.txt

Esempio per il file include:

javascript:document.location.href='jpdetail.php?_table=tirocini&action=add&stato=1&azienda=$azienda$'

permessi

Imposta i permessi di accesso alla tabella. I permessi sono espressi in forma di lista separata da virgole, e ogni elemento è una coppia ordinata (profilo,operazioni consentite). La forma è del tipo:

IDprofilo1=rwdn [,IDprofilo2=RWDN]

Dove:

IDprofilo#

E' il numero di un profilo collegato all'applicazione 'DB.Jam', o uno equivalente come da configurazione di DB.Jam

RWDNSLX

E' una combinazione delle lettere rwdn che stanno per

• r = Read - visualizzazione
• w = Write - modifica in scrittura
• d = Delete - cancellazione record esistente
• n = New - aggiunta nuovo record
• s = Search - ricercare
• L = List - vedere lista dei record (e, di conseguenza, risultanza nella lista tabelle)
• x = eXtended - comandi personalizzati a livello record e campo

Il default è rwdn per tutti. Se questo parametro viene impostato, i permessi vengono controllati utilizzando il massimo numero di profilo disponibile. Il controllo è subordinato a quello generale di profilo eseguito a inizio pagina.

NB.: L'effettiva implementazione del controllo dipende dalle singole applicazioni/pagine/funzionalità.

Esempio

permessi	0=r,1=r,2=rwdn

Questa imposta rwdn per profilo 2, r per profilo 1, r per nessun profilo

translation

Imposta la traduzione automatica di nomi campi, nomi tabelle e nomi comandi sulla page del language file e la lingua attualmente selezionata

Esempio

translation	1

Uso dall'esterno

Per sfruttare DB.Jam in altre applicazioni PHP all'interno di AMAnag, tenere in considerazione quanto segue.

jplist

tabella di lavoro

Valorizzare il parametro _table per specificare la tabella su cui lavorare.

Link di ritorno

$_SESSION[JP_LINKBACK] viene usato, se definito, per visualizzare un link di ritorno all'applicazione chiamante. Esempio:

$_SESSION[JP_LINKBACK] = "Torna a <A HREF=\"tcoperatori.php\">Gestione Tirocini</A>";

Filtro di ricerca

Un filtro di ricerca può essere impostato in questo modo:

• va passato un parametro cmdSearch non nullo (metodo GET o POST)
• vanno passati i vincoli sui campi nella forma nomecampo=valore

I vincoli vengono visualizzati con una stampa di eco in cima alla pagina

Legame per operazioni di Nuovo (add)

Se è richiesto che le funzioni di aggiunta siano vincolate con alcuni valori non modificabili, specificare i vincoli in questa forma:

• vanno passati i vincoli sui campi nella forma _bind_nomecampo=valore

Pagine

Valorizzare>

_start per determinare il numero del primo record da visualizzare. Il primo record [ il n. zero.

_chunksize per determinare l'ampiezza di una pagina. Zero significa "MOSTRA TUTTI"

jpdetail

tabella di lavoro

Valorizzare il parametro _table per specificare la tabella su cui lavorare.

azione scelta

Valorizzare il parametro action per specificare che operazione si desidera.

• (nulla): Default, mostra dettaglio
• action=add: Aggiunta di un nuovo record

Link di ritorno

$_SESSION[JP_LINKBACK] viene usato, se definito, per visualizzare un link di ritorno all'applicazione chiamante. Esempio:

$_SESSION[JP_LINKBACK] = "Torna a <A HREF=\"tcoperatori.php\">Gestione Tirocini</A>";

Filtro di ricerca

Un filtro di ricerca può essere impostato sui campi chiave in questo modo:

passare i vincoli sui campi nella forma chiave=valore

Plugin Standard

Ajaxtags

Sintassi:

tags=ajaxtags,$member_id$,tags_people,member_id,false

FAQ

Come rendere una query parametrizzata?

1. Identificare la tabella principale della tabella e chiamarla con l'alias "tabella"
2. Creare un file comandi che richiami la vista-query, avendo cura di specificare cmdSearch=1 e il parametro di ricerca:

javascript:document.location.href='jplist.php?_table=view_risultati&cmdSearch=1&codice_valutazione=$id_val$'

Il parametro sarà specificabile a partire da un campo di un record corrente.