`updateHandler`

Use updateHandler to call Gosu on the server side and get a result back without rendering the page again. For example, suppose that your panel is the only place in which some data is displayed, and you want to get the latest version of that data and update your panel using JavaScript. In that case, use the updateHandler to get the data.

The updateHandler must conform to the following interface:

public interface TemplatePanelUpdateHandler {
  gw.api.json.JsonObject update(gw.api.json.JsonObject json);
}

Because this interface has only one method, you can implement it with a Gosu block. Within the template, call the update handler from JavaScript using the gw.api.updateTemplate API. Pass gw.api.updateTemplate the following:

The ID of the template panel. The ID is provided by substituting in the value __helper.TemplatePanelId. The __helper variable is provided as part of the context to the template panel.
A JSON object to send to the server.
A callback method to execute when the server returns the resulting JSON.

The following is an example of calling gw.api.updateTemplate within a template:

gw.api.updateTemplate("<%=__helper.TemplatePanelId%>", {command: "details", name: typeName}, function(details) {
  if (details.name !== currentDetailsName) {
    return;  
  }  updateFields(details.fields);
});

When this JavaScript is executed on the client side, it calls the server with the specified template panel ID and JSON. The server looks up the Gosu updateHandler for the template panel and executes it, passing the JSON as its argument. The resulting JSON is returned to the client, which then calls the callback function.