Libreria AJAX

Introduzione

La libreria AJAX è basata su prototype.js.

E' costituita dai seguenti file che sono caricati automaticamente nel browser tramite il token <script adx="ALIBJS"></script>:

prototype.js

Libreria prototype versione 1.6.0.3

XtendAjax.js

Gestione delle richieste AJAX a destinazione del server XTEND

XtendAjaxFlash.js

Gestione delle richieste AJAX per i componenti FLASH X3

XtendAjaxMsgs.js

Gestione delle richieste AJAX per la visualizzazione dei messaggi utente nel browser

Tramite la funzione JavaScriptxtdAlert(messId,p1,P2,P3,P4)

XtendAjaxScripts.js

Gestione delle richieste AJAX per il richiamo degli script server

XtendAjaxWsvc.js

Gestione delle richieste AJAX per la chiamata delle interfacce XTEND (web service X3)

XtendAjaxDom.js

Strumento per la gestione di un DOM XML

XtendAjaxUtils.js

Strumenti diversi

XTENDAJAX.request

Principio

La chiamata della richiesta AJAX è asincrona, che significa che dopo l'invio della richiesta HTTP verso il server il programma chiamante non ottiene nessuna risposta dal server.

La risposta arriva nell'arco di un "certo tempo" che non si può gestire.

Solo quando l'oggetto HTTPREQUEST riceve la risposta viene chiamata una funzione JavaScript CallBack per elaborare il risultato.

In standard la funzione CallBack contiene solo la risposta HTTP come parametro e non permette di ritrovare il contesto di chiamata della richiesta.

La classe XTENDAJAX.request della libreria XtendAjax.js implementa la classe Ajax.Request della libreria prototype con lo scopo di facilitarne l'utilizzo e di permettere l'accesso al contesto di chiamata nella funzione CallBack.

XTENDAJAX.request=Class.create(Ajax.Request,{
    initialize: funzione(aCaller,url,aContentType,aReturnedType,params)
    {   
        // Programma specifico
        // Chiamata della richiesta Ajax di prototype.js
        $super(url,options);
    },

aCaller

Oggetto chiamante (vedere § seguente)

url

Url di chiamata del web service REST XTEND

aContentType

ContentType dei dati inviati - null autorizzato

• application/xml
  -> params contiene una String XML
• application/json
  -> params contiene una String JSON
• application/x-www-form-urlencoded
  -> params contiene un Hash ($H prototype.js)

aReturnedType

ContentType dei dati ottenuti - null autorizzato

params

Dati inviati nel corpo della richiesta - null autorizzato

Tutte le classi e funzioni sono collegate all'oggetto XTENDAJAX.

Oggetto chiamante

Si tratta dell'oggetto che chiama la richiesta e che gestisce il contesto di chiamata di cui si avrà bisogno per elaborare la risposta.

Questo oggetto deve implementare i metodi seguenti per elaborare i vari stati della risposta:

    //------------------------------------------------
    //Chiamata se HTTP status è uguale = 200
    //risposta: Classe Ajax.Response
    onSuccess:function(response){
   
    },
    //------------------------------------------------
    //Chiamata se HTTP status è diverso da 200
    //request   : Classe Ajax.Request
    //exception : String o  classe Error
    onFailure:function(request, exception){
   
    },
    //------------------------------------------------
    //Chiamata su eccezione JavaScript
    //request   : Classe Ajax.Request
    onException :function(response,headerJSON){
   
    }

Le funzioni onFailure e onException sono facoltative.

Se l'oggetto chiamante non le implementa, saranno richiamate le funzioni di visualizzazione XTENDAJAX.displayException e XTENDAJAX.displayFailure.

Esempio

L'esempio qui in basso richiama il web service REST identificato dal parametro aURL con i dati aData e visualizza la risposta.

var wClassCaller=Class.create({
    onSuccess:function(response){
        response.xtdDisplay();
    },
    call:function(aURL,aData){
        new XTENDAJAX.request(this,aURL,null,null,aData);
    }
});
var wURL="http://ecfdalbopro:28980/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/XTDLOGIN";
var wInput={
    _JSONOPT:{OPTIONS:"nogroups"},
    AXUSERCODE:"DIS001",
    AXPWD:"adonix"
};
new wClassCaller().call(wURL,wInput);

Nella pratica si utilizzano le classi della classe XTENDWSVC.classCallerSpg della libreria XtendAjaxWsvc.js che facilitano il calcolo dell'url e la manipolazione dei dati.

Oggetto 'response'

Il parametro response diventa una istanza a partire dalla classe Ajax.response a cui si aggiungono i metodi specifici per elaborare la risposta del server XTEND (XTENDAJAX.xtdExtendResponse).

{
    //-------------------------------------------------
    // Visualizza il contenuto della risposta in formato testo (XTENDAJAX.msgBox)
    xtdDisplay:function(),
    //-------------------------------------------------
    // Riquadro che contiene i messaggi di errore
    xtdMsgErr:,
    // Restituisce true se la risposta comporta un errore applicativo X3
    xtdHasX3Error:function(),
    //-------------------------------------------------
    // Riquadro che contiene messaggi warning
    xtdMsgWarning:,
    //-------------------------------------------------
    // Riquadro che contiene i messaggi di informazione
    xtdMsgInfo:,
    //-------------------------------------------------
    // Riquadro che contiene tutti i messaggi
    xtdMsgAll:,
    //-------------------------------------------------
    // ContentType della risposta
    xtdContentType:,
    //-------------------------------------------------
    // True se ContentType=text/plain
    xtdIsText:function(),
    //-------------------------------------------------
    // True se ContentType=text/html
    xtdIsHtml:function(),
    //-------------------------------------------------
    // True se ContentType=application/xml
    xtdIsXml:function(),
    //-------------------------------------------------
    // True se ContentType=application/json
    xtdIsJson:function(),
   
    /*------------------ Réponse XML ------------------*/
    //Valuta la risposta e restituisce un DOM XML (vedere XtendAjaxDom.js)
    xtdEvalXML,
    //Contiene il DOM XML creato da xtdEvalXML
    xtdResponseXML:,
   
    /*------------------ Risposta JSON------------------*/
    //Valuta la risposta e restituisce un oggetto JSON che rappresenta la risposta
    xtdEvalJSON:function(),
    //Contiene l'oggetto JSON creato da xtdEvalJSON
    xtdResponseJSON:,
    //Restituisce un Hash ($H) creato a partire da un riquadro di chiavi e di valori
    xtdHash:function(aKeyArray,aValArray),
   
    /*------- Risposta WEB SERVICE SOTTO-PROGRAMMA -------*/
    //Valuta la risposta con un sotto-programma
    //-> Aggiunge i metodi specifici
    xtdEvalJSONSpg:function(),
    //Restituisce il valore del parametro AXPAR
    AXPAR:function(aCode),
    //Restituisce il valore del parametro AXPAR come un intero
    AXPARInt:function(aCode,aDefValue),
   
    /*------ Risposta SOTTO-PROGRAMMA ACCESSO DATI -------*/    
    //Valuta la risposta ad un web service sotto-programma accesso dati
    //-> Aggiunge i metodi specifici
    xtdEvalJSONSpgAccess:function(),
    //Numero di record richiesti
    askedRecords:function(),
    //Numero totale di record
    totalRecords:function(),
    //Numero record ottenuti
    returnedRecords:function(),
    //Range (1-N) del primo record
    startRank:function(),
    //True se esistono dei record successivi - False se paginazione terminata
    hasNext:function(),
   
    /*--------- Risposta WEB SERVICE OGGETTO X3 ----------*/
    // Valuta la risposta ad un web service oggetto X3
    //-> Aggiunge i metodi specifici
    xtdEvalJSONObject:function(),
    //Gruppo tecnico ADXTEC
    adxADXTEC:function(aField),
    //Timestamp dell'oggetto X3
    adxTimeStamp:function(),
    //UserCode X3 che ha modificato per ultimo l'oggetto
    adxUser:function(),
}

Web service interfaccia

Introduzione

La libreria XtendAjaxWsvc.js mette a disposizione dello sviluppatore un insieme di classi per facilitare la chiamata dei web service REST di XTEND di tipo interfaccia.

La richiesta AJAX attiva l'esecuzione di un web service identificato dalla scheda interfaccia ed elabora direttamente il risultato. Il server XTEND chiama solo il web service X3 e restituisce la risposta.

Tutte le classi e le funzioni sono collegate all'oggetto XTENDWSVC

Strumenti

/*----------------- TEST -----------------*/
//Richiama l'interfaccia aInterfaceId con i dati aXmlData
// Visualizza il risultato
testSpgXML:function(aInterfaceId,aXmlData),
//---------------------------------------------
//Richiama l'interfaccia aInterfaceId con i dati aJSONData
// Visualizza il risultato
testSpgJSON:function(aInterfaceId,aJSONData),

/*----------------- CALL STATICA -----------------*/
//Richiama l'interfaccia sotto-programma aInterfaceId con i dati aData
//Le funzioni CallBack statiche sono passate nel parametro
runSpg:function(aInterfaceId,aData,onSuccess,onFailure),
//---------------------------------------------
//Idem runSpg con i dati JSON in ritorno
runSpgJSON:function(aInterfaceId,aData,onSuccess,onFailure),
//---------------------------------------------
//Idem runSpg con i dati XML in ritorno
runSpgXML:function(aInterfaceId,aData,onSuccess,onFailure),

/*----------------- PARAMETRI DI CHIAMATA -----------------*/
//Restituisce un oggetto parametro di base XTENDWSVC.classParam
//aJSONOptions : opzioni JSON (facoltativa)
newParam:function (aJSONOptions),
//---------------------------------------------
//Restituisce un oggetto parametro per la chiamata di un web service oggetto X3
//Classe XTENDWSVC.newParamXtdObject
//aTimeStampX3: il timestamp X3 dell'oggetto (facoltativo)
newParamXtdObject:function (aTimeStampX3,aJSONOptions),
//---------------------------------------------
//Restituisce un oggetto parametro per la chiamata di un web service sotto-programma
//Classe XTENDWSVC.classParamXtdSpg
newParamXtdSpg:function (aJSONOptions),
//---------------------------------------------
//Restituisce un oggetto parametro per la chiamata di un sotto-programma 'accesso dati'
//Classe XTENDWSVC.classParamXtdSpgAccess
//aNbLines : numero massimo di record richiesti
    //aStartAt : range del 1° record
newParamXtdSpgAccess:function (aNbLines,aStartAt,aJSONOptions),
//---------------------------------------------
//Restituisce un oggetto parametro per la chiamata di una lista di selezione oggetto X3
//Classe Hash (riquadro chiave/valore)
//aNbLinesReturned : numero righe richieste
newParamQuery:function(aNbLinesReturned,aJSONOPtions),
//---------------------------------------------
//Restituisce un oggetto parametro di tipo chiave
//Classe Hash (riquadro chiave/valore)
newParamRead:function(aJSONOPtions),
//---------------------------------------------
//Verifica che aHash sia il parametro per una query
//Presenza della chiave "_COUNT" che contiene il numero di righe richieste
checkQueryParam:function(aHash,aReturnedCount),

Classi parametri

XTENDWSVC.classParam

Classe di base dei parametri.

XTENDWSVC.classParam=Class.create({
    /---------------------------------------
    //aJSONOptions: Opzioni JSON
    initialize: function(aJSONOptions),
    /---------------------------------------
    //Restituisce le opzioni JSON
    option:function(),
    /---------------------------------------
    //Aggiunge un parametro aCode con il valore aCode
    add:function(aCode,aValue),
    /---------------------------------------
    //Restituisce il valore del parametro aCode
    get:function(aCode)
)}

XTENDWSVC.classParamXtdSpg

Classe di parametro di chiamata di un web service sotto-programma che eredita da XTENDWSVC.classParam.

XTENDWSVC.classParamXtdSpg=Class.create(XTENDWSVC.classParam,{
    /---------------------------------------
    //aJSONOption: Opzioni JSON
    initialize: function(OptionsJSON),
    /---------------------------------------
    //Aggiunta di un parametro AXPAR
    addAXPAR:function(aCode,aValue)    
});

XTENDWSVC.classParamXtdSpgAccess

Classe di parametro di chiamata di un web service sotto-programma di tipo 'Accesso dati' che eredita da XTENDWSVC.classParam.

XTENDWSVC.classParamXtdSpg=Class.create(XTENDWSVC.classParam,{
    /---------------------------------------
    //aJSONOption: Opzioni JSON
    //aNbLines: numero massimo di record richiesti
    //aStartAt : range del 1°record
    //Aggiorna i parametri '$REC_STARTAT','$TOTAL_COUNT','$RET_COUNT','$HAS_NEXT'
    initialize: function(aNbLines,aStartAt,aJSONOptions),
});

XTENDWSVC.classParamObject

Classe di parametro di chiamata di un web service oggetto X3 che eredita da XTENDWSVC.classParam.

XTENDWSVC.classParamXtdSpg=Class.create(XTENDWSVC.classParam,{
    /---------------------------------------
    //aJSONOptions: Opzioni JSON
    //aTimeStampX3: String - TimeStamp dell'oggetto X3 (può essere null o vuoto)
    //Aggiunge il parametro WW_MODSTAMP nel gruppo ADXTEC con il valore  aTimeStamp
    initialize: function(aTimeStampX3,aJSONOptions),
});

Classe XTENDWSVC.classJsonOpt

Classe che rappresenta le opzioni JSON.

//---------------------------------------
//Attiva l'opzione noGroups
noGroups:function(),
//---------------------------------------
//Attiva l'opzione noRows
noRows:function(),
//---------------------------------------
//Attiva l'opzione noLabels
noLabels:function(),
//---------------------------------------
//Attiva l'opzione noClobs
noClobs:function(),
/---------------------------------------
//Aggiorna l'elenco dei gruppi da escludere
//aValue : String or Array of string
excludeGrp:function(aValue),
//---------------------------------------
//Aggiorna l'elenco dei gruppi da includere
includeGrp:function(aValue),
//---------------------------------------
//Aggiorna l'elenco dei campi da escludere
excludeFld:function(aValue),
//---------------------------------------
//Aggiorna l'elenco dei campi da includere
includeFld:function(aValue),

/*------------- ESEMPIO -------------*/
var wOpts=new XTENDWSVC.classJsonOpt().noGroups().includeFld(["SOHNUM""ITMREF","QTY"]);

Classe XTENDWSVC.classCaller

Si tratta della classe di base usata per richiamare un web service REST.

Di default questa classe non permette di postare più richieste simultaneamente e blocca i tentativi di chiamate multiple.

/*---------------- METODI PRINCIPALI ----------------*/
//Costruttore
//aInterfaceId : ID dell'interfaccia XTEND
//Facoltativo: è possibile passare le funzioni CallBack statiche nei parametri
//               se non implementata nella classe
//               -> aInterfaceId,onSuccess,onFailure,onException
initialize:function(aInterfaceId),
//-------------------------------------------------------
//Verifica se la chiamata è in corso e attiva l'invio della richiesta
//aUrl        : Url del service
//aData       : Dati
//aContenType: ContentType
exec:function(aUrl,aData ,aContenType),

/*-------- METODO CALLBACK DA IMPLEMENTARE OBBLIGATORIAMENTE ----------*/
// HTTP STATUS=200
// !! Il metodo figlie deve richiamare $super(response) per posizionare
//    il flag di chiamata a false
onSuccess:function(response),

/*--------- METODO CALLBACK EVENTUALMENTE DA IMPLEMENTARE ----------*/
// ECCEZIONE JAVASCRIPT
//Di default questo metodo visualizza l'eccezione
// !! Il metodo figlie deve richiamare $super(request,exception,true)
//    per posizionare il flag di chiamata a false senza visualizzare il risultato
onException:function(request,exception,aIsOverriden),
//-------------------------------------------------------
// HTTP STATUS!=200
//Di default questo metodo visualizza la causa dell'errore
// !! Il metodo figlie deve chiamare $super(request,headerJSON,true)
//    per posizionare il flag di chiamata a false senza visualizzare il risultato
onFailure:function(response,headerJSON,aIsOverriden),

/*--------------------- FORMATI --------------------*/
//Fissa application/json come tipo di dati restituiti
//Tipo di default
setReturnJSON:function(),
//-------------------------------------------------------
//Fissa application/xml come tipo di dati restituiti
setReturnXML:function(),
//-------------------------------------------------------
//True se dati XML restituiti
returnXML:function(),
//-------------------------------------------------------
//True se dati JSON restituiti
returnJSON:function(),

/*--------------------- DIVERSI --------------------*/
//posta realmente la richiesta verso il server se non vi sono chiamate in corso
sendRequest:function(aUrl,aDataObject,aContenType)
//-------------------------------------------------------
//Restituisce l'id dell'interfaccia
getId:function(),

/*------------- GESTIONE CHIAMATE MULTIPLE -------------*/
//Da implementare se si vogliono sbloccare le chiamate multiple
//aBusy : True se chiamata in corso
//Restituisce true per autorizzare la chiamata del web service
doSendRequest:function(aBusy),
//-------------------------------------------------------
//Aggiorna il flag di occupazione
setBusy:function(aYes),
//-------------------------------------------------------
//True se chiamata in corso
isBusy:function()

Classe XTENDWSVC.classCallerSpg

Si tratta della classe di base utilizzata per richiamare un web service REST sotto-programma.

XTENDWSVC.classCallerSpg=Class.create(XTENDWSVC.classCaller,{
    //-------------------------------------------------------
    //Costruttore
    initialize:function(aInterfaceId),
    //-------------------------------------------------------
    //Esegue la richiesta con i dati aData
    //Valore autorizzato per aData
    // -null o undefined -> this.exec()
    // -String -> this.exec(aString,'text/plain')
    // -Hash   -> this.runFORMENCODED(aData)
    // -Altro  -> this.runJSON(Object.toJSON(aData))
    run:function(aData),
    //-------------------------------------------------------
    //Esegue la richiesta con i dati XML aXML
    runXML:function(aXML),
    //-------------------------------------------------------
    //Esegue la richiesta con i dati JSON aJSON
    // JSON : String JSON o oggetto JavaScript (classe parametro)
    runJSON:function(aJSON),   
    //-------------------------------------------------------
    //Esegue la richiesta con il riquadro delle chiavi/valori aHash
    //aHash rappresenta il contenuto di un formulario <form>
    runFORMENCODED:function(aHash),
});

Esempio

L'esempio qui in basso chiama l'interfaccia XTDLOGIN del sito corrente e visualizza la risposta.

Call Sotto-Programma

var wClassCaller=Class.create(XTENDWSVC.classCallerSpg,{
   //Costruttore facoltativo se non vi sono altri costruttori facoltativi diversi da aInterfaceId
   initialize:function($super,aInterfaceId){
      $super(aInterfaceId);
   },
   //Metodo obbligatorio per elaborare la risposta
   onSuccess:function(response){
      response.xtdDisplay();
   }
});
var wJSONOpts=new XTENDWSVC.classJsonOpt().noGroups();
var wParams=new XTENDWSVC.classParamXtdSpg(wJSONOpts);
wParams.add("AXUSERCODE","DIS001");
wParams.add("AXPWD","adonix");
new wClassCaller("XTDLOGIN").run(wParams);

Risultato

URL :
http://ecfdalbopro:28980/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/XTDLOGIN

Content-Type :
application/json;charset=utf-8

X3 INFORMAZIONE MESSAGGI:
Si è connessi con il codice utente DIS001

{
"AXUSERCODE":"DIS001",
"AXPWD":"adonix",
"AXUSERPROF":"B2B",
"AX3SOL":["SOLPAIE","X3V5","XTENDV2"],
"AX3FLDR":["PAIE","X3TESTV5","DEMOFRA"],
"AX3LANG":["FRA","FRA","FRA"],
"AX3USER":["XTEND","JPJ1","OG"],
"AX3PWD":["adonix","",""],
"AXLOGCOD":["NAME","FIRSTNAME","EMAIL","PHONE"],
"AXLOGVAL":["DAL BO","Frédéric","frdal@sage.com","00102030405"],
"SHIPADR1":["Sage Lyon new","Sage MGE","Sage PARIS"],
"SHIPCITY":["LYON","Echirolles","PARIS"],
"SHIPZIP":["69443","38130","75834"]
}

Classe XTENDWSVC.classCallerObject

Si tratta della classe di base utilizzata per richiamare un web service REST oggetto X3.

XTENDWSVC.classCallerObject=Class.create(XTENDWSVC.classCaller,{
    //-------------------------------------------------------
    //Costruttore
    initialize:function(aInterfaceId),
    //-------------------------------------------------------
    //Metodo save
    //aData : Dati in formato JSON o XML
    actCreate:function(aData),
    //-------------------------------------------------------
    //Metodo  Read
    //aHashKeys : Hash che contiene le chiavi dell'oggetto
    actRead:function(aHashKeys),
    //-------------------------------------------------------
    //Metodo Delete
    //aHashKeys : Hash che contiene le chiavi dell'oggetto
    actDelete:function(aHashKeys),
    //-------------------------------------------------------
    //Metodo Modify
    //aHashKeys : Hash che contiene le chiavi dell'oggetto
    //aData     : Dati in formato JSON o XML
    actUpdate:function(aHashKeys,aData),
    //-------------------------------------------------------
    //Azione di codice aCode
    //aCode     : Codice dell'azione
    //aHashKeys : Hash che contiene le chiavi dell'oggetto
    actOtherKey:function(aCode,aHashKeys),
    //-------------------------------------------------------
    //Azione di codice aCode
    //aCode     : Codice dell'azione
    //aData     : Dati in formato JSON o XML
    actOtherData:function(aCode,aData),
    //-------------------------------------------------------
    //Action query lista di selezione
    //aHashKeys      : Hash che contiene le chiavi per la selezione
    //aReturnedCount : Opzionale - Numero di righe richieste
    actQuery:function(aHashKeys,aReturnedCount),
});

Esempio

L'esempio qui in basso chiama l'interfaccia oggetto X3 OBJAYZ (oggetto AYZ) del sito corrente durante la creazione e visualizza la risposta.

Call Oggetto

var wClassCaller=Class.create(XTENDWSVC.classCallerObject,{
  onSuccess:function(response){
    response.xtdDisplay();
  }
});
var wJSONOpts=new XTENDWSVC.classJsonOpt().noGroups();
var wParams=new XTENDWSVC.classParamObject(null,wJSONOpts);
wParams.add("TTL","Titolo del formulario");
wParams.add("MAICOD","frdal@sage.com");
wParams.add("CMT","Commento");
new wClassCaller("OBJAYZ").actCreate(wParams);

Risultato

URL :
http://ecfdalbopro:28980/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/S

Content-Type :
application/json;charset=utf-8

X3 INFORMATION MESSAGES :
Formulario creato

{
"FRMCOD":"0902000005",
"FCYCOD":"FDBTEST",
"ZFCYCOD":"Sito di test fdalbo",
"TYP":"OTH",
"ZTYP":"Diversi",
"STATUT":"1",
"STATUT_LBL":"Da elaborare",
"TTL":"Titolo del formulario",
"MAICOD":"frdal@sage.com",
"CREDAT":"20090227",
"CREHEURE":"184431",
"CMT":"Commento",
"PARCOD":[],
"PARVAL":[],
"WW_MODSTAMP":"000000000000",
"WW_MODUSER":""
}