Thanks to SourceForge Logo for hosting this site. Back to main page

4. Building a Niles application

Database definition

Well, here we are. An application definition consist in a XML file, so we mostly work with XML tags. The root tag is <application>, so we'll start defining it:

<application name="John Doe's Hardware" database="mysql://localhost/jdhard">

The name attribute specifies an optional name that will be used in the main window and some others. Database is the URL of the database used by the application. You can't at this time (and you seldom need to) use more than only one database.

In your application, as we said, you need to specify the information about your database structure. You will do it using <table>, <field>, and <relationship> tags:

<table name="customers">
	<field name="number" type="integer" pk size="4" />
	<field name="lastname" type="char" size="20" />
	<field name="name" type="char" size="20" caption="First Name"/>
<table name="invoices">
	<field name="number" type="integer" pk size="8" default="0" />
	<field name="customer" type="integer" size="4" />
	<field name="date" type="char" size="12" />
	<field name="total" type="real" size="10" />
	<field name="notes" type="char" size="150" />
<table name="products">
	<field name="code" type="char" pk size="12" />
	<field name="description" type="char" size="30" />
	<field name="price" type="real" size="8" default="0.00" />

As you can see, declaring a table simply involves including its name, and for each field, the field name, type, size, if it is part of the table's primary key, and a default value, all but the name are optional. The field types are char, integer and real, default type is char.

Tables are related to each other, so we need to declare relationships as well. We use a <relationship> block with both parent and child table as attributes. The <link> tags into the relationship block states which field in a table matches each field in the other:

<relationship name="cust-inv" parenttable="customers" childtable="invoices">
	<link parentfield="number" childfield="customer" />

View definition

Once all the underlying database information is set, we can go for something more interesting, like an entry form. So, we define the user view:

<view name="Products" master="products">
	<field datafield="code" caption="Code" browseenabled editenabled />
	<field datafield="description" caption="Description" editenabled />
	<field datafield="price" caption="Price" editenabled />

This is a simple form, all the data will go to a single table, specified as the master table of the view. The view also has a name to handle it, and to use as a window caption.

Fields are defined in it, they must match to the view's master table, as long you do not specify explicitly a different table. You must specify a datafield by its name, and some interface stuff.

The <newline/> tag is a layout marker. We'll see layout management later. To give this stuff a try, add a start attribute to application tag

<application name="John Doe's Hardware" database="mysql://localhost/jdhard" start="products">

and run niles with the XML file (pick it here) as a parameter. You will get a window like this:

Products form

Lookups (under construction)

Easy, isn't it? But this isn't very useful, so we need to introduce some more features. One of the easiest things to try are lookups fields.

We add a new table for product categories, and a field in products table for category number. These two tables must be linked with a relationship as well:

<table name="categories">
	<field name="number" type="integer" pk size="2" />
	<field name="description" type="char" size="30" />
<relationship name="cat-prod" parenttable="categories" childtable="products">
	<link parentfield="number" childfield="category" />

Our user can remember those numbers, but to get sure, he'll appreciate if the category description appears next to the number. So we will add a new kind of tag into the view:

<view name="Products" master="products">
	<field datafield="code" caption="Code" browseenabled editenabled />
	<field datafield="description" caption="Description" editenabled />
	<field datafield="category" caption="Category" editenabled />
	<lookupfield datafield="cat-prod.description"  />
	<field datafield="price" caption="Price" editenabled />

Providing that we have some categories defined in the table, when we input a category number, the proper description appears in a label at the right (pick the code here):

Lookup label

In some cases, it's more worthy just put a list or combo box and simply choose the detailed value, without bothering about the real value of the key. To do so, delete the category field, and change the lookupfield to:

<lookupfield datafield="categories.description" caption="Category" showas="combo"/>

Lookup combo

There are still a lot of details and small tricks to consider. Please read the tag reference for throughly information about each option available.

Main window, menus, and toolbars

As in most cases you will need more than just a single data entry form, you'll likely want to have a menu in order to choose a form or another. The menu definition is quite easy:

	<submenu caption="Forms">
		<menuitem caption="Customers" />
		<menuitem caption="Products" />
		<menuitem caption="Exit" action="exit"/>
	<submenu caption="Sales">
		<menuitem caption="Invoices" />
	<submenu caption="Reports">
	<button caption="Products" picture="producticon.png"/>
	<button caption="Customers" />
	<button caption="Invoices" />

Having defined a menu, a toolbar, or both, there is no more need for start attribute in the <application> tag, as the application will start just showing the main window with the menu or toolbar. You still can have a start defined if you wish, in order to show a logon dialog or anything else.

Main window

The only thing to be aware is the action attribute. action can be present in either menuitem and button, and triggers the specified action, that can be showing a view, or trying to run a piece of code. Coded events will be discussed later.

Master detail forms

Coding events

Queries and reports