Skip to main content

buildfire.components.listView

The listView component provides a consistent tool to display lists of items featuring a search bar, custom header content, item image shapes, actions, item content, and more.

list view basic                        list view custom

Requirements

Widget

<head>
<!-- CSS -->
<link rel="stylesheet" href="../../../styles/components/listView@2.0/listView.css" />

<!-- JS -->
<script src="../../../scripts/buildfire.min.js"></script>
<script src="../../../scripts/buildfire/components/listView@2.0/listView.js"></script>
</head>

In your widget body create html container element for list view items.

<body>
<div id="listViewContainer"></div>
</body>

Methods

const listView = new buildfire.components.listView(selector, options);

ListView class constructor method which initializes the list view component.

const listView = new buildfire.components.listView('#listViewContainer');

listView()

Arguments

NameTypeRequiredDescriptionDefault
selectorstringyesCSS selector of element that will contain component
optionsobjectnooptions object

options

NameTypeRequiredDescriptionDefault
settingsobjectnosettings object
translationsobjectnotranslations object

settings

NameTypeRequiredDescriptionDefault
showSearchBarbooleannoHides or shows the search bartrue
itemImagestringnoSpecifies the shape of the item image circle, square, avatar, nonecircle
headerContentstringnoCustom HTML elementsnull
paginationEnabledbooleannoIf pagination is enabled onDataRequest provides the page and the pageSizefalse
paginationOptionsobjectnopaginationOptions object
contentMappingobjectnocontentMapping object
customListActionobjectnocustomListAction object
enableReadMorebooleannoSpecifies whether the description text should be truncated or nottrue
maxHeightnumbernoSpecifies the maximum height of the componentnull

paginationOptions

NameTypeRequiredDescriptionDefault
pagebooleannoSpecifies the starting page for the data0
pageSizestringnoSpecifies the page size for the data10

contentMapping

NameTypeRequiredDescriptionDefault
idKeystringyesSpecifies the id field of the itemid
imageKeystringnoSpecifies the image field for the itemimageUrl
titleKeystringnoSpecifies the title field for the itemtitle
subtitleKeystringnoSpecifies the subtitle field for the itemsubtitle
descriptionKeystringnoSpecifies the description field for the itemdescription

customListAction

note

Using customListAction disables passing actions to the list using the onItemRender handler.

NameTypeRequiredDescriptionDefault
htmlhtmlyesHTML Element to be appended

translations

NameTypeRequiredDescriptionDefault
readMorestringnoSpecifies the text for the read more buttonRead More
readLessstringnoSpecifies the text for the read less buttonRead Less
emptyStateMessagestringnoSpecifies the empty state message below the empty state imageNo Items Yet
searchInputPlaceholderstringnoSpecifies the text placeholder in the search barSearch

append()

listView.append(items, appendToTop)

Appends an item or many items to the list view

const listView = new buildfire.components.listView('#listViewContainer', options);

listView.append([
{
id: '1',
title: 'buildfire',
imageUrl: 'https://via.placeholder.com/150',
subtitle: 'The Most Powerful App Maker For iOS & Android',
description: 'BuildFire’s powerful and easy to use mobile app builder...'
}
]);

Arguments

NameTypeRequiredDescriptionDefault
items[object]objectyesArray of items, or single item to be appended to list view.
appendToTopbooleannofalseSpecifies whether items should be applied to the top or the bottom of the list

update()

listView.update(id, data)

Updates an item and re-renders it in the list

const listView = new buildfire.components.listView('#listViewContainer', options);

listView.update(1, {
id: 1,
imageUrl: 'https://via.placeholder.com/150',
title: 'John Doe',
subtitle: 'CEO',
description: 'Owner of the company'
});

Arguments

NameTypeRequiredDescriptionDefault
idstringyesObject id
dataobjectyesObject to be updated

remove()

listView.remove(id)

Removes an item from the list view

const listView = new buildfire.components.listView('#listViewContainer');

listView.remove(1);

Arguments

NameTypeRequiredDescriptionDefault
idstringyesObject id

clear()

listView.clear()

Clears the list view

const listView = new buildfire.components.listView('#listViewContainer', options);

listView.clear();

refresh()

listView.refresh()

Refreshes the component to apply new options provided

const listView = new buildfire.components.listView('#listViewContainer', options);

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

reset()

listView.reset()

Refreshes the component to apply new options provided and re-renders current items in the list

const listView = new buildfire.components.listView('#listViewContainer', options);

listView.reset();

Handlers

The following event handlers can be assigned:

onDataRequest(event, callback)

Triggered when the component loads for the first time, when the user scrolls to the bottom and requests the next page, or when the user is using the search bar. If you don't want to use this handler you can populate the list using the append method.

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesholds search value and pagination options if pagination is enabled
callbacknumbernoprovides callback to retrieve items back to component for render

Event

NameTypeRequiredDescriptionDefault
searchValuestringyesholds search value from the search barnull
pagenumbernoIf pagination is enabled provides the needed page for the pending fetch0
pageSizenumbernoIf pagination is enabled provides the specified pageSize10

Callback

NameTypeRequiredDescriptionDefault
itemsarrayyesarray of items that need to be rendered inside the component

onItemRender(event)

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

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesevent object

Event

NameTypeRequiredDescriptionDefault
itemstringyesitem that component is currently rendering

Example

Provides return statement to retrieve actions and custom content for a specific item.


listView.onItemRender = (event) => {
let actions = [
{ actionId: 'remove', text: 'Remove item' },
{ actionId: 'update', text: 'Update item' },
];

if(event.item.age > 36) actions.push({ actionId: 'call', text: 'Call' });

let customContent = 'Some custom content';

return { actions, customContent };
}
NameTypeRequiredDescriptionDefault
actionsarraynoarray of action objects
customContentstringnocustom content for the item that will appear below the description

onItemRendered(event)

Triggered every time after an item is rendered, you can use this handler to execute javascript for the custom content.

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesevent object

Event

NameTypeRequiredDescriptionDefault
itemstringyesitem that component is currently rendering
htmlhtmlyesHTML container for the rendered item

Example

You can use this handler to execute any functionality needed after the item has been rendered.

listView.onItemRendered = (event) => {
if (event.item.data.age > 33)
buildfire.components.ratingSystem.injectRatings();
}

onRenderEnd(event)

Triggered every time after the component has done rendering batch of items.

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesevent object

Event

NameTypeRequiredDescriptionDefault
itemsarrayyesContains array of rendered items
containershtmlyesContains array of html containers for rendered items

Example

You can use this handler to execute any functionality needed after the item has been rendered.

listView.onRenderEnd = (event) => {
//do your logic here
}

onItemClick(event)

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

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesevent object

Event

NameTypeRequiredDescriptionDefault
itemobjectyesItem clicked
targetstringyesSpecifies what part of the item has been clicked title, subtitle, action
note

Using customListAction will pass action as a target parameter.

Example

listView.onItemClick = event => {
console.log('onItemClick', event);
}

onItemActionClick(event)

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

Arguments

NameTypeRequiredDescriptionDefault
eventobjectyesevent object

Event

NameTypeRequiredDescriptionDefault
itemobjectyesitem interacted with
actionobjectyesaction clicked

onSearchInput(searchValue)

Triggered when the users 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.

Example

listView.onSearchInput = (searchValue) => {
console.log('onSearchInput', searchValue);
}

Examples

Using ListView with pagination enabled

Example 1

Using the component with pagination enabled, the component will take care of which page is next to be fetched.

Code

let listView = new buildfire.components.listView("#listViewContainer", {
settings: {
itemImage: 'circle',
paginationEnabled: true,//we enable pagination
paginationOptions: {
page: 0,
pageSize: 5//we set our custom page size
},
contentMapping: {
titleKey: 'data.title',
subtitleKey: 'data.subtitle',
imageKey: 'data.imageUrl',
descriptionKey: 'data.description',
}
}
});

listView.onDataRequest = (event, callback) => {
let searchOptions = {
limit: event.pageSize,
skip: event.page * event.pageSize,
sort: { title: 1 }
}

event.searchValue ? searchOptions.filter = { "$json.title": { $regex: event.searchValue, $options: 'i' } } : null;

getData(searchOptions, (result) => {
callback(result);
});
}

listView.onItemRender = event => {
let actions = [
{ actionId: 'call', text: 'Call' },
{ actionId: 'email', text: 'Email' }
];
if (event.item.age > 36)
actions.push({ actionId: 'remove', title: 'Remove' });

let customContent = "Some custom content...";
return { actions, customContent };
}

listView.onItemActionClick = (event) => {
if (event.action.actionId == 'remove')
listView.remove(options.item.id);
}
Example 2

Using with pagination disabled

Using the component with pagination disabled will not pass page and pageSize in the options parameter of the onDataRequest handler.

Code

let listView = new buildfire.components.listView("#listViewContainer", {
settings: {
itemImage: 'circle',
contentMapping: {
titleKey: 'data.title',
subtitleKey: 'data.subtitle',
imageKey: 'data.imageUrl',
descriptionKey: 'data.description',
}
}
});

listView.onDataRequest = (event, callback) => {
getData(event.searchValue, (result) => {
callback(result);
});
}

listView.onItemClick = event => {
event.item.data.title = 'You clicked me';
event.item.data.description = 'Nothing much to see here';
event.item.data.imageUrl = 'https://via.placeholder.com/150';
event.item.data.age = 33;
listView.update(event.item.id, event.item);
}
Example 3

Using without onDataRequest

Using the component without the onDataRequest handler you will need to populate the component using the append method.

Code

let listView = new buildfire.components.listView("#listViewContainer", {
settings: {
itemImage: 'circle',
contentMapping: {
titleKey: 'data.title',
subtitleKey: 'data.subtitle',
imageKey: 'data.imageUrl',
descriptionKey: 'data.description',
}
}
});

listView.append({
id: "someId",
data: {
title: "John Smith",
subtitle: "Developer",
description: "Javascript developer"
}
});

listView.onSearchInput = (event) => {
getData(event.searchValue, (result) => {
listView.clear();
listView.append(result);
});
}

Example 4

Using with customListAction

In this example, we are using the component with the customListAction feature which disables passing actions in the onItemRender handler.

Code

let listView = new buildfire.components.listView("#listViewContainer", {
settings: {
itemImage: 'square',
contentMapping: {
titleKey: 'data.title',
subtitleKey: 'data.subtitle',
imageKey: 'data.imageUrl',
descriptionKey: 'data.description',
},
customListAction: {
html: `<i class="material-icons">chevron_right</i>`,
}
}
});

listView.onDataRequest = (event, callback) => {
getData(event.searchValue, (result) => {
callback(result);
});
}

listView.onItemClick = event => {
if(event.target === 'action') {
//do something
}
}