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:

Adding a Category Renderer to a View Definition

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'
	})
}
Changing the font of the top-level category with a renderer

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

Wrapping the category with a Bootstrap label

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.


One Comment on “Flexible View Control for XPages – Category Renderers”

  1. […] a recent blog post we covered the concept of ‘Category Renderers’, which allows the user to easily alter the visual representation of category rows in a categorized […]

    Liked by 1 person


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s