Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Scout/Concepts/Table"

(first version)
 
(Summary Cell)
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
{{ScoutPage|cat=Component Model}}
 +
 
A table is data structure that can be represented in a {{ScoutLink|Concepts|TablePage|TablePage}} or a {{ScoutLink|Concepts|TableField|TableField}}.
 
A table is data structure that can be represented in a {{ScoutLink|Concepts|TablePage|TablePage}} or a {{ScoutLink|Concepts|TableField|TableField}}.
  
Line 7: Line 9:
 
Table can contains a set of structured data: the structure of the entity is defined by the {{ScoutLink|Concepts|Column|columns}}. Each entity contained in the table is a {{ScoutLink|Concepts|TableRow| row}}. At the intersection of a column and a row is a {{ScoutLink|Concepts|Cell|Cell}}. A Cell describes how the value is represented (displayed text, colors, style, icon...).
 
Table can contains a set of structured data: the structure of the entity is defined by the {{ScoutLink|Concepts|Column|columns}}. Each entity contained in the table is a {{ScoutLink|Concepts|TableRow| row}}. At the intersection of a column and a row is a {{ScoutLink|Concepts|Cell|Cell}}. A Cell describes how the value is represented (displayed text, colors, style, icon...).
  
=== Example ===
+
== Example ==
magine the you want to represent Persons that are structured as followed:
+
Imagine that you want to have a table of persons that are structured as followed:
 
* Name (String)
 
* Name (String)
 
* First name (String)
 
* First name (String)
Line 15: Line 17:
  
 
A such table needs to contains 4 columns :
 
A such table needs to contains 4 columns :
* NameColumn a {{ScoutLink|Concepts|StringColumn|String Column}}  
+
* <code>NameColumn</code> a {{ScoutLink|Concepts|StringColumn|String Column}}  
* FirstNameColumn a {{ScoutLink|Concepts|StringColumn|String Column}}  
+
* <code>FirstNameColumn</code> a {{ScoutLink|Concepts|StringColumn|String Column}}  
* AgeColumn a {{ScoutLink|Concepts|IntegerColumn|Integer Column}}
+
* <code>AgeColumn</code> a {{ScoutLink|Concepts|IntegerColumn|Integer Column}}
* BirthColumn a {{ScoutLink|Concepts|DateColumn|Date Column}}
+
* <code>BirthDateColumn</code> a {{ScoutLink|Concepts|DateColumn|Date Column}}
  
{{note|TODO|Add a Diagram to represent this table}}
+
Here is how this table looks like in the {{ScoutLink|SDK|Explorer View|Explorer View of the SDK}}:
 +
 
 +
[[Image:Scout sdk example table.png]]
  
 
=== Access to the data ===
 
=== Access to the data ===
To access a value of a table, the common pattern is to go throw the column. For example if you want to access the age of a person, at a precise row index r, the code is:
+
To access a value of a table, the common pattern is to go through the column. For example if you want to access the age of a person, at a precise row index r, the code is:
 
<source lang="java">
 
<source lang="java">
 
   private Integer getAgeOfPersonAtRow(int r){
 
   private Integer getAgeOfPersonAtRow(int r){
Line 29: Line 33:
 
   }
 
   }
 
</source>
 
</source>
 +
 +
=== Add a rows in the table ===
 +
The table API (client-side) offers different ways to add rows in the table:
 +
 +
1: One row, with type check on set value. (you get compile error if you change something in your table):
 +
<source lang="java">
 +
ITableRow row = getTable().createRow();
 +
getTable().getNameColumn().setValue(row, "Smith");
 +
getTable().getFirstNameColumn().setValue(row, "John");
 +
getTable().getAgeColumn().setValue(row, 42);
 +
getTable().getBirthDateColumn().setValue(row, DateUtility.parse("14.12.1970", "dd.MM.yyyy"));
 +
getTable().addRow(row, true);
 +
</source>
 +
The second parameter correspond to "mark as inserted". <code>false</code> (default value - if the parameter is omitted) the row will be insterted with a row Status: <code>ITableRow.STATUS_NON_CHANGED</code>. If <code>true</code>, the row will be inserted with the status <code>ITableRow.STATUS_INSERTED</code>.
 +
 +
2: One row as Object[] array.
 +
<source lang="java">
 +
getTable().addRowsByArray(
 +
    new Object[]{"Johnny", "Mcgee", 26, DateUtility.parse("25.05.1986", "dd.MM.yyyy")},
 +
    ITableRow.STATUS_INSERTED);
 +
</source>
 +
The second parameter indicate the status of the new row. <code>ITableRow.STATUS_INSERTED</code> is the default status (it could be omitted in this example).
 +
 +
3: Multiple rows as Object[][] array.
 +
<source lang="java">
 +
getTable().addRowsByMatrix(new Object[][]{
 +
    new Object[]{"Isabella", "Barton", 32, DateUtility.parse("21.01.1980", "dd.MM.yyyy")},
 +
    new Object[]{"Dana", "Reyes", 56, DateUtility.parse("16.08.1956", "dd.MM.yyyy")}
 +
}, ITableRow.STATUS_INSERTED);
 +
</source>
 +
The second parameter indicate the status of the new row. <code>ITableRow.STATUS_INSERTED</code> is the default status (it could be omitted in this example).
 +
 +
For method 2 and 3 you need to be ensure that the array elements order match with the order of your table columns.
 +
 +
=== Delete a row from the table ===
 +
In a Table client-side, you have two ways to remove a row:
 +
* deleteRow(..)
 +
* discardRow(..)
 +
 +
==== deleteRow(..) ====
 +
the row disappear from Table (as expected by the user), but is still present in the table. You can access it with ITableRow#getDeletedRows(). Later if you export the form content in a {{ScoutLink|Concepts|TableData}}, you will get row in the table with the status <tt>ITableHolder.STATUS_DELETED</tt> and you can persist the deletion in the database.
 +
 +
==== discardRow(..) ====
 +
The row is removed from the table and lost. Nothing is sent to the server.
 +
 +
Now if you set {{ScoutProp|AutoDiscardOnDelete}} to <code>true</code> on the table, calling deleteRow(..) is equivalent to discardRow(..).
 +
 +
 +
The semantic of a discarded row is: the row is deleted + there is no modification to commit to the server. The TableField assume there is no modifications. There is no "saveNeeded" status, the user will not be informed that he has pending modifications on the form...
 +
  
 
== TODO ==
 
== TODO ==
 
{{note|TODO| Organize these subsections in section + subsection. Add description }}
 
{{note|TODO| Organize these subsections in section + subsection. Add description }}
  
=== Load the data ===
 
in the page or in the field
 
  
add row
+
=== Display/Hide the data (Organize Table) ===
 +
Table provides support to sort, to filter how the content is represented.
  
  
=== Display/Hide the data ===
+
=== Sorting possibility ===
Table provides support to sort, to filter how the content is represented.
+
properties
  
  
Line 50: Line 103:
 
=== Menu ===
 
=== Menu ===
 
Table can also contains Menus, to provide a possibility to trigger some actions (Menus are displayed in the context menu of the table).
 
Table can also contains Menus, to provide a possibility to trigger some actions (Menus are displayed in the context menu of the table).
 +
  
 
=== Checkable ===
 
=== Checkable ===
  
  
=== Summary Cell, Primary Columns ===
+
=== Summary Cell ===  
 +
 
 +
In outline based application, the child-pages are represented a nodes in the page tree. The cell of this node is defined by the summary cell of the table.
 +
 
 +
The set a column as summary cell, the column must override the following method:
 +
 
 +
<source lang="java">
 +
      @Override
 +
      protected boolean getConfiguredSummary() {
 +
        return true;
 +
      }
 +
</source>
 +
 
 +
If more than 1 column is defined as summary column, they will be concatenated
  
 +
=== Primary Columns ===
 +
{{note|TODO|Describe this here or in the [[Scout/Concepts/Column#Properties|Column property]]}}
  
 
== See Also ==
 
== See Also ==

Revision as of 04:15, 29 January 2014

The Scout documentation has been moved to https://eclipsescout.github.io/.

A table is data structure that can be represented in a The Scout documentation has been moved to https://eclipsescout.github.io/. or a The Scout documentation has been moved to https://eclipsescout.github.io/..

Description

Table can contains a set of structured data: the structure of the entity is defined by the The Scout documentation has been moved to https://eclipsescout.github.io/.. Each entity contained in the table is a The Scout documentation has been moved to https://eclipsescout.github.io/.. At the intersection of a column and a row is a The Scout documentation has been moved to https://eclipsescout.github.io/.. A Cell describes how the value is represented (displayed text, colors, style, icon...).

Example

Imagine that you want to have a table of persons that are structured as followed:

  • Name (String)
  • First name (String)
  • Age (Integer)
  • Date of birth (Date)

A such table needs to contains 4 columns :

Here is how this table looks like in the The Scout documentation has been moved to https://eclipsescout.github.io/.:

Scout sdk example table.png

Access to the data

To access a value of a table, the common pattern is to go through the column. For example if you want to access the age of a person, at a precise row index r, the code is:

  private Integer getAgeOfPersonAtRow(int r){
    return getTable().getAgeColumn().getValue(r);
  }

Add a rows in the table

The table API (client-side) offers different ways to add rows in the table:

1: One row, with type check on set value. (you get compile error if you change something in your table):

ITableRow row = getTable().createRow();
getTable().getNameColumn().setValue(row, "Smith");
getTable().getFirstNameColumn().setValue(row, "John");
getTable().getAgeColumn().setValue(row, 42);
getTable().getBirthDateColumn().setValue(row, DateUtility.parse("14.12.1970", "dd.MM.yyyy"));
getTable().addRow(row, true);

The second parameter correspond to "mark as inserted". false (default value - if the parameter is omitted) the row will be insterted with a row Status: ITableRow.STATUS_NON_CHANGED. If true, the row will be inserted with the status ITableRow.STATUS_INSERTED.

2: One row as Object[] array.

getTable().addRowsByArray(
    new Object[]{"Johnny", "Mcgee", 26, DateUtility.parse("25.05.1986", "dd.MM.yyyy")}, 
    ITableRow.STATUS_INSERTED);

The second parameter indicate the status of the new row. ITableRow.STATUS_INSERTED is the default status (it could be omitted in this example).

3: Multiple rows as Object[][] array.

getTable().addRowsByMatrix(new Object[][]{
    new Object[]{"Isabella", "Barton", 32, DateUtility.parse("21.01.1980", "dd.MM.yyyy")},
    new Object[]{"Dana", "Reyes", 56, DateUtility.parse("16.08.1956", "dd.MM.yyyy")}
}, ITableRow.STATUS_INSERTED);

The second parameter indicate the status of the new row. ITableRow.STATUS_INSERTED is the default status (it could be omitted in this example).

For method 2 and 3 you need to be ensure that the array elements order match with the order of your table columns.

Delete a row from the table

In a Table client-side, you have two ways to remove a row:

  • deleteRow(..)
  • discardRow(..)

deleteRow(..)

the row disappear from Table (as expected by the user), but is still present in the table. You can access it with ITableRow#getDeletedRows(). Later if you export the form content in a The Scout documentation has been moved to https://eclipsescout.github.io/., you will get row in the table with the status ITableHolder.STATUS_DELETED and you can persist the deletion in the database.

discardRow(..)

The row is removed from the table and lost. Nothing is sent to the server.

Now if you set The Scout documentation has been moved to https://eclipsescout.github.io/. to true on the table, calling deleteRow(..) is equivalent to discardRow(..).


The semantic of a discarded row is: the row is deleted + there is no modification to commit to the server. The TableField assume there is no modifications. There is no "saveNeeded" status, the user will not be informed that he has pending modifications on the form...


TODO

Note.png
TODO
Organize these subsections in section + subsection. Add description


Display/Hide the data (Organize Table)

Table provides support to sort, to filter how the content is represented.


Sorting possibility

properties


Selection

Table also manages selection.

properties

Menu

Table can also contains Menus, to provide a possibility to trigger some actions (Menus are displayed in the context menu of the table).


Checkable

Summary Cell

In outline based application, the child-pages are represented a nodes in the page tree. The cell of this node is defined by the summary cell of the table.

The set a column as summary cell, the column must override the following method:

      @Override
      protected boolean getConfiguredSummary() {
        return true;
      }

If more than 1 column is defined as summary column, they will be concatenated

Primary Columns

Note.png
TODO
Describe this here or in the Column property


See Also

Back to the top