jBUtil - TryLab

jBUtil è una collezione di funzioni scritte in Javascript che pone uno standard su alcune funzionalità di uso comune.

Questo plugin è nato autonomamente come una libreria che contiene delle funzionalità di ampio uso, questa collezione di utility permette di concentrarsi nello sviluppo vero e proprio, avendo come base di partenza delle funzioni ben testate a cui affidarsi.

Questo progetto è in tuttora in sviluppo è viene ampliato continuamente in base alle necessità che si possono presentare nel corso dello sviluppo di un portale Web.

Caratteristiche

Di seguito le caratteristiche principali:

Non richiede framework Javascript
Completamente testato
Basta includere il file js per poterlo utilizzare

Installazione

L’istallazione di questo plugin è molto semplice, basta includere questo script nelle pagine che dovranno essere in grado di utilizzarlo, di seguito un esempio

...    
<script src="jquery.min.js"></script>
<script src="jButil.js"></script>
...

jBUtil si può appoggiare al framework jQuery in caso sia disponibile, nel caso in cui si volesse usare anche jQuery è consigliato includerlo prima di questo plugin.

Fatto ciò è possibile utilizzare le funzionalità di jBUtil, come nell’esempio riportato qui sotto.

...
alert(jB.siteUrl());
...

Configurazione

Questo plugin necessita di alcune configurazioni di base per poter funzionare correttamente, attraverso questa sarà quindi possibile adattarlo alle proprie necessita

Qui di seguito riporto una sintetica lista delle voci da configurare e il loro significato

jB.config.segmentBaseRoot Stringa: La parte dell’url facente parte del baseUrl (vedi jb.baseUrl)
jB.config.segmentSiteRoot Stringa: La parte dell’url facente parte del siteUrl (vedi jb.siteUrl)
jB.config.sessionExpiredUrl Stringa: Il link al quale si viene reindirizzati in casi di sessione scaduta, usato per rilevare errori di sessione in caso di chiamata Ajax
jB.config.silentMode Booleano: Se TRUE abilita la visualizzazione di messaggi di debug sulla console del browser

Per chiarire come configurare il plugin e il significato dei parametri di seguito un esempio di configurazione (usato in questo sito):

jB.config = {
    segmentBaseRoot: "trylab",
    segmentSiteRoot: "trylab/[a-z]{2}",
    sessionExpiredUrl: "user/login",
    silentMode: false
};

Documentazione

Di seguito una breve documentazione delle funzionalità messe a disposizione da questo plugin:

jB.siteUrl()

Ritorna l’indirizzo web in base alle impostazioni fornite ed ai parametri della funzione,utile per generare redirect o simili direttamente da Javascript.

Parametri

Indirizzo [Opzionale] Stringa – La parte da accodare all’indirizzo del sito

Ritorna

La stringa composta da l’indirizzo del sito e dalla stringa aggiuntiva fornita eventualmente per parametro

 jB.baseUrl();    
// returns : "https://trylab.bettapro.com/it/"      

 jB.baseUrl('foo/site/url');  
// returns : "https://trylab.bettapro.com/it/foo/site/url"

jB.baseUrl()

Ritorna l’indirizzo web base del sito in base alle impostazioni fornite ed ai parametri della funzione, è essenzialmente una riscrittura dell’omonima funzione introdotta dal framework Codeigniter per poter accedere a risorse del server (immagini, file ..).

Parametri

Indirizzo [Opzionale] Stringa – La parte da accodare all’indirizzo del sito

Ritorna

La stringa composta da l’indirizzo del sito e dalla stringa aggiuntiva fornita eventualmente per parametro

 jB.baseUrl();    
// returns : "http://bettapro.ddns.net/trylab"      

 jB.baseUrl('/foo/base/url');  
// returns : "http://bettapro.ddns.net/trylab/foo/base/url"

jB.segment()

Ritorna il segmento n-esimo dell’url corrente, la numerazione inizia in base ai parametri di configurazioneforniti.

Parametri

Indice del segmento Intero – Il numero del segmento da ottenere, la numerazione parte da 1.

Ritorna

Una stringa contenente segmento n-esimo dell’url corrente, NULL altrimenti

 jB.segment();  
// returns : NULL  

 jB.segment(1);    
// returns : "it"      

 jB.segment(3);  
// returns : "jbutil"    

 jB.segment(0);  
// returns : NULL

jB.count()

Ritorna la lunghezza del parametro dato, la funzione modifica la metodologia di calcolo in base al tipo del parametro dato in ingresso

Parametri

L’elemento da contare __ – L’elemento di cui contare il contenuto.

Ritorna

Il Numero di elementi contenuti dall’oggetto dato in ingresso, in base alla tipologia la funzione conta

Oggetto Il numero di attributi posseduti dall’oggetto (non ereditati)
Array o altro Il numero di che lo compongono, equivale alla funzione “length()” di Javascript

 jB.count("jButil");  
// returns : 6  

 jB.count({j:1,b:2,u:3,t:4,i:5,l:6});    
// returns : 6      

 jB.count([1,2,3,4,5,6,7,8]);  
// returns : 8    

jB.count(jQuery.fn);  
// returns : 149

jB.wait()

Realizza un busy-waiting basandosi su una coandizione di termniazioni dell’attesa, gestisce anche timeout

Parametri

L’oggetto strutturato Oggetto – Un oggetto strutturato con i seguenti attributi:
- sync_name : [Opzionale] Il nome del busy-waiting (utile in fase di debug)
- sync_clock : [Opzionale] I millisecondi che deveno trascorrere tra due verifiche della condizione di uscita
- sync_function : Il nome del busy-waiting (utile in fase di debug)
- timeout : [Opzionale] Il numero massimo di millisecondi di attesa, oltre al quale scatta il timeout
- silent_mode : [Opzionale] Abilita i messaggi di diagnostica se TRUE
- done_callback : Il nome del busy-waiting (utile in fase di debug)
- timeout_callback : [Opzionale] La funzioen da eseguire in caso di timeout
- clock_callback : [Opzionale] La funzione da eseguire ad ogni controllo della condizione di uscita

Ritorna

Funzione senza valore di ritorno

jB.wait({
    sync_name : "foo_sync"  // use foo_sync to name this busy-waiting
    sync_function: function () {    //  wait util a random number is grater than 0.9
        return Math.random() > 0.9;
    },
    sync_clock: 50, // check the sync_function every 50ms
    timeout: 2000,  // stop after 2000 ms
    done_callback : function (){    // if done show an alert
        alert('Done!!');
    }
});

jB.fetch()

Effettua una chiamata xhr con possibilità di inviare dati (mediante post) e di gestire timeout

Parametri

L’oggetto strutturato Oggetto – Un oggetto strutturato con i seguenti attributi:
- call : Il path della chiamata xhr al quale verra aggiunto il siteUrl
- timeout : [Opzionale] Il numero massimo di millisecondi di attesa, oltre al quale scatta il timeout
- silent_mode : [Opzionale] Abilita i messaggi di diagnostica se TRUE
- data : [Opzionale] Un oggetto contenente i dati da inviare
- callback : La funzione da eseguire a risposta ricevuta o in caso di timeout, la funzione ha come paramentro di chiamata un oggetto con i seguenti dati
  - msg : L’eventuale messaggio descrittivo dell’errore
  - response : La risposta ricevura dal server o NULL
  - status : Lo stato della risposta (200 : ok, 504 : timeout)
  - elapsedTime : Il numero di millisecondi aspettati

Ritorna

Funzione senza valore di ritorno

jB.fetch({
    call: 'foo/xhr_foo_call',
    data: {
        foo : data      // send a pair foo=>data to the server
    },
    callback: function (r) {
        if (r.status === 200) {
            alert('Received an object with '+ jB.count(r.response) +' elements')
        }
    }
});

jB.param()

Questa funzione deriva dall’implementazione dell’omonima funzione del framework jQuery, essenzialmentequesta funzione serializza un oggetti elencando gli attributi dell’oggetto come chiave-valore.

Si usa generalmente quando si deve generare richieste Ajax o URL con paramentti.

Parametri

L’oggetto Oggetto – L’oggetto da serializzare.

Ritorna

Una stringa contentente tutte le coppie chiave-valore degli attrbiuti dell’oggetto ( es “a=1&b=2&c=3”)

 jB.param({j:1,b:2,u:3});    
// returns : j=1&b=2&u=3     

 jB.param({try:'lab'});  
// returns : try=lab

jB.extend()

Questa funzione deriva dall’implementazione dell’omonima funzione del framework jQuery, essenzialmentequesta funzione fonde 2 o più oggetti, inserendo tutte le proprietà degli oggetti passati nel primo fornito.

Parametri

La funzione opera in 2 modi in base alla tipologia dei parametri forniti, la modalità 2 si usa essenzialmente quando si deve fare una fusione ricorsiva degli oggetti

Modalità 1

L’oggetto target Oggetto – L’oggetto in cui inserite tutte le proprietà degli altri oggetti dati come parametro.
Oggetto 1 Oggetto – Il primo oggetto da fondere con l’oggetto target.
..
Oggetto n Oggetto – L’oggetto n-esimo da fondere con l’oggetto target.

Modalità 2

Tipo di merge Booleano – Se TRUE il merge diventa ricorsivo copiando i “sotto-oggetti”.
L’oggetto target Oggetto – L’oggetto in cui inserite tutte le proprietà degli altri oggetti dati come parametro.
Oggetto 1 Oggetto – Il primo oggetto da fondere con l’oggetto target.
..
Oggetto n Oggetto – L’oggetto n-esimo da fondere con l’oggetto target.

Ritorna

jB.extend({}, {j:1,b:2}, {u:3});  
// target = {j:1,b:2,u:3}
// returns : {j:1,b:2,u:3}  

 jB.extend({j:1,b:2}, {u:3});  
// target = {j:1,b:2,u:3}
// returns : {j:1,b:2,u:3}     

 jB.extend({b:2}, {u:3, j:{a:1,f:2}});  
// target = {j:{a:1,f:2},b:2,u:3}
// returns : {j:{a:1,f:2},b:2,u:3}   j is the same as before

 jB.extend(true, {b:2}, {u:3, j:{a:1,f:2}});  
// target = {j:{a:1,f:2},b:2,u:3}
// returns : {j:{a:1,f:2},b:2,u:3}   j is a 'new' copy

jB.parseNum()

Questa funzione estrae un numero da una stringa, risulta essere più flessibile delle funzioni nativedi javascript parseInt e parseFloat.

Parametri

La funzione accetta un’unico parametro

La stringa Stringa – La stringa da utilizzare per estrarre il numero.

Ritorna

Il numero (float o intero) estratto, false se non ci sono numeri da estrarre.

 jB.parseNum("12.0");  
// returns : 12.0  
jB.parseNum("12.034,99");  
// returns : 12034.99

jB.isNumeric()

Questa funzione verifica che il parametro fornito in input sia un numero.

Parametri

La funzione accetta un parametro

Parametro – L’entità da controllare.

Ritorna

True se il parametro è numerico, false altrimenti.

 jB.isNumeric("12.0");  
// returns : true  
jB.isNumeric("12a3");  
// returns : false

jB.round()

Questa funzione arrotonda un numero usando un dato numero di cefre decimali.

Parametri

La funzione accetta due parametri

Valore Intero – Il numero da arrotondare.
Cifre decimali [Opzionale] Intero – Il numero di cifre decimali da mantenere, se non specificato viene impostato a 2.

Ritorna

Il numero arrotondato.

jB.round(12.365, 2);  
// returns : 12.37  
jB.round(99.658);  
// returns : 99.66

jB.parseDate()

Questa funzione estra una data da una stringa, estendendo i formati di dati supportati dala funzione nativa di javascript.

Parametri

La funzione accetta un parametro

La data Data – La stringa contentente la data.

Ritorna

Un oggetto Date se la funzione ha rilavato una data valida, null altrimenti.

 jB.parseDate("12 a");  
// returns : null  
jB.parseDate("21/08/1991");  
// returns : Date 21/08/1991

jB.formatDate()

Questa funzione crea una stringa descrittiva di una data basandosi sul formato dato in input.

Parametri

La funzione accetta due parametri in ingresso

Formato Stringa – Il formato “guida” per stampare la data. La stringa contiene delle parole chiaveche specificano dove e che valore inserire. Le parole chiave supportate sono:
- YYYY L’anno (4 cifre)
- mm Il mese (2 cifre)
- dd Il giorno (2 cifre)
- HH
- ii I minuti
- ss I secondi
Data Data – La data da stampare.

Ritorna

La stringa in base al formato fornito.

jB.formatDate('YYYY mm dd',Date('21/08/1991'));  
// returns : '1991 08 21'  
 jB.formatDate('YYYY',Date('21/08/1991'));  
// returns : '1991'

jB.formSubmit()

Questa funzione simula un submit di un form con metodo POST.

Parametri:

Data un oggetto contenente i valori da inviare nella richiesta POST
Url l’indirizzo alla qualle inviare la richiesta POST (verrà applicata la funzione jB.siteUrl su questo parametro)

jB.formSubmit({
   name : 'user',
   animals : ['cat', 'dog', 'lion']
}, 'my_url/method');
// send a POST request to https://trylab.bettapro.com/it/my_url/method containing
// name = 'user'
// animals[] = 'cat'
// animals[] = 'dog'
// animals[] = 'lion'

Download

Il plugin viene sviluppato e mantenuto su GitHub.

GITHUB