EntityListView

EntityListView

<entityList> • javadoc

Synopsis

A UI component for displaying an EntityList.

Usage

<entityList [provider="com.example.myapp.providers.SampleProvider.class"]
    [model="someEntityList"]
    [animateInsertions="true|false"]
    [animateRemovals="true|false"]
    [scrollableY="true|false"]
    [listLayout="Y|Grid"]
    [columns="1|2|...|n"]
    [landscapeColumns="1|2|...|n"]
    [refreshAction="SOME_ACTION_CATEGORY"]
    [loadMoreAction="SOME_ACTION_CATEGORY"]
    [addAction="SOME_ACTION_CATEGORY"]
    [selectAction="SOME_ACTION_CATEGORY"]
    [removeAction="SOME_ACTION_CATEGORY"]
    [renderer="myEntityCellRenderer"]
    [listViewFactory="myEntityListViewFactory"]>
    [
        <row-template case="java boolean expression">
            ... row content
        </row-template>
    ]
</entityList>

The simplest form of <entityList> EntityList as its model attribute, and renders it using a default renderer, which just renders a label for each row. E.g.

<entityList model="someEntityList"/>

In most cases, it is better to use the provider attribute to specify a provider class, which is used to load the row data, include at least one <row-template> child tag to specify how each row should be rendered. E.g.

<entityList layout-constraint="center"
        provider="com.codename1.rad.sampler.providers.SampleListProvider.class"
    >
    <row-template>
        <border uiid="SampleListRow">
            <profileAvatar size="1.5rem" layout-constraint="west"/>
            <radLabel tag="Person.name" layout-constraint="center"
                      component.allStyles.font="native:MainRegular 1rem"
                      component.allStyles.marginLeft="1rem"
            />

        </border>
    </row-template>
</entityList>

For the provider attribute to work, you also need to implement a provider, and register it with the controller. The provider for the above snippet looks like:

package com.codename1.rad.sampler.providers;

import com.codename1.io.Log;
import com.codename1.rad.io.ResultParser;
import com.codename1.rad.models.AbstractEntityListProvider;
import com.codename1.rad.models.EntityList;
import com.codename1.rad.models.EntityListProvider;
import com.codename1.rad.sampler.models.UserProfile;
import com.codename1.rad.sampler.models.UserProfileImpl;
import com.codename1.ui.CN;

import java.io.IOException;

import static com.codename1.ui.CN.scheduleBackgroundTask;

public class SampleListProvider extends AbstractEntityListProvider {
    @Override
    public Request getEntities(Request request) {

        EntityList out = new EntityList();
        {
            UserProfile profile = new UserProfileImpl();
            profile.setName("Steve Hannah");
            profile.setEmail("steve@example.com");
            out.add(profile);
        }
        {
            UserProfile profile = new UserProfileImpl();
            profile.setName("Shai Almog");
            profile.setEmail("shai@example.com");
            out.add(profile);
        }
        {
            UserProfile profile = new UserProfileImpl();
            profile.setName("Chen Fishbein");
            profile.setEmail("chen@example.com");
            out.add(profile);
        }
        request.complete(out);
        return request;
    }

}

And it is registered in the controller code like:

@Override
protected void onStartController() {
    super.onStartController();
    addLookup(new SampleListProvider());
}

Attributes

Tip	See EntityListViewBuilder javadoc and EntityListView javadoc for definitive list of available attributes.

addAction

A Category from which to load the "Add" action. If the controller registers an action in this category will case a FAB (floating action button) to be rendered over the list to "add" a row to the list, and pressing this button will trigger that action.

animateInsertions

Whether to animate insertions into the list. true|false.

animateRemovals

Whether to animate removals into the list. true|false.

columns

Used in conjunction with listLayout="Grid", this specifies the number of columns to use in the layout. Expects an integer (or java expression resolving to an integer).

landscapeColumns

Used in conjunction with listLayout="Grid", this specifies the number of columns to use in the layout when in Landscape mode. Expects an integer (or a java expression resolving to an integer).

listLayout

Specifies the layout type for the list. Possible values: Y or Grid

listViewFactory

Specifies an EntityListViewFactory to use for creating rows. Don’t use this attribute if you are using the <row-template> tag.

loadMoreAction

A Category from which to load the "Load more" action. If an action is registered in the controller with this category, then the action will be triggered when the user scrolls to the bottom of the list. Only use this if you want to override the load more behaviour. The default behaviour is to load more records from the provider (if the provider is set). If you customize this option, then it may break the default provider flow for loading rows.

model

An EntityList to use for the list model. This can be used to "preload" an entitylist for rendering. If used in conjunction with the provider attribute, then the provided model will still be used, but its contents will be replaced by the contents returned by the provider.

provider

Specifies a provider that can be used to fill the list. This can take either a Class literal (e.g. com.example.MyProvider.class), which will result in a "lookup" to find the provider from the controller, or an EntityListProvider object.

refreshAction

A Category from which to load the "Refresh" action. If an action is registered in the controller with this category, then the action will be triggered when the user initiates a "pull-to-refresh" gesture on the list. Only use this if you want to override the refresh behaviour. The default behaviour is to load records from the provider (if the provider is set). If you customize this option, then it may break the default provider flow for loading rows.

removeAction

A Category to trigger when the user issues a "remove" event on the list.

renderer

An EntityListCellRenderer to use for rendering the rows of the list. Do not use this if you are using the <row-template> tag to specify the row format.

scrollableY

Boolean value indicating whether the list should be scrollable.

selectAction

A Category to trigger when the user selects a row of the list.

Row Templates

The <row-template> tag can be used to specify how rows of the list should be rendered. You can provide zero or more <row-template> tags as direct children of the <entityList> tag. If more than one is provided, then the case attribute of the <row-template> will be used to determine which should be used for any given row. The first template where the java expression inside the case attribute resolves to true is used.

The <row-template> tag should contain exactly one child component, which will be used as the row itself. Usually this child would be a container (e.g. <y>, <border>, etc…​), but it could also just be a simple component like a <label>.

Row Environment

The following variables are available inside the <row-template> tag for use in Java expressions (either inside <script> tags, or attributes containing java expressions):

boolean rowFocused

Indicates whether the current row is focused.

int rowIndex

The zero-based index of the current row.

EntityList rowList

Refers to the parent EntityList component.

Entity rowModel

Refers to the view model for the current row.

boolean rowSelected

Indicates whether the row being rendered is selected or not.

EntityView rowView

Refers to the EntityView for the current row.

ViewContext subContext

A view context with the rowModel, and the row’s ViewController (if specified).