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

dbjam_detail_head

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

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

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'

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
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_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($tabella_db,$row,$params)

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

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

Visibilità di tabelle - in jpconfig/jpconfig.php - gestito con un IF
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
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

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,...

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

il tipo del campo (se diverso dal default)
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', è possibile referenziare campi usando la sintassi $campo$

$_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

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

To Do

(in ordine di priorità)

traduzione relazioni uno-molti con multiselect: In dettaglio dovrebbe essere possibile fare selezioni uno-molti usando delle liste multiselect, quando vi è una opportuna configurazione (usare sistema simile a quello usato per le liste tendina). Implementare prima per visual. dettaglio, poi per elenco (lista testo)

verifiche: Verifiche automatiche della validità dei dati, per i tipi di dati/lunghezze in cui si sbaglia più facilmente (es. date)

Plugin Standard

Ajaxtags

Sintassi:

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

FAQ

Come rendere una query parametrizzata?

Identificare la tabella principale della tabella e chiamarla con l'alias "tabella"
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.

DBJam

DB.Jam

Funzionalità

Caratteristiche speciali

File system

Plugin

Plugin - Sintassi

Actions

Filters

Plugin di esempio

Eventi

admin_menu (filter)

am_menu (action)

custom:XYZ (filter)

dbjam_detail_head

login (action)

login_info (filter)

plugins_loaded (action)

Filtri

Uso

aftersave_action($params)

before_query_list($sql,$params)

before_list_display($tabella_db,$userid)

before_record_display($tabella_db,$row,$params)

before_record_save($tabella_db,$row,$params)

after_record_save($params)

Configurazione

Permessi, Criteri di accesso/visibilità

Configurazione jpconfig.php

Configurazione jpconfig/tabella.conf

campi_ricerca

campo_ord_def

campo_ord_verso

custom_fields

fields_displayorder

fields_hidden

nome_tabella

nome_campi

query

relazione_campi

checkbox

dropdown

multiselect

password

relation.label

relation.shadow

shadow

textarea

comandi_record

File comandi a inclusione

permessi

translation

Uso dall'esterno

jplist

jpdetail

To Do

Plugin Standard

Ajaxtags

FAQ

Navigation menu

Search