org.universAAL.utilities.api.ui

Class DataTable

java.lang.Object

org.universAAL.utilities.api.ui.Control

org.universAAL.utilities.api.ui.DataTable

All Implemented Interfaces:

IContainer

public class DataTable
extends Control
implements IContainer

Class representing a Data Table UI element. Data Tables show data from a repetitive data model composed by equally structured entries, whether it's a table, list of groups or any other way, depending on the UI renderer.

A Data Table is composed by the Data Model backing up the actual content and an Entry Model defining what is shown from each entry and how. The Entry Model is like a Group, any Control (except Submits or other Data Tables) can be added to it. Each Control added must reference a Path from the entries in Data Model, and must not have an initial value. The Entry Model will be repeated for each entry in the Data Model, and each of its Controls initialized with the data of that Entry found in the given reference Path of the Control.

WARNING: A Data Table is like a Group, it must be added to a SimpleUIRequest or a Group BEFORE any element can be added to its Entry Model. This is because the Tables�s Entry Model is not actually created until it's added. The Data Model however must be set BEFORE the Data Table is added, thus the order of operations is the following: 1) Create Data Table. 2) Set Data Model. 3) Add Data Table to parent. 4) Add Controls to Entry Model.

There are two ways of constructing Data Tables: Inferring the Data Model entries from the parent's root resource or setting the Data Model entries explicitly.

Example render:

 Label ---------------------------------------
      | Control1Label     | Control2Label     |
       ---------------------------------------
      | Control1Render(1) | Control2Render(1) |
       ---------------------------------------
      | Control1Render(2) | Control2Render(2) |
       ---------------------------------------
      | Control1Render(3) | Control2Render(3) |
       ---------------------------------------
                         ...
 

Author:

alfiva

Field Summary

Fields inherited from class org.universAAL.utilities.api.ui.Control

help, hint, label, MY_NAMESPACE, ref

Constructor Summary

Constructors

Constructor and Description
DataTable() Generic empty constructor.
DataTable(String ref) Constructor with the reference of the Table Data Model to be used .
DataTable(String label, Resource[] initialEntries) Constructor without reference of Table Data Model.
DataTable(String ref, String label) Constructor with the reference of the Table Data Model to be used .

Method Summary

Modifier and Type	Method and Description
String[]	add(Control ctrl) Add the given Simple Control UI element to the Table Entry Model.
void	addEntry(Resource entry) Add an entry to the Data Model backing up this Data Table.
String[]	create(Group group) This method is for internal use of utils only.
Resource[]	getEntries() Get the entries of the Data Model backing up this Data Table.
Boolean	isDeletable() Check if entries can be removed by the user.
Boolean	isEditable() Check if entries can be edited by the user.
Boolean	isExpandable() Check if entries can be added by the user.
void	setDeletable(Boolean deletable) Set if entries can be removed by the user.
void	setEditable(Boolean editable) Set if entries can be edited by the user.
void	setEntries(Resource[] entries) Set the entries of the Data Model backing up this Data Table.
void	setExpandable(Boolean expandable) Set if entries can be added by the user.

Methods inherited from class org.universAAL.utilities.api.ui.Control

getHelp, getHint, getLabel, getReference, setHelp, setHint, setLabel, setReference, setReference

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DataTable

public DataTable()

Generic empty constructor. The Data table will be generated with default values (empty).

DataTable

public DataTable(String ref)

Constructor with the reference of the Table Data Model to be used . The reference is a property path, but in this constructor it is simplified as a single String (a single-property path). All other properties of the input are set to defaults (empty). Use method setReference(String[] path) to set a path through several properties. If a root Resource is used in the parent of the Table (to which it is added) then the values reachable through the reference Path from the root will be used as Data Model for the Table.

Example:


Location root=new Location(URI1);
Location adj=new Location(URI2);
root.addAdjacentLocation(adj);
Dialog d=new Dialog(user,"Title",root);
DataTable rp=new DataTable(Location.PROP_IS_ADJACENT_TO);

take into account that the referenced property must allow cardinality > 1

Parameters:

ref - The simple reference identifying the Table Data Model from the parent root. Set to null to auto-generate and not use a Data Model from the root.

DataTable

public DataTable(String ref,
                 String label)

Constructor with the reference of the Table Data Model to be used . The reference is a property path, but in this constructor it is simplified as a single String (a single-property path). All other properties of the input are set to defaults (empty). Use method setReference(String[] path) to set a path through several properties. If a root Resource is used in the parent of the Table (to which it is added) then the values reachable through the reference Path from the root will be used as Data Model for the Table.

Example:


Location root=new Location(URI1);
Location adj=new Location(URI2);
root.addAdjacentLocation(adj);
Dialog d=new Dialog(user,"Title",root);
DataTable rp=new DataTable(Location.PROP_IS_ADJACENT_TO);

take into account that the referenced property must allow cardinality > 1

Parameters:

ref - The simple reference identifying the Table Data Model from the parent root. Set to null to auto-generate and not use a Data Model from the root.

label - The label text that identifies the Table to the user.

DataTable

public DataTable(String label,
                 Resource[] initialEntries)

Constructor without reference of Table Data Model. Instead, the entries are passed explicitly, as an array of Resource elements. All of these elements in the array (the entries) must be of the same class, because their properties will be used by the controls in the Entry Model, for every entry. An automatic reference for the Table will be generated but only to identify it in the response.

Parameters:

label - The label text that identifies the Table to the user.

initialEntries - Array of Resources representing the entries of the Data Model.

Method Detail

create

public String[] create(Group group)

Description copied from class: Control

This method is for internal use of utils only. It creates the actual official universAAL control configured with the properties defined by this class. Once it is created it cannot be modified.

Specified by:

create in class Control

Parameters:

group - The UI group to which the control is being added.

Returns:

An array of Strings representing the property path used to identify the control in the response. This is only of interest for Input Controls. Submits and Triggers have only one String value. If the path has not been set manually by the time this method is called, an automatic one must be generated.

add

public String[] add(Control ctrl)

Add the given Simple Control UI element to the Table Entry Model. Submits and Data Tables ARE NOT ALLOWED and will not be added. The initial value of the Control MUST be null, because the value will be set to the Data Model entry property specified by the reference. The Control�s reference path must follow a valid path starting where the Table�s own path finished. Example:

 (Root) --PROP1-- (ResA) --PROP2-- (ResB)
      _____________
       Table Path      _____________
                        Control Path
 

If the Table used explicit entries instead of a reference path, then the reference of the Controls must start with (or be) one of the properties of the type of Resource used for the explicit entries.

Once the control is added it cannot be modified. Controls are renedered in the same order they are added. Controls that are Containers and can add elements as well, like Group or DataTables, must be added BEFORE other controls can be added to them. Controls that need references, like Inputs (with property paths), or Submits (with IDs) will be given an automatic reference if none was set. This reference will be returned by this method, in the form of an Array of Strings representing the reference: a Path for Inputs, or a single String for Submits IDs.

Specified by:

add in interface IContainer

Parameters:

ctrl - The Simple Control UI element to be added.

Returns:

The Array of Strings representing the reference Property Path for Input Controls, or with a single String for Submits IDs. Returns null if attempted to add a SubmitCmd or DataTable.

isDeletable

public Boolean isDeletable()

Check if entries can be removed by the user.

Returns:

If entries can be removed by the user.

setDeletable

public void setDeletable(Boolean deletable)

Set if entries can be removed by the user.

Parameters:

deletable - If entries can be removed by the user.

isEditable

public Boolean isEditable()

Check if entries can be edited by the user.

Returns:

If entries can be edited by the user.

setEditable

public void setEditable(Boolean editable)

Set if entries can be edited by the user.

Parameters:

editable - If entries can be edited by the user.

isExpandable

public Boolean isExpandable()

Check if entries can be added by the user.

Returns:

If entries can be added by the user.

setExpandable

public void setExpandable(Boolean expandable)

Set if entries can be added by the user.

Parameters:

expandable - If entries can be added by the user.

getEntries

public Resource[] getEntries()

Get the entries of the Data Model backing up this Data Table.

Returns:

An array of Resources representing the entries in the Data Model.

addEntry

public void addEntry(Resource entry)

Add an entry to the Data Model backing up this Data Table. Must be of the same class of those already added.

Parameters:

option - The entry to add to the Data Model.

setEntries

public void setEntries(Resource[] entries)

Set the entries of the Data Model backing up this Data Table. Overrides any previous values.

Parameters:

entries - An array of Resources representing the entries the Data Model.