Flexible View Control for XPages – Category Renderers

What is a Renderer?

In the DataTables world, “Renderers” play an important role in creating the visual representation of a table. In fact, behind the scenes the Flexible View Control uses Renderers to display all of the data in a View. In the future, I will be posting about creating custom renderers to further enhance the Flexible View Control, but this post focuses on “Category Renderers” in keeping with the category/subcategory theme of recent posts.

Technically speaking, Category Renderers are not the same as standard DataTable Renderers. But the concept is the same – taking a data input and altering the output that is presented to the user.

Building a Category Renderer Demo

Let’s pick up where we left off in the previous post with our subcategory demo. I made a copy of the View Definition used in this demo and called it ferraris-category-renderer. Take look at the MODEL column:

Underneath the category checkbox is another checkbox labeled “Renderer”. Clicking this reveals a pop-up window:

In this box I can enter a function string without parameters in the same way that callback functions are configured in the FVC custom properties. If a value exists in this box, then after the categories are drawn in the DataTable, the dom element for each MODEL category row is passed into the function defined in the category renderer box:

 // does this group need a renderer?
if (o.columnCategory[x].categoryRenderer != null && o.columnCategory[x].categoryRenderer != "" ) {

	$('.group-'+o.columnCategory[x].itemName).each(function() {

		var fnstring = o.columnCategory[x].categoryRenderer;
		if ((typeof fnstring) == "undefined" || fnstring == null) {
			return;
		}
		if (fnstring.indexOf('.') > -1) {
			var fn = window.getFunctionFromString(fnstring);
		} else {
			var fn = window[fnstring];
		}
		
		// is object a function?
		if (typeof fn === "function")  {
			fn(this);
		} else {
			console.log("renderer error")
			return;
		}
	});
}

In the screen below I’ve entered a function name into the category renderer box. This is just a client-side JavaScript function that lives in a demos script library.

Category Renderers are JavaScript functions

Starting simple, I’m just going to change the font for the MODEL category row. *Technically* this should be done with CSS instead of a renderer, but it’s fine for a simple example:

model_renderer : function(_this) {
	// _this is the row dom element
	console.log('category renderer')
	$(_this).css({
		'font-family':'Oswald',
		'font-size':'1.25em'
	})
}

A more practical use for the category renderer is to manipulate the dom node for the category. For this next example I’m going to wrap the category value in a Bootstrap label:

model_renderer : function(_this) {
	// _this is the row dom node
	
	$(_this).css({
		'font-family':'Oswald',
		'font-size':'1.25em'
	});
	
	
	// add a Bootstrap label
	var v = $('.group_value',$(_this)).text();
	$(_this).find('.group_value').addClass("label label-success")
	
}

Checkout the demo: http://demos.xpage.me/demos/datatables-xpages-bootstrap.nsf/viewCategories.xsp?viewdef=ferraris-category-renderer&key=make:ferrari

Summary

In summary, Category Renderers can be a valuable, low-code tool that adds functionality to Views created with the Flexible View Control for XPages and provide a more rich experience for your users.