Using ListView with UI Editor

Overview

This guide is applicable for using UI editor on both ListView and GridView. It is advised to check them for more detailed guide.

Designing ListViewItem

  • Go to the toolbox, drag&drop a ListViewItem and perform your design inside that component. For more information please refer to our library guide.

  • Ensure that Show In Toolbox is set to true

Using ListViewItem

  • Go to Page Design from Explorer

  • From the BUILT-IN COMPONENTS drag&drop the ListView inside your page

  • Double click the ListView component to enable edit mode

  • From the toolbox menu go to the "My Components" section

  • Insert your newly created UI.ListViewItem by Drag & Drop.

Using more than one ListViewItem type

On UI Editor, Smartface Cloud IDE only supports using one UI.ListViewItem type by Drag & Drop.

After Dragging & Dropping your UI.ListViewItem, adjust rowHeight and itemCount to your needs.

Adapting ListView to ListViewItem

Setting itemCount

itemCount determines how many items is going to be shown on UI.ListView, therefore this property needs to be changed when related dataset changes.

contentInset and contentOffset

Since padding will not work on UI.ListViewItem, you might want to leave extra space only on the latest or the first item. You can use contentInset or contentOffset on such cases. Using UI editor with class is recommended by Smartface, to keep the code clean.

Important

When defining contentInset and contentOffset , make sure that you define both bottom and top, even if you are not using one of them. Only defining one of them might cause unexpected behaviors.

Coding ListViewItem

  • When a component is created on library pane by using Reusable Component Libraries a file that contains component code like scripts/components/ListViewItem1.js is created.

  • While using your newly added layouts ( e.g. changing text ), it is crucial to encapsulate inner layouts and define them as properties by using Object.defineProperties. This will help page code to be clean, improve extendibility and maximize reusability. Refer Smartface snippet for ease of usage.

scripts/components/ListViewItem1.js
scripts/components/ListViewItem1.js
const extend = require('js-base/core/extend');
const ListViewItem1Design = require('library/ListViewItem1');
const ListViewItem1 = extend(ListViewItem1Design)(
function(_super, props = {}, pageName) {
_super(this, props);
this.pageName = pageName;
Object.defineProperties(this, {
titleText: {
get: () => this.label1.text || "",
set: (value) => this.label1.text = typeof value === "string" ? value : ""
// E.g. you can check its type to avoid wrong assignments
});
});
module.exports = ListViewItem1;

Adding layouts inside of ListViewItem

If the layout needs to be reached from the code, ensure that the layouts have their Assign to Page variable is set to true

Using ListViewItem on Page with ListView

After the properties and codes are created, it is time to use it on Actual page.

When UI.ListViewItem is added by UI Editor, using onRowCreate callback is not necessary, this will help to keep the code clean.

UI.ListView needs to be initialized, then the data should be defined properly.

By default, Smartface sets rowHeight and itemCount value to something reasonable. To change that, simply set those values inside of initListView() function.

ListView with multiple types

To use more than one Type, use onRowCreate function and add your types from the code. Refer the ListView Guide for details.

scripts/pages/page1.js
scripts/components/ListViewItem1.js
../components/ListViewItem1.json
scripts/pages/page1.js
const ListViewItem1 = require("components/ListViewItem1");
function onLoad(superOnLoad) {
superOnLoad();
const page = this;
page.dataSet = [{
title: "Smartface1"
},{
title: "Smartface2"
}]
page.initListView();
page.refreshListView();
}
function initListView() {
const page = this;
const { listView1 } = page;
listView1.rowHeight = ListViewItem1.getHeight();
listView1.onRowBind = (listViewItem, index) => {
listViewItem.titleText = page.dataSet[index].title; // Recommended way
};
listView1.onPullRefresh = () => {
apiCall()
.then(() => {
page.refreshListView();
})
.finally(() => {
listView1.stopRefresh();
});
};
}
function refreshListView() {
const page = this;
const { listView1 } = page;
listView1.itemCount = page.dataSet.length;
listView1.refreshData();
}
module.exports = Page1;
scripts/components/ListViewItem1.js
const extend = require('js-base/core/extend');
const ListViewItem1Design = require('library/ListViewItem1');
const ListViewItem1 = extend(ListViewItem1Design)(
function(_super, props = {}, pageName) {
_super(this, props);
this.pageName = pageName;
Object.defineProperties(this, {
titleText: {
get: () => this.label1.text || "",
set: (value) => this.label1.text = typeof value === "string" ? value : ""
// E.g. you can check its type to avoid wrong assignments
});
});
module.exports = ListViewItem1;
ListViewItem1.getHeight = () => getCombinedStyle(".listViewItem1").height || 0;
../components/ListViewItem1.json
{
".listViewItem1": {
"height": 80
}
}

Changing dimensions inside of component on runtime

As stated on Context, you need to call applyLayout when a dimension changes. For iOS, only call this on UI.ListViewItem itself.

Tips & Tricks

  • Since the dimensions of UI.ListViewItem is handled differently than the other layouts, assigning dimensional properties like margin, width or height will be ignored and those are handled by UI.ListView. Use a wrapper to cover entire UI.ListViewItem when needed.

  • You can also define any functions you want inside of a component. To do that, define the function outside of the constructor and use Function.prototype.bind() to use them in your scope.

scripts/components/ListViewItem1.js
scripts/components/ListViewItem1.js
const extend = require('js-base/core/extend');
const ListViewItem1Design = require('library/ListViewItem1');
const ListViewItem1 = extend(ListViewItem1Design)(
function(_super, props = {}, pageName) {
_super(this, props);
this.pageName = pageName;
this.clearText = clearText.bind(this);
}
);
function clearText() {
const component = this;
const { label1 } = component;
label1.text = "";
}
module.exports = ListViewItem1;

-For ease of usage, it is advised to set height of UI.ListView by a theme via Using Themes in Apps. Then, you can use getCombinedStyle to access their style from the code. This will also ease the implementation UI.ListView which has multiple types.

Foldering component themes

By default, Smartface Cloud IDE adds new UI themes to common.json file. For better file structure, it is recommended to separate each theme by creating components folder under a different file.