New Version

Alex,

I just installed the new version you made available and noticed that a few things have changed and in particular, the way the message template works. I noticed the new error and the nodata templates and noticed that there is a text and and image property for each. Can you please explain how we can use these new features?

Jeremie,

In the previous version the template switching logic was hidden inside the List template, which made it difficult to customize. The new implementation works like this:

- layout template splits the control area into four parts – corner, top, left and main.
- main template decides what to show in the main part depending on the status/code property. It may be data template, error template or status template.
- data template prints a list of row templates, row is a list of columns.
- status template displays status/text property next to status/image.


The main template does not have underlying HTML – it just calls one of other templates, so it is now possible to use a function returning other template instead of full template object derived from Active.System.Template.

Current main template logic is: if status/code is empty – display data template, if "error" – display error template, otherwise status template. This allows displaying multiple status codes with a single status template.

If you decide to modify the template selection logic – here is the example:

var myTemplate = function(){

switch(…) {
case 1:
return this.getTemplate("template1");
case 2:
return this.getTemplate("template2");
…
}
}

obj.setTemplate("main", myTemplate);

The status template retrieves status text and status image from the status data model. By default the status model just maps status codes ("loading" and "nodata") to text message and image code. You can either modify mapping functions or just assign static values when necessary.

The error template should work in a similar way. In case of error your status/code should return "error", which makes main template switch content to error template, and error model should return proper error/text. You can add more properties to the error model and error template if needed.

Sorry for introducing breaking changes, but I believe in this case it was really necessary.

Alex,

I agree that this change was needed but I'm still not sure I understand how I can use this new behavior. For instance, I override the table's "response" with a custom function which allows me to inspect the XML returned asynchronously from the server. If no data rows are returned, how do I notifythe main template that it should display the NoData template? Also, if the server notifies me that an error occured, how do I update the error template to display my specific error message and how do I notify the main template that it should display the error template?

Jeremie,

in ActiveWidgets there are two ways of providing a property value or a content template: 'push' or 'pull'. The common 'push' style means you just assign the value using setProperty or setTemplate method and the grid keeps copy of it. With the opposite 'pull' style you provide the grid with a function, which returns a requested resource. With the 'pull' style the grid does not keep the copies of the resources but requests them (by calling he function) when and only when they are needed.

The status model and template switching is implemented using the 'pull' approach. The 'main' template is returned by a function which selects it based on status/code property. Status/code is also returned by a function, which calculates it on demand by checking different parameters of the grid and data model. Status text is produced on demand from the status code etc. With this approach whenever you call grid.refresh() it will obtain the current values and paint itself according to the current values.

Here is the example how you can add 'error' status:

...
// assign external XML data model
obj.setDataModel(table);

// create custom status code function
var myStatusCode = function(){

var data = this.getDataModel();
if (!data.isReady()) {
return "loading";
}

var xml = this.getDataProperty("XML");
if (xml && xml.selectSingleNode("//error")) {
return "error";
}

if (!this.getRowProperty("count")) {
return "nodata";
}

return "";
}

// assign custom status code function to the grid
obj.setStatusProperty("code", myStatusCode);

- the XML.Table model now provides direct access to the DOM document through the property called 'XML', so you can access all data nodes without intercepting the response() method. You can get it from the table object using table.getXML() method or directly from the grid using grid.getDataProperty("XML").

The same way you can provide the error text to the error model (error template gets the text message from the error/text property).

// create custom error text function
var myErrorText = function(){

var xml = this.getDataProperty("XML");
if (!xml) return "";

var node = xml.selectSingleNode("//error");
if (!node) return "";

return node.text;
}

// assign custom error text function to the grid
obj.setErrorProperty("text", myErrorText);


------------------------------------------


If you don't like 'pull' approach - you can still use 'push' method. Whenever something changes - you can set 'main' template, set status and/or error properties and call refresh();

obj.setMainTemplate(new Active.Templates.Status);
obj.setStatusProperty("text", "Loading data");
obj.setStatusProperty("image", "loading");
obj.refresh();