AJAX Library

Introduction

The AJAX library is based on prototype.js.

It is made of the following files which are loaded automatically in the browser via the following token <script adx="ALIBJS"></script>:

prototype.js

Library -prototype version 1.6.0.3

XtendAjax.js

Management of AJAX requests to the XTEND server

XtendAjaxFlash.js

Management of AJAX requests for FLASH X3 components

XtendAjaxMsgs.js

Management of AJAX requests for the display of user messages in the browser

Via JavaScript function xtdAlert(messId,p1,P2,P3,P4)

XtendAjaxScripts.js

Management of AJAX request for the call to server scripts

XtendAjaxWsvc.js

Management of AJAX requests for the call to XTEND interfaces (X3 web services)

XtendAjaxDom.js

Utility for the management of a DOM XML

XtendAjaxUtils.js

Miscellaneous utility

XTENDAJAX.request

Principle

The call to AJAX requests is asynchronous. Once the HHTP request is sent to the server, the calling program does not obtain a response from the server.

The response comes after a "certain amount of time" which cannot be controlled.

Only the HTTPREQUEST object receives the response called a JavaScript CallBack function in order to deal with the result.

In standard, the CallBack function does not contain the HTTP response as a setup and cannot be used to find the call context of the request.

The XTENDAJAX.request class of the XtendAjax.js library overloads the Ajax.Request class of the prototype library in order to provide easier use and to access the context of the CallBack function.

XTENDAJAX.request=Class.create(Ajax.Request,{
    initialize: function(aCaller,url,aContentType,aReturnedType,setups)
    {   
        // Specific process
        // Call to the prototype.js Ajax request
        $super(url,options);
    },

aCaller

Calling object (see next §)

url

REST XTEND web service url call

aContentType

ContentType of sent data - null autorized

• application/xml
  -> setups contains an XML string
• application/json
  -> setups contains a JSON string
• application/x-www-form-urlencoded
  -> setups contain an Hash ($H prototype.js)

aReturnedType

ContentType of returned data - null autorized

setups

Data sent in the request body - null authorized

All class and functions are assigned to the XTENDAJAX object.

Calling object

It's the object which call upon the request and manages the call context which will be needed in order to deal with the response.

This object must implement the following methods in order to process the various reports of the response:

    //------------------------------------------------
    //Appel si HTTP status is equal to 200
    //response : Classe Ajax.Response
    onSuccess:function(response){
   
    },
    //------------------------------------------------
    //Call if HTTP status is diffrent than 200
    //request   : Class Ajax.Request
    //exception: String ou  classe Error
    onFailure:function(request, exception){
   
    },
    //------------------------------------------------
    //Call on JavaScript exception
    //request   : Classe Ajax.Request
    onException :function(response,headerJSON){
   
    }

The onFailure and onException functions are optional.

If the calling object does not apply them, the XTENDAJAX.displayException and XTENDAJAX.displayFailure display functions will be called.

For instance

The following example illustrates the call to the REST web service which is identified by the the aURL setup with the aData and displays the answer.

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);

The user actually uses classes from the XTENDWSVC.classCallerSpg class, which is from the XtendAjaxWsvc.js librarty which makes it easier to calculate the url and to use data.

'Response' object

The response setup is initialized from the Ajax.response class to which specific methods have been added in order to handle the XTEND server response (XTENDAJAX.xtdExtendResponse).

{
    //-------------------------------------------------
    // Displays the content of the response with the text format (XTENDAJAX.msgBox)
    xtdDisplay:function(),
    //-------------------------------------------------
    // Grid which contains the error messages
    xtdMsgErr:,
    // True resent if the answer contain an X3 application error
    xtdHasX3Error:function(),
    //-------------------------------------------------
    // Grid which contains warning messages
    xtdMsgWarning:,
    //-------------------------------------------------
    // Grid which contains informative messages
    xtdMsgInfo:,
    //-------------------------------------------------
    // Grid which contains all messages
    xtdMsgAll:,
    //-------------------------------------------------
    // ContenType of the response
    xtdContentType:,
    //-------------------------------------------------
    // True if ContentType=text/plain
    xtdIsText:function(),
    //-------------------------------------------------
    // True if ContentType=text/html
    xtdIsHtml:function(),
    //-------------------------------------------------
    // True if ContentType=application/xml
    xtdIsXml:function(),
    //-------------------------------------------------
    // True if ContentType=application/json
    xtdIsJson:function(),
   
    /*------------------ XML response------------------*/
    //Evaluates the responses and send a DOM XML (see XtendAjaxDom.js)
    xtdEvalXML,
    //Contains the DOM XML created by xtdEvalXML
    xtdResponseXML:,
   
    /*------------------ JSON response---------*/
    //Evaluates the response and sends a JSON object which represents the response
    xtdEvalJSON:function(),
    //Contains the JSON response created by xtdEvalJSON
    xtdResponseJSON:,
    //Resends an Hash ($H) created from the key and value grid
    xtdHash:function(aKeyArray,aValArray),
   
    /*------- SUBPROGRAM WEBSERVICE response-------*/
    //Evaluates the response to a subprogram
    //-> Adds specific methods
    xtdEvalJSONSpg:function(),
    //Resends the AXPAR setup value
    AXPAR:function(aCode),
    //Resends the AXPAR setup value as an integrer
    AXPARInt:function(aCode,aDefValue),
   
    /*------ DATA ACCESS SUBPROGRAM response -------*/    
    //Evaluates the response to a data access subprogram webservice
    //-> Adds specific methods
    xtdEvalJSONSpgAccess:function(),
    //Number of requested records
    askedRecords:function(),
    //Total number of records
    totalRecords:function(),
    //Number of resent records
    returnedRecords:function(),
    //Rang (1-N) of the first record
    startRank:function(),
    //True if there are other records after - False if it is the last page
    hasNext:function(),
   
    /*--------- X3 OBJECT WEB SERVICE ----------*/
    //Evaluates the response to a X3 object web service
    //-> Adds specific methods
    xtdEvalJSONObject:function(),
    //ADXTEC technical groups
    adxADXTEC:function(aField),
    //X3 object Timestamp
    adxTimeStamp:function(),
    //UserCode X3 which has last modified the object
    adxUser:function(),
}

Web services interface

Introduction

The XtendAjaxWsvc.js library provides a range of interface classes in order to facilitate the call to the REST web services from XTEND.

The AJAX request triggers the execution of a web service identified by the interface record and processes the resut directly. The XTEND server only calls the X3 web service and sends the response again.

All class and functions are assigned to the XTENDWSVC object.

Utilities

/*----------------- TESTS -----------------*/
//Calls the aInterfaceId interface with the aXmlData data
// Displays the result
testSpgXML:function(aInterfaceId,aXmlData),
//---------------------------------------------
//Calls the aInterfaceId interface with the aJSONData data
// Displays the result
testSpgJSON:function(aInterfaceId,aJSONData),

/*----------------- STATIC CALL -----------------*/
//Calls the aInterfaceId sub-program interface with the data
//The statistics CallBack functions are entered as setup
runSpg:function(aInterfaceId,aData,onSuccess,onFailure),
//---------------------------------------------
//Idem runSpg with JSON data in return
runSpgJSON:function(aInterfaceId,aData,onSuccess,onFailure),
//---------------------------------------------
//Idem runSpg with XML data in return
runSpgXML:function(aInterfaceId,aData,onSuccess,onFailure),

/*----------------- CALL SETUPS-----------------*/
//Resends a XTENDWSVC.classParam base setup object
//aJSONOptions: JSON options (optional)
newParam:function (aJSONOptions),
//---------------------------------------------
//Resends a setup object for the call to an X3 object web service
//Classe XTENDWSVC.newParamXtdObject
//aTimeStampX3: the X3 timestamp of the objects (optional)
newParamXtdObject:function (aTimeStampX3,aJSONOptions),
//---------------------------------------------
//Resends a setup object for the call to a sub-program web service
//Classe XTENDWSVC.classParamXtdSpg
newParamXtdSpg:function (aJSONOptions),
//---------------------------------------------
//Resends a setup object for the call to a 'data access' sub-program
//Classe XTENDWSVC.classParamXtdSpgAccess
//aNbLines: maximum number of requested records
//aStartAt: 1st record rank
newParamXtdSpgAccess:function (aNbLines,aStartAt,aJSONOptions),
//---------------------------------------------
//Resends a setup object for the call to an X3 object quick select list
//Classe Hash (key/value grid)
//aNbLinesReturned: number of requested lines
newParamQuery:function(aNbLinesReturned,aJSONOPtions),
//---------------------------------------------
//Resends a key setup object
//Classe Hash (key/value grid)
newParamRead:function(aJSONOPtions),
//---------------------------------------------
//Checks if aHash is a setup for query
//Presence of the "_COUNT" key which contains the number of requested lines
checkQueryParam:function(aHash,aReturnedCount),

Setup classes

XTENDWSVC.classParam

Setups base class

XTENDWSVC.classParam=Class.create({
    /---------------------------------------
    //aJSONOptions: JSON options
    initialize: function(aJSONOptions),
    /---------------------------------------
    //Resendst the JSON options
    options:function(),
    /---------------------------------------
    //Adds an aCode setup with the value: aCode
    add:function(aCode,aValue),
    /---------------------------------------
    //Resends the aCode setup value
    get:function(aCode)
)}

XTENDWSVC.classParamXtdSpg

Class of a sup-program web service call setup which has XTENDWSVC.classParam.

XTENDWSVC.classParamXtdSpg=Class.create(XTENDWSVC.classParam,{
    /---------------------------------------
    //aJSONOptions: JSON Options
    initialize: function(OptionsJSON),
    /---------------------------------------
    //Addition of a AXPAR setup
    addAXPAR:function(aCode,aValue)    
});

XTENDWSVC.classParamXtdSpgAccess

Class of call setup for an 'Data access' sup-program web service which has XTENDWSVC.classParamXtdSpgAccess.

XTENDWSVC.classParamXtdSpgAccess=Class.create(XTENDWSVC.classParamXtdSpg,{
    /---------------------------------------
    //aJSONOptions : JSON Options
    //aNbLines : maximum number of requested records
    //aStartAt : 1st record rank
    //Updates the '$REC_STARTAT','$TOTAL_COUNT','$RET_COUNT','$HAS_NEXT' setups
    initialize: function(aNbLines,aStartAt,aJSONOptions),
});

XTENDWSVC.classParamObject

Class of setup for the call to X3 object web service which has XTENDWSVC.classParam.

XTENDWSVC.classParamObject=Class.create(XTENDWSVC.classParam,{
    /---------------------------------------
    //aJSONOptions : JSON Options
    //aTimeStampX3 : String - TimeStamp of X3 object (can be null or empty)
    //Adds the WW_MODSTAMP setup in the ADXTEC group with the value aTimeStamp
    initialize: function(aTimeStampX3,aJSONOptions),
});

XTENDWSVC.classJsonOpt class

Class which represents the JSON options.

//---------------------------------------
//Activates the noGroups option
noGroups:function(),
//---------------------------------------
//Activated the noRows option
noRows:function(),
//---------------------------------------
//Activates the noLabels option
noLabels:function(),
//---------------------------------------
//Activates the noClobs option
noClobs:function(),
/---------------------------------------
//Updates the list of groups to exclude
//aValue : String or Array of string
excludeGrp:function(aValue),
//---------------------------------------
//Updates the list of groups to exclude
includeGrp:function(aValue),
//---------------------------------------
//Updates the list of fields to exclude
excludeFld:function(aValue),
//---------------------------------------
//Updates the list of fields to exclude
includeFld:function(aValue),

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

Classe XTENDWSVC.classCaller

This is the base class used to call a REST web service.

By default, this class cannot be used to post several requests simultaneously and blocks attempts of multiple calls.

/*---------------- MAIN METHODS----------------*/
//Constructeur
//aInterfaceId: ID of the XTEND interface
//Optional: the CallBack statistics functions can be entered as setups
//               if not implemented in the class
//               -> aInterfaceId,onSuccess,onFailure,onException
initialize:function(aInterfaceId),
//-------------------------------------------------------
//Checks the current call and triggers the sending of the request
//aUrl        : Service Url
//aData       : Data
//aContenType: ContentType
exec:function(aUrl,aData ,aContenType),

/*-------- CALLBACK METHOD TO OVERLOAD SYSTEMATICALLY
// HTTP STATUS=200
// !! The daughter methods must call $super(response) in order to set
//    the call flag to false
onSuccess:function(response),

/*--------- CALLBACK METHOD TO POTENTIALLY OVERLOAD----------*/
// EXCEPTION JAVASCRIPT
//By default, this method displays the exception
// !! The daughter method must call $super(request,exception,true)
//    to set the call flag to false without displaying the result
onException:function(request,exception,aIsOverriden),
//-------------------------------------------------------
// HTTP STATUS!=200
//By default, this method displays the error cause
// !! The daughter method must call $super(request,headerJSON,true)
//    to set the call flag to false without displaying the result
onFailure:function(response,headerJSON,aIsOverriden),

/*--------------------- FORMATS --------------------*/
//Sets application/json as the type of data in return
//Default type
setReturnJSON:function(),
//-------------------------------------------------------
//Set application/xml as data type in return
setReturnXML:function(),
//-------------------------------------------------------
//True if XML data in return
returnXML:function(),
//-------------------------------------------------------
//True if JSON data in return
returnJSON:function(),

/*--------------------- MISCELLANEOUS ---------------------*/
//effectively posts the request to the server if there are no current call
sendRequest:function(aUrl,aDataObject,aContenType)
//-------------------------------------------------------
//Resends the ID of the interface
getId:function(),

/*------------- MULTIPLE CALLS MANAGEMENT -------------*/
//To overload if the user wants to unblock multiple calls
//aBusy : True if call in progress
//Resends true in order to authorize the call to the web service
doSendRequest:function(aBusy),
//-------------------------------------------------------
//Updates the occupation flag
setBusy:function(aYes),
//-------------------------------------------------------
//True if call in progress
isBusy:function(),

Classe XTENDWSVC.classCallerSpg

This is the base class used in order to call a sub-program REST web service.

XTENDWSVC.classCallerSpg=Class.create(XTENDWSVC.classCaller,{
    //-------------------------------------------------------
    //Manufacturer
    initialize:function(aInterfaceId),
    //-------------------------------------------------------
    //Executes the request with aData data
    //Authorized value for aData
    // -null or undefined -> this.exec()
    // -String -> this.exec(aString,'text/plain')
    // -Hash   -> this.runFORMENCODED(aData)
    // -Other  -> this.runJSON(Object.toJSON(aData))
    run:function(aData),
    //-------------------------------------------------------
    //Executes the request with XML aXML data
    runXML:function(aXML),
    //-------------------------------------------------------
    //Executes the request with JSON aJSON data
    // JSON : String JSON or JavaScript object (setup class)
    runJSON:function(aJSON),   
    //-------------------------------------------------------
    //Executes the request with the key/value grid aHash
    //aHash represents the content of a <form> form
    runFORMENCODED:function(aHash),
});

For instance

The following example calls the XTDLOGIN interface of the current site and displays the response.

Sub-program call

var wClassCaller=Class.create(XTENDWSVC.classCallerSpg,{
   //Manufacturer if there are no other setups than aInterfaceId
   initialize:function($super,aInterfaceId){
      $super(aInterfaceId);
   },
   //Méthode obligatoire pour traiter la réponse
   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);

Result

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

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

X3 INFORMATION MESSAGES :
User connected with DIS001 user code

{
"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"]
}

Class XTENDWSVC.classCallerObject

This is the base class used in order to call a X3 object REST web service.

XTENDWSVC.classCallerObject=Class.create(XTENDWSVC.classCaller,{
    //-------------------------------------------------------
    //Constructeur
    initialize:function(aInterfaceId),
    //-------------------------------------------------------
    //Save method
    //aData : Data with the JSON or XML format
    actCreate:function(aData),
    //-------------------------------------------------------
    //Méthode  Read
    //aHashKeys : Hash which contains the object keys
    actRead:function(aHashKeys),
    //-------------------------------------------------------
    //Methode Delete
    //aHashKeys : Hash which contains the object keys
    actDelete:function(aHashKeys),  
    //-------------------------------------------------------
    //Method Modify
    //aHashKeys : Hash which contains the objects keys
    //aData     : Data with JSON or XML format
    actUpdate:function(aHashKeys,aData),
    //-------------------------------------------------------
    //Action de code aCode
    //aCode     : Action code
    //aHashKeys : Hash which contains the object keys
    actOtherKey:function(aCode,aHashKeys),
    //-------------------------------------------------------
    //Action of aCode code
    //aCode     : Action code
    //aData     : Data with the JSON or XML format
    actOtherData:function(aCode,aData),
    //-------------------------------------------------------
    //Action query quick select list
    //aHashKeys      : Hash which contains the keys for selection
    //aReturnedCount : Optional - Number of requested lines
    actQuery:function(aHashKeys,aReturnedCount),
});

For instance

The following example calls the X3 OBJAYZ (AYZ objet) object interface of the current site in creation and displays the response.

Call Objet

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","Form title");
wParams.add("MAICOD","frdal@sage.com");
wParams.add("CMT","Comment");
new wClassCaller("OBJAYZ").actCreate(wParams);

Result

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

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

X3 INFORMATION MESSAGES :
Form created

{
"FRMCOD":"0902000005",
"FCYCOD":"FDBTEST",
"ZFCYCOD":"Site de test fdalbo",
"TYP":"OTH",
"ZTYP":"Divers",
"STATUT":"1",
"STATUT_LBL":"A traiter",
"TTL":"Form title",
"MAICOD":"frdal@sage.com",
"CREDAT":"20090227",
"CREHEURE":"184431",
"CMT":"Comment",
"PARCOD":[],
"PARVAL":[],
"WW_MODSTAMP":"000000000000",
"WW_MODUSER":""
}