Skip to main content

buildfire.components.control.listView

The Control List View component is a versatile tool designed for displaying lists of items in a standardized manner. It comes equipped with a search bar, sorting capabilities, and options for adding items individually or in bulk, among other features.

list view custom

Requirements

After injecting the buildfire.min.js inject sortable.min.js as well because it is required for the component to work properly. Finally, inject the component css file listView.css and js file listView.js

Control

<head>
<!-- ... -->
<script src="../../../../scripts/buildfire.min.js"></script>
<script src="../../../../scripts/sortable.min.js"></script>

<link rel="stylesheet" href="../../../../styles/components/control/listView/listView.css"></link>
<script src="../../../../scripts/buildfire/components/control/listView/listView.js"></script>
</head>

Methods

listView()

new buildfire.components.control.listView(selector<String>, options<Object>)

Class constructor method which initializes the Control List View component.

Arguments

NameTypeRequiredDescriptionDefault
selectorstringyesCSS selector of element that will contain component
optionsobjectfalseOptions object.

options

NameTypeRequiredDescriptionDefault
appearanceobjectnoSpecifies appearance of certain elements
settingsobjectnoSpecifies functionalities inside the component
contentMappingobjectyesSpecifies item mapping keys and columns
addButtonOptionsarraynoSpecifies dropdown options on add button
sortOptionsarraynoSpecifies sort options inside the component

options.appearance

NameTypeRequiredDescriptionDefault
titlestringnoSpecifies the title of the list.
infostringnoSpecifies the info section of the list.
addButtonTextstringnoSpecifies the add button text."Add item"
addButtonStylestringnoSpecifies the add button appearance. "filled or outlined""filled"
itemImageEditablebooleannoSpecifies whether the image of the item in the list should be editable or not."true"
itemImageStylestringnoSpecifies the shape of the item image circle, square, avatar, none"square"
info

If itemImageEditable is set to false placeholder image will be applied to the list items based on the choosen item image style

options.settings

NameTypeRequiredDescriptionDefault
showSearchBarbooleannoSpecifies whether the search bar should show or not.false
showSortOptionsbooleannoSpecifies whether the sort options should show or not.false
showAddButtonbooleannoSpecifies whether the add button should show or not.false
allowDragAndDropbooleannoSpecifies whether the drag handle should show or nottrue
showEditButtonbooleannoSpecifies whether the item edit button should show or not.true
showDeleteButtonbooleannoSpecifies whether the item delete button should show or not.true
paginationEnabledbooleannoIf pagination is enabled onDataRequest provides the page and the pageSize.false
paginationOptionsobjectnopaginationOptions object.

options.settings.paginationOptions

NameTypeRequiredDescriptionDefault
pagenumbernoSpecifies the starting page for the data0
pageSizenumbernoSpecifies the page size for the data10

options.contentMapping

NameTypeRequiredDescriptionDefault
idKeystringnoSpecifies the id field of the item."id"
columnsarraynoSpecifies the columns for items displayed in the component.

options.contentMapping.columns

This object uses keys to denote the type of content each column should display and values to specify the data source of that content. Available column keys are:

Column KeyDescription
titleKeyFor titles, stylized to be bold and ellipsis.
subtitleKeyFor subtitles, displayed below the first key.
anchorKeyFor HTML anchor values, stylized via CSS.
imageKeyUsed to render images. Cannot be combined with other keys.
toggleKeyAdds a toggle input field. Cannot be combined with other keys.
dateKeyFor date values, formatted to a string date.

options.addButtonOptions

NameTypeRequiredDescriptionDefault
titlestringyesSpecifies the title value of the option in the dropdown menu.
info

Using options.addButtonOptions will add the dropdown to the button.

options.sortOptions

NameTypeRequiredDescriptionDefault
titlestringyesSpecifies the title value of the option in the dropdown menu.

Example

  const options = {
appearance: {
title: 'Control List View',
info: "Some description of the control list",
addButtonText: "Add Feed",
addButtonStyle: "outlined",
itemImageEditable: false,
},
addButtonOptions: [
{ title: "Add New" },
],
settings: {
allowDragAndDrop: true,
showSearchBar: true,
showSortOptions: true,
showAddButton: true,
showEditButton: true,
showDeleteButton: true,
paginationEnabled: true, //we enable pagination
paginationOptions: {
page: 0,
pageSize: 5 //we set our custom page size
},
contentMapping: {
idKey: "id",
manualOrderKey: "data.manualOrder",
columns: [
{ imageKey: "data.imageUrl" },
{ titleKey: "data.title", subtitleKey: "data.subtitle" },
{ dateKey: "data.createdOn", anchorKey: "data.address" },
{ toggleKey: "data.isActive" }
],
}
},
sortOptions: [
{ title: "Newest First", },
{ title: "Oldest Z-A", default: true }
]
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

append()

function buildfire.components.control.listView.append(items<Array>, appendToTop<Boolean>)

Appends an item or many items to the list view

Arguments

NameTypeRequiredDescriptionDefault
itemsarray or objectyesArray of items, or single item to be appended to list view.
appendToTopbooleannoSpecifies whether items should be applied to the top or the bottom of the list.false

Example

const options = {
settings: {
contentMapping: {
idKey: "id",
manualOrderKey: "data.manualOrder",
columns: [
{ titleKey: "data.title", subtitleKey: "data.subtitle" },
{ dateKey: "data.createdOn" }
],
}
}
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.append([
{ id: 1, data: { title: 'Item 1', subtitle: 'subtitle 1', createdOn: 1694642517971 }},
{ id: 2, data: { title: 'Item 2', subtitle: 'subtitle 2', createdOn: 1694743518971 }}
]);

update()

function buildfire.components.control.listView.update(id<String>, data<Object>)

Updates an item and re-renders it in the list

Arguments

NameTypeRequiredDescriptionDefault
idstringyesItem id
dataobjectyesItem data to be updated

Example

const options = {
settings: {
contentMapping: {
idKey: "id",
columns: [{ titleKey: "title" }]
}
}
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.update(1, { id: 1, title: 'Updated Item' });

remove()

function buildfire.components.control.listView.remove(id<String>)

Removes an item from the list view

Arguments

NameTypeRequiredDescriptionDefault
idstringyesItem id

Example

const options = {
settings: {
contentMapping: {
idKey: "id",
columns: [{ titleKey: "title" }]
}
}
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.append([
{ id: 1, title: 'Item 1' },
{ id: 2, title: 'Item 2' }
]);

controlListView.remove(1);

clear()

function buildfire.components.control.listView.clear()

Clears the list of items in the list view

Example

const options = {
settings: {
contentMapping: {
idKey: "id",
columns: [{ titleKey: "title" }]
}
}
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.append([
{ id: 1, title: 'Item 1' },
{ id: 2, title: 'Item 2' }
]);

controlListView.clear();

refresh()

function buildfire.components.control.listView.refresh()

Refreshes the component to apply changes and re-render items

const controlListView = new buildfire.components.control.listView('#listView_container', options);

controlListView.options.settings.showSearchBar = false;// hides the search bar
controlListView.refresh();

reset()

function buildfire.components.control.listView.reset()

Resets the component to its initial state

const controlListView = new buildfire.components.control.listView('#listView_container', options);

controlListView.reset();

Handlers

onDataRequest()

function onDataRequest(event<Object>, callback<Function>)

Triggered when:

  • The component loads for the first time
  • The user is using the search bar
  • Calling refresh() or reset()
  • Selecting the sort option
info

If you don't want to use this handler you can populate the list using the append method

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesContains search value and current sort option.
callbackfunctionyesProvides callback to retrieve items back to the component to render.

event

NameTypeRequiredDescriptionDefault
searchValuestringyesContains search value from the search bar if any.
sortOptionobjectyesContains choosen sort option if any.

callback

NameTypeRequiredDescriptionDefault
itemsarrayyesArray of items that need to be rendered inside the component.
const options = {
settings: {
contentMapping: {
idKey: "id",
columns: [{ titleKey: "title" }]
}
}
}

const items = [
{ id: 1, title: "John Smith" },
{ id: 2, title: "Will Smith" }
];

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.onDataRequest = (event, callback) => {
callback(items);
};

onItemRender()

function onItemRender(event<Object>)

Triggered every time before an item is rendered, provides a return statement to specify actions for the item.

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesContains item object.

event

NameTypeRequiredDescriptionDefault
itemobjectyesItem that is currently being rendered.
const options = {
settings: {
contentMapping: {
idKey: "id",
columns: [{ titleKey: "title" }]
}
}
}

const items = [
{ id: 1, title: "John Smith" },
{ id: 2, title: "Will Smith" }
];

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.onDataRequest = (event, callback) => {
callback(items);
};

controlListView.onItemRender = (event, callback) => {
let presetOptions = {
disableDelete: true,
disableEdit: false,
deleteButtonTooltip: "item will be deleted permanently"
};

let actions = [
{ actionId: "calendar", icon: "calendar", theme: "primary", disabled: true },
{ actionId: "graph", icon: "graph", theme: "primary", tooltipText: 'Sales' },
];

return { actions, presetOptions };
};

return statement

NameTypeRequiredDescriptionDefault
actionsarraynoArray of action objects.
presetOptions objectnoPreset options object.

actions

NameTypeRequiredDescriptionDefault
actionIdstringyesUnique ID of the action.
iconstringnoSpecifies the icon of the action.
themestringnoSpecifies the theme of the action.
disabledbooleannoDisables the action.false
tooltipTextstringnoSpecifies tooltip text for the action.

presetOptions

NameTypeRequiredDescriptionDefault
disableManualSortingbooleannoDisables manual sorting for the item.false
disableEditbooleannoDisables edit button for the item.false
disableDeletebooleannoDisables delete button for the item.false
editButtonTooltipstringnoTooltip string for edit button.
deleteButtonTooltipstringnoTooltip string for delete button.

icons available

list view custom

onItemClick()

function onItemClick(event<Object>)

Triggered when an item is clicked. Passes the item and column clicked in the event parameter.

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesContains information for clicked item.

event

NameTypeRequiredDescriptionDefault
itemobjectyesItem that has been clicked.
columnobjectyesColumn that has been clicked.
targetKeystringyesColumn key of the item that has been clicked.
const options = {
settings: {
contentMapping: {
idKey: "id",
columns: [{ titleKey: "title" }]
}
}
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.onItemClick = (event) => {
console.log(event);
}

onItemActionClick()

function onItemActionClick(event<Object>)

Triggered when an item's action is clicked. Passes the item and action in the event parameter.

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesContains information for clicked item.

event

NameTypeRequiredDescriptionDefault
itemobjectyesItem that has been clicked.
actionIdobjectyesClicked action of the item that has been interacted with.
const options = {
settings: {
contentMapping: {
idKey: "id",
columns: [{ titleKey: "title" }]
}
}
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.onItemActionClick = (event) => {
console.log(event);
}

onSearchInput()

function onSearchInput(searchValue<String>)

Triggered when the user types in something in the search bar.

danger

This handler will not be invoked if onDataRequest is being used

Event

NameTypeRequiredDescriptionDefault
searchValuestringyesContains the search value.
const options = {
settings: {
showSearchBar: true,
contentMapping: {
idKey: "id",
columns: [{ titleKey: "title" }]
}
}
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.onSearchInput = (searchValue) => {
console.log(searchValue);
}

onSortOptionChange()

function onSortOptionChange(option<Object>)

Triggered when the user selects the sort option from the sort options dropdown.

danger

This handler will not be invoked if onDataRequest is being used

Options

NameTypeRequiredDescriptionDefault
optionstringyesContains the choosen sort option.
const options = {
settings: {
showSortOptions: true,
contentMapping: {
idKey: "id",
columns: [{ titleKey: "title" }]
}
}
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.onSortOptionChange = (option) => {
console.log(option);
}

Examples

Using with onDataRequest

const items = [
{
"id": "6489fe794feadf03a7df37cc",
"data": {
"createdOn": "05/06/2023",
"isActive": false,
"imageUrl": "http://placehold.it/32x32",
"title": "Bridgett Lara",
"subtitle": "SNIPS",
"address": "362 Utica Avenue, Beaulieu, Oklahoma, 4949",
"manualOrder": 0
}
},
{
"id": "6489fe79fb32d8039fdc4c94",
"data": {
"createdOn": "05/06/2023",
"isActive": true,
"imageUrl": "http://placehold.it/32x32",
"title": "Cameron Mayer",
"subtitle": "EXOTERIC",
"address": "421 Beaumont Street, Linwood, North Carolina, 913",
"manualOrder": 1
}
},
{
"id": "6489fe794feadf03a7df37cd",
"data": {
"createdOn": "05/06/2023",
"isActive": true,
"imageUrl": "http://placehold.it/32x32",
"title": "Carla Wilkinson",
"subtitle": "COMVEY",
"address": "820 Virginia Place, Tryon, Indiana, 1631",
"manualOrder": 2
}
}
];

const options = {
appearance: {
title: 'Control List View',
info: "Some description of the control list",
addButtonText: "Add Feed",
addButtonStyle: "outlined",
itemImageEditable: false,
},
addButtonOptions: [
{ title: "Add New" },
],
settings: {
allowDragAndDrop: true,
showSearchBar: true,
showSortOptions: true,
showAddButton: true,
showEditButton: true,
showDeleteButton: true,
contentMapping: {
idKey: "id",
manualOrderKey: "data.manualOrder",
columns: [
{ imageKey: "data.imageUrl" },
{ titleKey: "data.title", subtitleKey: "data.subtitle" },
{ dateKey: "data.createdOn", anchorKey: "data.address" },
{ toggleKey: "data.isActive" }
],
}
},
sortOptions: [
{ title: "Newest First", },
{ title: "Oldest Z-A", default: true }
]
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.onDataRequest = (event, callback) => {
callback(items);
};

controlListView.onItemRender = (event, callback) => {
let presetOptions = {
disableDelete: true,
disableEdit: false
};

let actions = [
{ actionId: "calendar", icon: "calendar", theme: "primary", disabled: true },
{ actionId: "graph", icon: "graph", theme: "primary" }
];

return { actions, presetOptions };
};

Using without onDataRequest

 const options = {
appearance: {
title: 'Control List View',
info: "Some description of the control list",
addButtonText: "Add Feed",
addButtonStyle: "outlined",
itemImageEditable: false,
},
addButtonOptions: [
{ title: "Add New" },
],
settings: {
allowDragAndDrop: true,
showSearchBar: true,
showSortOptions: true,
showAddButton: true,
showEditButton: true,
showDeleteButton: true,
contentMapping: {
idKey: "id",
manualOrderKey: "data.manualOrder",
columns: [
{ titleKey: "title" },
],
}
},
sortOptions: [
{ title: "Newest First", },
{ title: "Oldest Z-A", default: true }
]
}

let controlListView = new buildfire.components.control.listView("#listView_container", options);

controlListView.onItemRender = (event, callback) => {
let presetOptions = {
disableDelete: false,
disableEdit: false
};

let actions = [
{ actionId: "calendar", icon: "calendar", theme: "primary", disabled: true },
{ actionId: "graph", icon: "graph", theme: "primary" }
];

return { actions, presetOptions };
};

controlListView.append([
{ id: 1, title: "John Smith" },
{ id: 2, title: "Will Smith" }
]);

controlListView.onSortOptionChange = (option) => {
console.log(option);
}

controlListView.onSearchInput = (searchValue) => {
console.log(searchValue);
}