Difference between revisions of "AJAX - Start Here"

Revision as of 14:00, 21 October 2014

1 Overview

AJAX, short for Asynchronous JavaScript And XML, is a group of interrelated Web development techniques used on the client-side (in the browser) to create asynchronous Web applications.

With Ajax, Web applications can send data to and retrieve from a server asynchronously (in the background) without interfering with the display and behaviour of the existing page. Data can be retrieved using the XMLHttpRequest object. Despite the name, the use of XML is not required; JSON is often used instead (see AJAJ), and the requests do not need to be asynchronous.

Ajax is not a single technology, but a group of technologies. HTML and CSS can be used in combination to mark up and style information. The DOM is accessed with JavaScript to dynamically display – and allow the user to interact with – the information presented. JavaScript and the XMLHttpRequest object provide a method for exchanging data asynchronously between browser and server to avoid full page

http://en.wikipedia.org/wiki/Ajax_%28programming%29

Basically AJAX allows a web page to retrieve information that was not supplied when the page was first drawn. There are many uses for this.

• It can help pages remain a lot smaller as not all of the data has to be on the page, when it first loads.
• It can be used to retrieve real time information for various uses
• It can be used to store data without having to leave the current page.

Pure AJAX can be used in bxp software (bxp) however it can be long and complicated to build. To speed things up bxp has a number of pre-built functions already integrated with the security of bxp to allow these functions to work. These functions are only currently available in the bxp forms.

2 How it works

1. When you log into bxp and start a form, the page will draw based on the Form (Web Page is built on Form 1).
2. As part of the code of the page you can include AJAX functionality into the form, done through the Advanced Settings > JavaScript onLoad. (AJAX is drawn into the page.)
3. When the page is executed in the clients browser, the AJAX can be activated and it works through the BEAPI to access data in any number of forms.

3 Array of Parameters

To save a lot of repeating code, the majority of the functionality use the same parameters.

All of the functionality is coded into the publicly available library fn_javascript_ajax_campaign.js. https://ww3.allnone.ie/library/javascript/fn_javascript_ajax_campaign.js

bxp creates an array to store the parameters. Not all parameters are being used by all functions.

//================================================================
// Variable Initialisation
//================================================================
//Initialising the settings array, and for clarity explaining the elements of the array.
//Simply copy this block of data into your code and replace the values with your system values
//Not that the automation user MUST have an IP Address set for the system to work
//-----------------------------------------------------------------------------------------
aryAjax_Settings[0] = "client_demo"; 					//The system to use
aryAjax_Settings[1] = "demo"; 						//The automation username
aryAjax_Settings[2] = "password"; 					//The automation users password
aryAjax_Settings[3] = "1"; 						//The Id of the campaign
aryAjax_Settings[4] = "strCDA_1_field_0_0"; 				//The search field
aryAjax_Settings[5] = "1"; 						//The search value
aryAjax_Settings[13] = "-1";						//Id of the current record, used for delimiting and not repeating current case
aryAjax_Settings[14] = "true";						//Click through to campaign?
aryAjax_Settings[15] = "divWarning";					//The id of the destination to which the table will be inserted
aryAjax_Settings[16] = "Table";						//The default option is to create a table to display.  The other options is Insert. Which will insert the values into the relevant fields.

//The fields to be returned into the array
//The column names of those fields
//The first field must always be the ID of the campaign
aryAjax_Settings[6] = "intCDA_1_Id,strCDA_1_field_0_0,strCDA_1_field_0_1";
aryAjax_Settings[12] = "Id,Field 1,Field 2";
aryAjax_Settings[17] = "intCDA_1_Id,strCDA_1_field_0_0,strCDA_1_field_0_1";	//For insertion, what local campaign fields will the data be transferred into.
 
//-----------------------------------------------------------------------------------------
// Extra settings fields used by the function, but made available globally for testing
aryAjax_Settings[7] = "";						//Constructed URL for retrieveing data
aryAjax_Settings[8] = "-1";						//Error Status
aryAjax_Settings[9] = "";						//Error Translation
aryAjax_Settings[10] = "-1";						//Record count
aryAjax_Settings[11] = "";						//Alternate Destination if required. Constructed just before use

//-----------------------------------------------------------------------------------------
aryAjax_Settings[18] = "true";						//Show table if empty? By default always show something.
aryAjax_Settings[19] = "";						//Custom sort order if needed
aryAjax_Settings[33] = "";						//Custom sort orderDESC 
aryAjax_Settings[20] = "";						//Custom group by if needed
aryAjax_Settings[21] = "false";						//Limit to My Records only
aryAjax_Settings[22] = "";						//Auto Login - System
aryAjax_Settings[23] = "";						//Auto Login - User
aryAjax_Settings[24] = "";						//Auto Login - SessionId

//--Live Search----------------------------------------------------------------------------
aryAjax_Settings[25] = "";						//Field to Update (Id Value)
aryAjax_Settings[26] = "";						//Function After Update
aryAjax_Settings[27] = "";						//Field to Update (Display Text)

//--Post Data Rerrieval Execution----------------------------------------------------------
aryAjax_Settings[28] = "";						//Generic function call

//--Live Search Format Options-------------------------------------------------------------
aryAjax_Settings[29] = "";						//Buttons in the first column or the last column 	--> First/Last
aryAjax_Settings[30] = "";						//Multi - button functionality	 					--> Two colours
aryAjax_Settings[31] = "";						//Button Text (multi separated by ','  				--> XXXXXXXX,XXXXXXX
aryAjax_Settings[32] = "";						//Value for matching to show button 2 				--> XXXXXXX

//--Order Options----------------------------------------------------------------------------
aryAjax_Settings[33] = "";						//Sort decending 

//--AJax Data Insert/Update/Delete Parameters----------------------------------------------------------------------------
aryAjax_Settings[34] = "";						//Fields to insert to
aryAjax_Settings[35] = "";						//Values to insert
aryAjax_Settings[36] = "";						//Field to search on
aryAjax_Settings[37] = "";						//Value to search with
aryAjax_Settings[38] = "";						//Add a CCl

4 Functions Available

As part of the functionality there are a number of predefined functions. These are set in aryAjax_Settings[16]

As the functions are detailed, please use the links where available for further details.

• Append
• dbDeleteRecord
• dbInsertRecord
• dbUpdateRecord
• Insert
• InsertCount JavaScript_AJAX_Functions
• LiveSearch JavaScript_LiveSearch
• LiveSearchTable JavaScript_AJAX_Functions Java_Script_Live_Search_Table
• Populate JavaScript_Populate_Drop_Down_List_from_another_Campaign
• Populate_AltList JavaScript_AJAX_Functions
• PopulateNoClear
• PopulateNoClear_AltList

5 Solutions

It is possible to build entire solutions using AJAX

• JavaScript_Self-Referencing_Campaigns

• JavaScript_-_Interactive_Record_Locking

6 Security

Security is very important to bxp and BEAPI calls should be no less secure. For this reason there are a number of security concepts to be considered.

The AJAX makes calls to the BEAPI, hereto referred to as "The Call". When the Call is made, it requires a username and password. That user must have access to the form. In using the AJAX there are two possible options.

1. Use a set username and password
2. Use a dynamic username and password

The set username and password is more secure but must have specified white listed IP addresses it can be used from. The user must be granted access to the form containing the data. This also allows this user to have all functional access removed but still allow content access. This is the more secure preferred option.

• aryAjax_Settings[0] = "client_demo";
• aryAjax_Settings[1] = "demo";
• aryAjax_Settings[2] = "password";

Set user location can be difficult to manage if users move location often or there is no static IP address available. There is a dynamic security setting, which requires the current user to have access to the form, but the engine uses the current users login, to access the form.

• aryAjax_Settings[22] = document.getElementById('intSystemGenerated_CompanyId').value;
• aryAjax_Settings[23] = document.getElementById('intSystemGenerated_UserId').value;
• aryAjax_Settings[24] = document.getElementById('intSystemGenerated_LoginKey').value;

The Call is made using a secure HTTP Post using form variables and not querystring parameters. This provides maximum security for the data being sent.

The error code will return 0 for success and the following codes for errors.

• -1 = No settings initialised. Please set the settings on your page.
• -2 = Settings not initialised. Please set the settings on your page.
• -3 = Settings cannot be blank. Please check the settings on your page.
• -4 = Server response not formatted correctly.
  Please refresh the page and try again.
  Error Code [ " + aryAjax_Settings[3] + " - " + aryAjax_Settings[5] + " ]
• -5 = No data fields specified. Please set the settings on your page.
• -6 = No display fields specified. Please set the settings on your page.
• -7 = AJAX transport failure. Please refresh the page and try again.
• -8 = AJAX initialisation failure. Please refresh the page and try again.

7 Error messages and feedback

There is often error messages to display when using the engine for a variety of reasons including: incorrect username, password, IP address restricted, etc.

For this reason, it is possible to write back to screen the error messages into a user specified div. You create the div on your form where you like it and put id="" in it.

If you set aryAjax_Settings[15] = 'divYourName'; then the error messages will write to the innerHTML of the div.