<sect1>
  <title>Application presentation and context</title>
  <para>
    This section presents a small example of how to use some powerful widgets provided with the &LIBGNOMEDB; library 
    (the usage of the data dictionary is better seen in the source of the 'gnome-db-browser' application located in the 
    extra/ directory). This small application will allow
    direct manipulation of data stored in a database representing a small company's shipments. Each shipment
    (order) is represented by an entry in the 'orders' table, and the corresponding's contents are listed as
    entries in the 'order_contents' table. Moreover, the customer the order is for is expressed as a link
    from the 'orders' table to the 'customers' table.
  </para>
  <para>
    The sample application will allow to select a customer, will provide a tabular (grid) view of all the orders for that
    customers, and in another tabular (grid) view whill display the selected order's contents. The orders and the order's 
    contents can be directly edited from the tabular views.
  </para>
  <para>
    The following picture is a screenshot of the final sample application to be built. The resulting window allows to select
    a customer from a drop-down menu at the top ('Lew Bonito' in the example); the middle part shows 
    the orders for the selected customer (which is of course updated everytime the selectec customer changes), 
    and the bottom part shows the selected order's contents (one item in the example).
    Even though they are used, all the primary and foreign keys are hidden from the user.
  </para>
  <mediaobject>
    <imageobject role="html">
      <imagedata fileref="sampleapp1.png" format="PNG"/>
    </imageobject>
  </mediaobject>
  <para>
    The user is expected to select a customer from a popup list at the top of the application, and when done, the
    list of orders for that customers gets updated; when the selected order changes, the order's contents (details)
    is also updated as a dependency, as illustrated in the following picture:
  </para>
  <mediaobject>
    <imageobject role="html">
      <imagedata fileref="sampleapp2.png" format="PNG"/>
    </imageobject>
  </mediaobject>
  <para>
    This sample example is built using LibGlade, and avoids concentrating on the GTK specific layout code. The code
    is located in the <filename>samples/SimpleExample</filename> directory, 
    the specific hand-written code being in the <filename>example.c</filename> file (there is also a simple
    <filename>Makefile</filename> to show how to compile).
  </para>
</sect1>

<sect1>
  <title>Database structure</title>
  <para>
    The database structure is described in the next paragraphs (in PostgreSQL's syntax in this example):
  </para>
  <sect2>
    <title>The customers table</title>
    <para>
      The 'id' field is the primary key of this table.
    </para>
    <programlisting>
CREATE TABLE customers (
      id serial NOT NULL,
      name character varying(35) NOT NULL,
      default_served_by integer,
      country character varying(20),
      city character varying(30)
);
    </programlisting>
  </sect2>
  <sect2>
    <title>The orders table</title>
    <para>
      Each row in the table represents an order passed by a customer. The customer is identified through a
      foreign key (the 'customer' field).
      The 'id' field is the primary key of this table.
    </para>
    <programlisting>
CREATE TABLE orders (
      id serial NOT NULL,
      customer integer NOT NULL,
      creation_date date DEFAULT now() NOT NULL,
      delivery_before date,
      delivery_date date
);
    </programlisting>
  </sect2>
  <sect2>
    <title>The order_contents table</title>
    <para>
      Each row in the table represents an item in an order. The referenced order is identified through a
      foreign key (the 'order_id' field); the referenced item is identified through the 'product_ref' foreign
      key.
      This table has no primary key.
    </para>
    <programlisting>
CREATE TABLE order_contents (
      order_id integer NOT NULL,
      product_ref character varying(15) NOT NULL,
      quantity integer DEFAULT 1 NOT NULL,
      discount double precision DEFAULT 0 NOT NULL
);
    </programlisting>
  </sect2>
  <sect2>
    <title>The products table</title>
    <para>
      Each row in the table represents an item which is sold and can be ordered.
      The 'ref field is the primary key of this table.
    </para>
    <programlisting>
CREATE TABLE products (
      ref character varying(15) NOT NULL,
      name character varying(20) NOT NULL,
      price double precision,
      wh_stored integer
);
    </programlisting>
  </sect2>
</sect1>


<sect1>
  <title>Coding the application</title>

  <sect2>
    <title>Choice of objects</title>
    <para>
      In this example, the <link linkend="GnomeDbGrid">GnomeDbGrid</link> widget will be used to display the data, which
      is stored as a <link linkend="GdaDataModel">GdaDataModel</link> (a 2 dimensions array holding 
      data where all the values in the same row have the same data type). 
    </para>
    <para>The data will be fetched from the database using SELECT SQL queries. It would have been possible at
      this point to use a <link linkend="GdaCommand">GdaCommand</link> for each SQL statement, but it would have been 
      a lot of code to keep track of the dependencies (and re-run the statements when necessary), and it would
      have been difficult to make modifications possible. So instead, the example make use of the 
      <link linkend="GdaDataModelQuery">GdaDataModelQuery</link> object for which one specifies a SELECT SQL statement,
      and optionnally SQL statements for the UPDATE, DELETE and INSERT operations, the object being
      responsible to run those statement when necessary.
    </para>
    <para>
      Two <link linkend="GdaDataModelQuery">GdaDataModelQuery</link> objects are used here: one for the orders of a specific
      customers, and one for the details of a specific order.
    </para>
  </sect2>

  <sect2>
    <title>Complete code</title>
    <para>
      Here is the complete example, which is self-documented.
      <programlisting>&libgnomedb-Example-Code;</programlisting>
    </para>
  </sect2>

  <sect2>
    <title>Compiling</title>
    <para>
      To compile an application using &LIBGNOMEDB;, proceed as with other GTK+ or Gnome libraries, 
      using the <command>pkg-config</command> program and get
      the CFLAGS and LDFLAGS for the '&LIBGNOMEDB;' library.
    </para>
  </sect2>
</sect1>
