<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to you under the Apache License,
Version 2.0 (the "License"); you may not use this file except in
compliance with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<document id="table-views.json">
    <properties>
        <title>JSON-based TableView</title>
    </properties>

    <body>
        <p>
            The previous example showed a basic table view that was populated by string-based hash
            map data and did not support sorting on the Olympic medal count data. This example
            populates the same table view with JSON values, which represent the medal counts as
            numbers, rather than strings:
        </p>

        <application class="org.apache.pivot.wtk.ScriptApplication" width="480" height="240">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/tableviews/json_table_view.bxml</src>
            </startup-properties>
        </application>

        <p>The BXML source is as follows:</p>

        <source type="xml" location="org/apache/pivot/tutorials/tableviews/json_table_view.bxml">
            <![CDATA[
            <Window title="Table Views" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <Border>
                    <ScrollPane horizontalScrollBarPolicy="fill_to_capacity">
                        <TableView bxml:id="tableView" styles="{includeTrailingVerticalGridLine:true}">
                            <columns>
                                <TableView.Column name="nation" width="180" headerData="Nation"/>
                                <TableView.Column name="gold" width="60" headerData="Gold"/>
                                <TableView.Column name="silver" width="60" headerData="Silver"/>
                                <TableView.Column name="bronze" width="60" headerData="Bronze"/>
                                <TableView.Column name="total" width="60" headerData="Total"/>
                            </columns>

                            <tableViewSortListeners>
                                function sortChanged(tableView) {
                                    var tableData = tableView.getTableData();
                                    tableData.setComparator(new org.apache.pivot.wtk.content.TableViewRowComparator(tableView));
                                }
                            </tableViewSortListeners>

                            <tableData>
                                <bxml:include src="standings.json"/>
                            </tableData>
                        </TableView>

                        <columnHeader>
                            <TableViewHeader tableView="$tableView" sortMode="single_column"
                                styles="{includeTrailingVerticalGridLine:true}"/>
                        </columnHeader>
                    </ScrollPane>
                </Border>
            </Window>
            ]]>
        </source>

        <p>It is very similar to the previous example, with the following exceptions:</p>

        <ul>
            <li>
                <p>
                    The <tt>ScrollPane</tt> is given a <tt>horizontalScrollBarPolicy</tt> value of
                    "fill_to_capacity". This tells the scroll pane to expand the width of its
                    contents to fit the available horizontal space when necessary, but not
                    constrain the content width to that space when the content wants to be larger.
                    This is what allows the table view to display a "filler" column when its total
                    column width is less than the current viewport width in the scroll pane.
                </p>
            </li>

            <li>
                <p>
                    It populates the table with data from the "standings.json" file. The contents
                    of this file are shown below.
                </p>
            </li>

            <li>
                <p>
                    It defines a listener that responds to table view sorts. Table views do not
                    implement sorting internally. This is the responsibility of the application,
                    since the application may want to delegate sorting to another process, such as
                    a JDBC query executed as a background task. When a user presses a column
                    header, the <tt>TableViewHeader</tt> skin responds by modifying the table
                    view's "sort dictionary", which maps column names to sort directions
                    (ascending, descending, or neither). <tt>TableView</tt> fires a "sortChanged"
                    event in response to a sort dictionary change, to which the listener responds
                    by setting a comparator on the table data:
                </p>

                <source type="xml" location="org/apache/pivot/tutorials/tableviews/json_table_view.bxml">
                    <![CDATA[
                    <tableViewSortListeners>
                        function sortChanged(tableView) {
                            var tableData = tableView.getTableData();
                            tableData.setComparator(new org.apache.pivot.wtk.content.TableViewRowComparator(tableView));
                        }
                    </tableViewSortListeners>
                    ]]>
                </source>
                <p>
                    In this case, the listener assigns an instance of
                    <tt>TableViewRowComparator</tt> to the table data. This class is capable of
                    sorting many types of table data given the sort dictionary of the
                    <tt>TableView</tt> passed to its constructor.
                </p>
            </li>
        </ul>

        <p>
            The contents of "standings.json" are as follows. Medal counts are represented as actual
            numeric data rather than strings, allowing <tt>TableViewRowComparator</tt> to sort
            them properly:
        </p>

        <source type="javascript" location="org/apache/pivot/tutorials/tableviews/standings.json">
            <![CDATA[
            // Source: http://en.wikipedia.org/wiki/2008_Summer_Olympics_medal_table
            [   {nation:"China", gold:51, silver:21, bronze:28, total:100},
                {nation:"United States", gold:36, silver:38, bronze:36, total:110},
                {nation:"Russia", gold:23, silver:21, bronze:28, total:72},
                {nation:"Great Britain", gold:19, silver:13, bronze:15, total:47},
                {nation:"Germany", gold:16, silver:10, bronze:15, total:41},
                {nation:"Australia", gold:14, silver:15, bronze:17, total:46},
                {nation:"South Korea", gold:13, silver:10, bronze:8, total:31},
                {nation:"Japan", gold:9, silver:6, bronze:11, total:26},
                {nation:"Italy", gold:8, silver:10, bronze:10, total:28},
                {nation:"France", gold:7, silver:16, bronze:17, total:40}
            ]
            ]]>
        </source>

        <p>
            There is no associated Java source code for this example.
        </p>
    </body>
</document>
