Catcade - Cascading Category Selection

Installation

This is a jQuery plugin, so be sure to include jQuery as your project dependency module or include in the pages using this plugin. This plugin also only uses select2, for now. support for pure HTML and vanilla javascript is in the roadmap. For now, to use this plugin, simply execute npm i catcade against your project or search for catcade in jsDelvr and use:

<script src="////cdn.jsdelivr.net/npm/[email protected]/dist/catcade.min.js"></script>

to include catcade to your project.

Usage

This is a jQuery plugin. Like any other jQuery plugin, you can initialize a cascading category selection by invoking catcade against a jQuery object.

$ = jQuery;
$('.selector-for-an-empty-div-or-span-as-container').catcade(options);
// or
$('.selector-for-an-empty-div-or-span-as-container').catcade('a-switch');

where options and switches may include any of the properties discussed later. It returns the jQuery object it has fired upon for chaining.

Options

Almost all options are (no pun intended) optional. Property | Type | Description | Default ---------|-------|-------------|-------- container|JQuery | A jquery container that overrides the object which catcade has fired upon. | The object which catcade has fired upon. label |string | The label which is used for each selection. Can be overriden by template. | "Category" live |boolean| Whether use select2's ajax option for firing live queries against url. | false maxLevel |number | The maximum level that cascading continues; the depth which is allowed to be delved in. 0 means unlimited depth | 0 name |string | The name used for the "LAST" level of selection which you can grab value for form submition | "category_id" url |string | PropertyFunction<string> | The URL used for fetching options in each level. You can provide dynamic URLs for each level by providing a function that returns the url for each specific level. | (parent, base = '') => base + defaultTo(parent,$(``<input value=""/>``)).val(), template |string | TemplateFunction | A template which the input selection will be created with. To modify each level's template, you can use a function that returns the HTML code to be inserted at each level. | a function

The template's default is as follows:

(self, parent) => {
    let result = ``;
    if (parent)
    {
        let current = parseInt(parent.data(`level`)) + 1;
        result = `
<div class="form-group">
<label class="col-md-3">${self.label} - ${current}</label>
<select class="form-control col-md-6" data-level="${current}" name="${self.name}"><option></option></select>
</div>
`;
    }
    else
    {
        result = `
<div class="form-group">
<label class="col-md-3">${self.label}</label>
<select class="form-control col-md-6" data-level="0" name="${self.name}"><option></option></select>
</div>
`;
    }
    return result;
}

Switches

There is currently two switches, but through course of time and per need as this package grows, they will grow through community. Switches are called like this:

$('container-selector').catcade('switch')

Switch | Returns | Action -------|---------|------- destroy | jQuery object that it fired upon (for chaining) | cleans the catcade on container object | The internal DynamicCategory object for manipulation per instance | nothing

Contributions

Feel free to open issues, pull-requests and engage in discussions. I'll appreciate it and do my best to keep adding and fixing.