Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 96 insertions, 0 deletions

diff --git a/documentation/components/components-treetable.asciidoc b/documentation/components/components-treetable.asciidoc
new file mode 100644
index 0000000000..97e53cdf76
--- /dev/null
+++ b/documentation/components/components-treetable.asciidoc
@@ -0,0 +1,96 @@
+---
+title: TreeTable
+order: 23
+layout: page
+---
+
+[[components.treetable]]
+= [classname]#TreeTable#
+
+[classname]#TreeTable# is an extension of the [classname]#Table# component with
+support for a tree-like hierarchy in the first column. As with
+[classname]#Tree#, the hierarchy is determined by the parent-children
+relationships defined in the [interfacename]#Container.Hierarchical# interface.
+The default container is [classname]#HierarchicalContainer#, but you can bind
+[classname]#TreeTable# to any container implementing the interface.
+
+[[figure.components.treetable.basic]]
+.[classname]#TreeTable# Component
+image::img/treetable-basic.png[]
+
+As with [classname]#Tree#, you can define the parent-child relationships with
+[methodname]#setParent()#, as is shown in the following example with numeric
+item IDs:
+
+
+[source, java]
+----
+TreeTable ttable = new TreeTable("My TreeTable");
+ttable.addContainerProperty("Name", String.class, null);
+ttable.addContainerProperty("Number", Integer.class, null);
+        
+// Create the tree nodes and set the hierarchy
+ttable.addItem(new Object[]{"Menu", null}, 0);
+ttable.addItem(new Object[]{"Beverages", null}, 1);
+ttable.setParent(1, 0);
+ttable.addItem(new Object[]{"Foods", null}, 2);
+ttable.setParent(2, 0);
+ttable.addItem(new Object[]{"Coffee", 23}, 3);
+ttable.addItem(new Object[]{"Tea", 42}, 4);
+ttable.setParent(3, 1);
+ttable.setParent(4, 1);
+ttable.addItem(new Object[]{"Bread", 13}, 5);
+ttable.addItem(new Object[]{"Cake", 11}, 6);
+ttable.setParent(5, 2);
+ttable.setParent(6, 2);
+----
+
+Some container types may allow defining hierarchies if the container data
+itself, without explicitly setting the parent-child relationships with
+[methodname]#setParent()#.
+
+Unlike [classname]#Tree#, a [classname]#TreeTable# can have components in the
+hierarchical column, both when the property type is a component type and when
+the tree table is in editable mode.
+
+For other features, we refer you to documentation for [classname]#Table#, as
+given in
+<<dummy/../../../framework/components/components-table#components.table,"Table">>.
+
+[[components.treetable.collapsed]]
+== Expanding and Collapsing Items
+
+As in [classname]#Tree#, you can set the expanded/collapsed state of an item
+programmatically with [methodname]#setCollapsed()#. Note that if you want to
+expand all items, there is no [methodname]#expandItemsRecursively()# like in
+[classname]#Tree#. Moreover, the [methodname]#getItemIds()# only returns the IDs
+of the currently visible items for ordinary [interfacename]#Hierarchical# (not
+[interfacename]#Collapsible#) containers. Hence you can not use that to iterate
+over all the items, but you need to get the IDs from the underlying container.
+
+
+[source, java]
+----
+// Expand the tree
+for (Object itemId: ttable.getContainerDataSource()
+                          .getItemIds()) {
+    ttable.setCollapsed(itemId, false);
+    
+    // As we're at it, also disallow children from
+    // the current leaves
+    if (! ttable.hasChildren(itemId))
+        ttable.setChildrenAllowed(itemId, false);
+}
+----
+
+In large tables, this explicit setting becomes infeasible, as it needs to be
+stored in the [classname]#TreeTable# (more exactly, in the
+[classname]#HierarchicalStrategy# object) for all the contained items. You can
+use a [interfacename]#Collapsible# container to store the collapsed states in
+the container, thereby avoiding the explicit settings and memory overhead. There
+are no built-in collapsible containers in the Vaadin core framework, so you
+either need to use an add-on container or implement it yourself.
+
+
+
+