Updating a Page without Reloading

All modern browsers have a built-in XMLHttpRequest object to request data from a server; with this object it is possible to interact with the server after page load and update a page without reloading it.

InterSystems IRIS® provides an easy system to use this object within CSP pages, to communicate directly with the CSP server.

Basics

There are three parts to this system:

When generating the <head> part of the HTML page, call HyperEventHead(), which returns a string consisting of two successive <script> elements that are required by this system. The method signature is as follows:
```
classmethod HyperEventHead(iframeOnly As %Boolean, 
                           strict As %Boolean = 0) as %String
```
Where:
- The iFrameOnly argument is ignored but is present for compatibility.
- If strict is 1, the returned string will use the strict HTML 4 format of <script> tag.
Create a (server-side) method to call. The method must be an instance method and can return a literal value (not an OREF). It cannot pass arguments by reference or as output.

Tip:

A common reason to XMLHttpRequest is to modify the page, so it may be helpful for this method to return a fully formed piece of HTML to add to the page.
As part of the page HTML, define a JavaScript function that uses HyperEventCall() to invoke your method and that uses the results of that call, if applicable.
The HyperEventCall() method has the following signature:
```
classmethod HyperEventCall(methodName As %String, 
                           args As %String, 
                           type As %Integer = 0) as %String
```
Where:
- methodName is a reference to the server method, either in the form ..MethodName() if the method is in the same class, or in the following longer form: Package.Class.MethodName
- args contains all the argument to pass to the method. args is a quoted string containing a comma-separated list of variables (which are defined earlier within your JavaScript function).
- If type is 1 (recommended), the call is asynchronous.
HyperEventCall() returns the value returned by the server method.

Example

An example shows how this fits together. In this scenario, we want to define a function that retrieves additional parts of a tree control. The function will use the GetChildren() method of a class named %CSP.Documatic.Helper. The method takes three string arguments: name, parent, and ns and it returns a fully formed piece of HTML that is meant to be added to the page within the tree control. (For our purposes here, it does not matter exactly how that tree control works or exactly what this method does.)

Within the code that generates the <head> for this HTML page, we call both HyperEventHead() and HyperEventCall() as follows:

 //Add hyperevent-related scripts for left navigation
 set headhtml=_..HyperEventHead()
  _"<script>function addChildrenAfter(item,name,Id,ns) {"
  _"var h="_..HyperEventCall("%CSP.Documatic.Helper.GetChildren","name,Id,ns",1)_";"
  _"if (h!==null) {"
  _"item.insertAdjacentHTML('afterend',h); } else {"
  _"location.reload();}"
  _"return false;"
  _"}</script>"

The resulting HTML looks like this (with line breaks added and edits for readability):

<script type="text/javascript" src="/somelocation/csp/broker/cspxmlhttp.js">
</script>
<script type="text/javascript" src="/somelocation/csp/broker/cspbroker.js">
</script>
<script>function addChildrenAfter(item,name,Id,ns) 
{var h=cspHttpServerMethod("pyK473ekNn0...very long...DOKepQ",name,Id,ns);
if (h!==null) {item.insertAdjacentHTML('afterend',h);
 } else {location.reload();
}return false;}</script>

Notice that this HTML does not include the name of the server method, but instead includes a long token that the server uses to identify the code to run. Also note that this HTML includes cspHttpServerMethod, which is a JavaScript function provided by HyperEventHead().

Handling Errors

Saving and Using Cookies