Using the Custom Component JavaScript Class

Description

How to make an Ajax callback and maintain state across HTTP calls.

 Making an Ajax Callback

  •  Syntax:

    {Component.Object}.ajaxCallback(part,rowNum,XbasicFunction OR actionName,URL,OtherData)

The ajaxCallback method of the A5.CustomComponentHelper JavaScript class makes it trivial to call a server-side Xbasic function from the client side of an Alpha Five Custom Control.

The first two parameters are meaningless and should normally be set to empty strings. They have been included for compatibility with the ajaxCallback method of the Grid and Dialog2 components. The third parameter contains the name of the Xbasic function to call if the URL parameter is omitted or an empty string, and an action name if the URL parameter is specified.

For example:

function doCallback() {
  {Component.Object}.ajaxCallback('','','','','Navigate');
}

The URL parameter is only used when it is necessary to call back to a non-Alpha site. In that case, the non-Alpha site will be unable to take advantage of many of the facilities that make Alpha Five Ajax callbacks so easy to develop and maintain, such as e._state.

The OtherData parameter takes the form of a JavaScript string of name/value pairs in HTTP query form. It can also be a JavaScript function call that returns a JavaScript string of name/value pairs in HTTP query form, or be a JavaScript expression that evaluates to a JavaScript string of name/value pairs in HTTP query form.

So, for example, you can have OtherData parameters like these:

Simple name/value pairs in HTTP query form:

'_direction=First&_param2=something&_param2=else'

Evaluate a reference:

'_direction=First&_param2='+$('div1').value

If 'div1' was an input control and it contained a value of 'myspecialvalue' then this would evaluate to:

'_direction=First&_param2=myspecialvalue'

In the Xbasic callback handler, the e object that was passed in would have:

Request.Variables._direction = "Frank"
Request.Variables._param2 = "myspecialvalue"

If the OtherData parameter were

readDataFromPage()

and readDataFromPage() returned:

'_param1=foo&_param2=bar'

then that returned string would be submitted to the server.

Note that the Ajax callback function (in Xbasic) can return a string that will be executed as JavaScript.

See User Defined Ajax Callbacks in Grids V10 for additional discussion of this method.

 Maintaining state

In a web component you often need to maintain state across HTTP calls. In the custom component, assuming that you are using an Alpha Five server, you can do this by creating properties of the e._state variable in any event-handling context where the e variable has been passed in by the component.

For example, to create a state property called pageNumber and initialize it to "1", run the following Xbasic code in your onInitialRender event function:

e._state.pageNumber = "1"

Behind the scenes, the server will generate a JavaScript call to the component's setStateInfo() method.

If you wanted to increment the pageNumber state in a callback function, you could write:

dim pn as c
dim e._state.pageNumber as c = default ""
pn = e._state.pageNumber
dim newPage as n
newPage = val(pn) + 1
e._state.pageNumber = "" + newPage

See Also