Fork me on GitHub

How to Create a Basic jPList Plugin

Sometimes you want to make a control with a special functionality that is not available out of the box. For example, perhaps you want a text filter that some custom logic. In this case, you may want to write a control.

Every jPList control has a special HTML structure with 3 data attributes:

  • data-control-type - a unique control type that is defined in control's JS file.
  • data-control-name - control name could have any value. It's used in cases when there are several controls of the same type on the page.
  • data-control-action - could have the values 'filter', 'sort', 'paging' depending on control's purpose.
<div 
    data-control-type="my-filter"
    data-control-name="my-filter-1"
    data-control-action="filter" />

jPList recognizes its controls by these three data attributes. For every control it looks for a JavaScript function that defines appropriate data-control-type. The basic control structure may looks as following:

(function(){
	'use strict';		
		
   //***************** PRIVATE METHODS ****************************
	/**
	* Get control status
	* @param {Object} context
	* @param {boolean} isDefault - if true, get default (initial) control status; else - get current control status
	* @return {jQuery.fn.jplist.StatusDTO}
	*/
	var getStatus = function(context, isDefault){
        //create and return control status here...
        return null;		
	};
         			
	/**
	* Set control status
	* @param {Object} context
	* @param {jQuery.fn.jplist.StatusDTO} status
	* @param {boolean} restoredFromStorage - is status restored from storage
	*/
	var setStatus = function(context, status, restoredFromStorage){	
        //update control state using the control status		
	};
	
	/**
	* Get control paths
	* @param {Object} context
	* @param {Array.} paths
	*/
	var getPaths = function(context, paths){
		//add control jQuery paths to the comon paths list
	};
	/**
	* Init control events
	* @param {Object} context
	*/
	var initEvents = function(context){	
        //init control events like 'click', 'change' etc.
	};
   //***************** CONSTRUCTOR ****************************
	
	/** 
	* My Filter control
	* @constructor
	* @param {Object} context
	*/
	var Init = function(context){
			
		context.params = {	
			//control parameters...
		};
		
		//init events
		initEvents(context);
		
		return jQuery.extend(this, context);
	};
   //***************** PUBLIC METHODS ****************************
		
	/**
	* Get control status
	* @param {boolean} isDefault - if true, get default (initial) control status; else - get current control status
	* @return {jQuery.fn.jplist.StatusDTO}
	*/
	Init.prototype.getStatus = function(isDefault){
		return getStatus(this, isDefault);
	};
	
	/**
	* Get Paths
	* @param {Array.} paths
	*/
	Init.prototype.getPaths = function(paths){
		getPaths(this, paths);
	};
	
	/**
	* Set Status
	* @param {jQuery.fn.jplist.StatusDTO} status
	* @param {boolean} restoredFromStorage - is status restored from storage
	*/
	Init.prototype.setStatus = function(status, restoredFromStorage){
		setStatus(this, status, restoredFromStorage);
	};
   //***************** CONTROL REGISTRATION IN JPLIST ****************************
	
	/** 
	* My Filter control initialization
	* @constructor
	* @param {Object} context	
	*/
	jQuery.fn.jplist.controls.MyFilter = function(context){
		return new Init(context);
	};	
	
	/**
	* control registration in jPList plugin system
	*/
	jQuery.fn.jplist.controlTypes['my-filter'] = {
		className: 'MyFilter'
		,options: {}
	};	
})();