A typical list will be created used like this:

...
private BeanListWidget myList;
...
protected void init() {
  ...
  myList = new BeanListWidget(MyModel.class);

  myList.setOrderableByDefault(true);
  myList.addField("name", "#Name").like();
  myList.addField("surname", "#Surname").like();
  myList.addField("phone", "#Phone no").like();
  myList.addField("birthdate", "#Birthdate").range();
  ...
  myList.setInitialOrder("name", true);
  myList.setListDataProvider(new MyListDataProvider());  
  addWidget("myList", myList);
  ...
}
...

Note that here we basically do following things:

Now that we have created the list we show how to build a simple data provider. The following example code should be in the same widget as the previous:

...
private class MyMemoryBasedListDataProvider extends MemoryBasedListDataProvider {
  protected MyMemoryBasedListDataProvider() {
    super(MyModel.class);
  }
  public List loadData() throws Exception {             
    return lookupMyService().findAllMyModel();
  }
}
...

The line super(MyModel.class) associated this MemoryBasedListDataProvider with the JavaBean model class MyModel. The method List loadData() implements loading all table rows and returning it as a List object.

Later, we will also discover using org.araneaframework.uilib.list.dataprovider.BackendListDataProvider.

As the list may be displayed as a table, it is basically an ordered collection of items. In the previous example, we defined a list of MyModel.class typed items that have fields 'name', 'surname', 'phone' and 'birthdate'. By listing of MyModel.class, we also told ListWidget the corresponding field types, e.g String.class, String.class, Long.class and Date.class. In fact this feature of reflection is the only distinction between the ListWidget and BeanListWidget.

Each list field have its own Id, label and type. The labels are used to automatically create a corresponding title row above the displayed table. The types are used to describe how to order or filter the whole data using this field. E.g String.class is treated differently than other types, because usually one would prefer to order by this field ignoring the case. Both the labels and types are also used to build a corresponding search form - an automatically built FormWidget - for the list.

If we would like to add some list fields that are not MyModel.class fields, we can pass it's type to the ListWidget like following:

myList.addField("income", "#Income", BigDecimal.class);

Here the myList could be just a ListWidget rather than a BeanListWidget.

When adding a list field, we can also provide this field-related ordering and filtering information.

Each list field can be orderable or not. We already discovered ListWidget's method setOrderableByDefault(boolean) that switch whether to configure fields that are added afterwards orderable or not. This method can be used several times in the list configuration.

Another way is to set each field individually orderable or not when they are added to the list. In such case add additional boolean argument to the addField() method such as:

myList.addField("phone", "#Phone no", false);

Notice the false as third parameter. true means that the list can be ordered by this field and false means the opposite. By not providing this parameter, simply the last value is used which has been set by setOrderableByDefault(boolean) method.

In addition, we already used method setInitialOrder(String, boolean). It sets a specified field (the first argument) to be ordered by default. true as the second argument tells the ordering should be ascending, false would mean descending. By not providing this information, the list is displayed in the original order.

Filtering means that we only display a certain list items. The list can be filtered using its fields and data provided by the search from of this list.

For this, we must provide the ListWidget with the corresponding org.araneaframework.uilib.list.structure.ListFilters and FormElements. As the form elements are dummy "boxes" that hold search data, each ListFilter is related to a certain filter test, e.g. equality, greater than comparison etc. Each ListFilter also knows what information it must consider. In general, one list field is compared against a value provided by the search form. It's also assumed that a blank search field means that this particular ListWidget is currently disabled.

Fortunately, in most cases it's unnecessary to add these search fields manually. Instead, if one is adding a list field, he or she can assign both the ListFilter and FormElement for this field very simply:

myList.addField("address", "#Address").like();

Here we simply add an 'Address' field providing it with label and telling there's should be a Like filter for this field. By this, we automatically add a TextControl into the search form. By filling it with value 'Paris', we will see only rows which 'Address' field contain 'Paris', 'paris', 'PARIS' etc.

To describe, how this works, we show a longer version of the previous code:

myList.addField("address", "#Address");
myList.getFilterHelper().like("address");

So there's a special class org.araneaframework.uilib.list.structure.filter.FilterHelper that is used to add list filters. All ListWidget.addField() methods just return a little different version of this helper class, called a FieldFilterHelper. It's methods do not need a field Id and thus make one not to repeat the same field Id for each filter. In general, the shorter usage is recommended of course. However some filters are more complicated and may be related to more than one list field. For those, one must use the FilterHelper instead.

By default all filters that deal with the Strings are case insensitive. To configure some filters to be different, use the following:

myList.addField("country", "#Country").setIgnoreCase(false).like();
myList.addField("city", "#City").like();
myList.addField("address", "#Address").setIgnoreCase(true).like();

This can be explained following: Before adding a Like filter for the 'country' field, we switched to the case sensitive mode. And before adding a filter for the 'address' field, we switched to the case insensitive mode. Thus the city's filter is case sensitive as the country's but the address' filter does ignore the case.

This state is held by the FilterHelper and can be modified either by calling a method of the FilterHelper or the FieldFilterHelper. In such way, the following parameters can be set:

Now, let's show which filters we have got:

By default the FormElements added into the search form have the same identifiers as the list fields. Therefore there can be only one search field per list field. If one would like to override the used Id for FormElement, any filter could be added like following:

        myList.addField("country", "#Country").like();
        myList.getFilterHelper().like("country", "anotherCountry");

The first line adds a list field 'country' and a Like filter associated with it as well as a new FormElement with Id of 'country'. The second line adds another Like filter associated to the list field 'country' and a new FormElement with Id of 'anotherCountry'.

By adding a filter, the corresponding FormElement is automatically created and added to the search form of the list. Now we cover the properties of the few FormElement describing their default values and showing how to customize them:

The xxx marks any filter adding method. As one can count, there are 6 overridden methods for each list filter: 2 versions for providing a custom Id or not and 3 versions for providing a custom FormElement, Control or neither of them. In addition there are methods that start with an _ for disabling adding a form element. Using the FilterHelper instead of FieldFilterHelper is analogous except all filter adding methods take the list field Id as the first argument in addition.

It's import to notice that xxxxConst methods do not create a form element because they are independent of the search form at all - they are constant. However they can actually take a value Id for the defined constants as well. These Ids can be used later to convert specific values when creating a database query. Of course non-constant filters have the same Ids but just use them mainly to get values from the search form. xxxxConst filters have 2 overridden add methods depending on whether the custom value Id is provided or not. By default it's the same as the field Id.

Now that we have demonstrated defining lists and also creating MemoryBasedListDataProvider, we will discover using BackendListDataProvider. The following example code should be in the same widget as constructing of the related ListWidget.

...
private class MyBackendListDataProvider extends BackendListDataProvider {
  public MyBackendListDataProvider() {
    super(true);
  }
  protected ListItemsData getItemRange(ListQuery query) throws Exception {
    return lookupMyService().findMyModel(query);
  }
}
...

The line super(true) constructs BackendListDataProvider with cache enabled (only used when there are no change in query). Notice that there is no association with any JavaBean class here. The method ListItemsData getItemRange(ListQuery query) implements loading current item range according to the range indexes and filtering and ordering conditions. org.araneaframework.backend.list.mode.ListQuery and org.araneaframework.backend.list.mode.ListItemsData may be thought as being input and output of each list data query.

ListQuery is a simple JavaBean that holds the following properties:

Generally, this whole object is just passed to org.araneaframework.backend.list.helper.ListSqlHelper class that is used to generate SQL statements and fetching the results from database. Latter is hold in ListItemsData object which is a simple JavaBean that holds the following properties:

Notice that BackendListDataProvider actually do not depend on using databases. It just provides a simple query object and expects a simple result to be returned. Thus, you have the power to use it as you like. At the same, Aranea provides a very useful class org.araneaframework.backend.list.helper.ListSqlHelper that generate SQL statements and fetches the results from database. We strongly recommend it together with its subclasses that support different database systems. Currently Oracle (OracleListSqlHelper) and HSQL (HsqlListSqlHelper) databases are supported.

The following example discovers the simplest usage of ListSqlHelper. The following code should be in a service class instead of previously discovered Widget:

public class MyService {
  ...
  private DataSource dataSource;
  ...
  public ListItemsData findMyModel(ListQuery query) {
    ListSqlHelper helper = new OracleListSqlHelper(this.dataSource, query);

    helper.addMapping("name", "NAME");
    helper.addMapping("surname", "SURNAME");
    helper.addMapping("phone", "PHONE_NO");

    helper.setSimpleSqlQuery("PERSON");
    return helper.execute(MyModel.class);
  }
  ...
}

Method ListItemsData findMyModel(ListQuery query) does the following:

The following example discovers the custom usage of ListSqlHelper.

public class MyService {
  ...
  private DataSource dataSource;
  ...
  public ListItemsData findMyModel(ListQuery query) {
    ListSqlHelper helper = new OracleListSqlHelper(this.dataSource, query);

    helper.addMapping("name", "NAME");
    helper.addMapping("surname", "SURNAME");
    helper.addMapping("phone", "PHONE_NO");

    StringBuffer s = new StringBuffer();
    s.append("SELECT ");
    s.append(helper.getDatabaseFields());
    s.append(" FROM PERSONS");
    s.append(helper.getDatabaseFilterWith(" WHERE ", ""));
    s.append(helper.getDatabaseOrderWith(" ORDER BY ", ""));

    helper.setSqlQuery(s.toString());
    helper.addStatementParams(helper.getDatabaseFilterParams());
    helper.addStatementParams(helper.getDatabaseOrderParams());

    return helper.execute(MyModel.class);
  }
  ...
}

Method ListItemsData findMyModel(ListQuery query) does the following:

Starts a list context. List view model, list sequence view model and list id are made accessible to inner tags as EL variables.

<?xml version="1.0" encoding="UTF-8"?>
<ui:list id="list">
    ...
</ui:list>

Represents list filter. Introduces an implicit form (<ui:form>), so one can place form elements under it.

This tag has no attributes.

<?xml version="1.0" encoding="UTF-8"?>
<ui:list id="list">
  <ui:listFilter>
    <ui:row>
        <ui:cell>
            <ui:textInput id="field1Filter"/>
        </ui:cell>
    
        <ui:cell>
            <ui:textInput id="field2Filter"/>
        </ui:cell>

        ...

    </ui:row>
  </ui:listFilter>
</ui:list>

<ui:listFilterButton> renders list's filter form filtering activation button and registers a keyboard handler, so that pressing ENTER key in any filter form field activates list filtering. <ui:listFilterClearButton> renders list's filter form clearing button, pressing it sends server-side event that clears all active list filters.

Both of these tags must be used inside <ui:listFilter> tag.

<?xml version="1.0" encoding="UTF-8"?>
...
  <ui:listFilter>
    <ui:row>
      <!-- Bunch of filter fields in cells -->
      <ui:cell>
        <ui:listFilterButton/>
        <ui:listFilterClearButton/>
      </ui:cell>
    <ui:row>
  </ui:listFilter>

Iterating tag that gives access to each row on the current list page. The row is by default accessible as EL variable row.

<?xml version="1.0" encoding="UTF-8"?>
<ui:list id="list">
  <ui:listFilter>
    ...
  </ui:listFilter>
  
  <ui:listRows>
    <ui:row>
        <!-- In each row, object in this list row is accessible -->
        <ui:cell>
            <c:out value="${row.field1}"/>
        </ui:cell>

        <ui:cell>
            <c:out value="${row.field2}"/>
        </ui:cell>

        ...
    </ui:row>
  </ui:listRows>
</ui:list>

Represents an HTML form button (not tied to any Control or FormElement). Default styleClass="aranea-button", rendered with HTML <button ...> tag.

Represents a HTML link with an onClick JavaScript event. Default styleClass="aranea-link-button", rendered with HTML <a href="javascript:" ...> tag.

<?xml version="1.0" encoding="UTF-8"?>
<ui:list id="list">
  ...  
  <ui:listRows>
    <ui:row>
      ...
      <ui:cell>
        <ui:listRowLinkButton eventId="edit">
          <img src="editButton.png"/>
        </ui:listRowLinkButton>
      </ui:cell>
      ...
    </ui:row>
  </ui:listRows>
</ui:list>