# &app; User Guide V&manrevision;

## Introduction

&app; allows you to design and use database systems.

## Getting Started

### Starting &app;

You can start &app; in the following ways:

Applications menu

- Choose Office &app; .

Command line

- To start &app; from a command line, type the following command, then press Return:

  `&app;`

  there are no command line parameters at this time.

### When You Start &app;

When you start &app;, the following window is displayed.

#### &app; Start Up Window

Shows &app; main window.

## Using Glom as an Operator

To open an existing glom document, either open that document from the File Manager, or choose Glom from the Applications menu, and then choose the document when asked. Glom will ask you for a user name and password to access the database. Your administrator will provide your user name and password.

When you open an existing document, Glom will be in `Operator` `user level`. This user level allows you to find and edit records, but does not allow you to change the fundamental structure of the database.

### Navigation

Each database has several tables. To look at a different table, choose `Table` from the `Navigate` menu. Then double-click on the table, or select it and click the `Open` button.

### Entering Data

When in `Data Mode`, you can enter information into either the `List` or `Details` view. The List view shows many records at once, but does not show every field. The details view shows only one record, and shows all the fields arranged suitably.

When you enter data into a field it will be saved into the database immediately after you finish editing the field. If it is a date or time field then the data format will be checked for you.

To create a new record just click the `New` button. A new record will be created with blank fields for you to fill in.

### Finding Data

Choose `Find Mode` from the Mode menu. The fields in the List and Details views will now be empty, and a Find button will appear at the bottom of the window.

Enter information, or part of the information, into a field to find records with that information in that field. For instance, enter Jim into a name field to find records with "Jim" or "Jimmy" in the name.

When you press the `Find` button, glom will search for records and then display them. If only one record is found then it will show you that record in the Details view. If several records are found then it will show you those records in the List view.

## Using Glom as a Developer

When you create a new document, Glom will be in the `Developer` `user level`. You can also change to the Developer user level after opening an existing document, with the `User Level` menu. Glom will only allow this if the administrator has allowed it.

### Adding Tables

You can see the list of existing tables by choosing `Table` from the `Navigate` menu. You will also see this window after connecting to a database server, after creating a new document. To create a new table, click the `Add` button and enter the name for the new table. This name should not contain any spaces or special characters. Glom will suggest a human-readable title for this table. `Operators` will see this title instead of the actual table name. You can also marka a tables as `hidden` from Operators. For instance, Operators should see "Invoice Lines" as related records from the "Invoices" table, but they should never be able to navigate directly to the "Invoice Lines" table.

You can also specify one table as the `default table`. This table will be shown whenever an operator opens an existing document, without asking him to select a table from the list.

You can also use this window to rename an existing table.

Click the `Open` button to look at the selected table.

### Editing Fields

Choose `Fields` from the `Developer` menu. This shows the list of fields in the table. New tables automatically have a primary key field, but you can change this field if necessary.

Click the `Add` button to add a new field, then enter the name of the new field. The name should not contain spaces or special characters. Glom will guess an appropriate human-readable title for this field, but you can edit this. `Operators` will see this title instead of the actual field name.

To specify more field details, select the field and click the `Details` button.

#### Editing Fields

Editing the table's fields.

#### Primary Keys

Each table must have one, and only one, `Primary Key`. The value in this field will be unique, meaning that each value in this field will appear in only one record in the table. For instance, each record in a "Customers" table would have a "Customer ID". This value will be used to refer to that customer from other tables, such as "Projects" and "Invoices" records. See the Creating Relationships section to see how you can relate tables together.

#### Field Types

Glom offers a few simple field types:

1. Number

2. Text

3. Date

4. Time

5. Boolean - either true or false

#### Calculated Fields

Field values can be calculated in terms of other fields, using the Python programming language. This calculation should be the implementation of a python function, which should return a value. The return value will be used as the value of the field. This value will be recalculated every time one of the source fields changes. TODO: This only works for default values at the moment, and you can not use field values in the calculation yet.

You can also use calculations to specify a default value for fields, by selecting the `Default Value` tab in the `Field Details` window, clicking on the `Calculate Value` check box, and then entering a Python calculation. You can test this calculation in the `Edit` window.

### Arranging Layouts

Each table has `List` and `Details` views, and by default these show all fields in the table, in order of creation. You can edit the layout by choosing `Layout` from the `Developer` menu.

For the `List` view, you can specify the sequence of field columns, and whether some fields are hidden.

For the `Details` view, you can create groups of fields, and give these groups titles. You can then place fields in these groups and specify the sequence fo fields in these groups. You can also specify the sequence of these groups. For instance, in a "Contacts" table, you might create a "Name" group, and place the "title", "first_name" and "last_name" fields in that group. You might have other groups for the "Address" fields.

Date and Time fields will be displayed, and entered, in the correct format according to the user's locale, but stored in the database in a canonical form. Therefore, a German user can enter a date in the German format, but this will later be displayed to a U.S. user in the U.S. format.

### Creating Relationships

Tables in the Database are often related together. For instance, an "Invoices" table might have a "Customer ID" field. A value in this field would specify a record in the "Customers" table with the same value. Glom can show extra information, such as the customer name, from that related record. Or it can show a list of several related records - for instance, several related "Invoice Lines" that are related to a record in the "Invoice" record.

To create relationships, choose `Relationships` from the `Developer` menu. This will show the list of existing relationships. Click the `Add` button to create a new relationship, and enter a name for it. You should then choose a field in the current table, and a field in another table to which it should be related. This relationship will find any records in the other table for which the values in both fields are equal.

You can use the relationship in the following places.

1. To show a related field on the List or Details view.

2. To show a list of related records on the Details view.

3. To lookup a value from a field in a related record. For instance, to copy the current price of a "Product" into the "Price" field of an "Invoice Line" record.

4. To calculate a field value.

### Users Administration

To define the `Operators` who can use your database, and to specify what access they have to the various tables, choose `Users` from the `Developer` menu. TODO: Implement the User adminstration.

## About &app;

&app; is maintained by Glom and GNOME community volunteers. To find more information about &app;, please visit the &app; Web site.

To report a bug or make a suggestion regarding this application or this manual, you can submit them using bugzilla.

Another excellent source of information are the &app; mailing lists.

This program is distributed under the terms of the GNU General Public license as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license can be found at this link, or in the file COPYING included with the source code of this program.

## Concepts

Glom is easy to use, but you must understand the following basic concepts.

1. `Database`: Each glom document allows access to one database.

2. `Table`: Each database contains several tables, such as "Customers" and "Invoices" tables.

3. `Field`: Each table has several fields, such as "Customer ID", "First Name", and "Date of Birth" fields. In other documents and applications, fields are sometimes called "Columns"

4. `Records`: Each table contains several records, each of which has values for each of the fields. For instance, the "Customers" table will have a record for each customer. In other documents and applications, records are sometimes called `Rows`.

5. `Relationships`: Each table might be related to other tables, via fields in both tables. For instance, a "Customers" table could have a relationship to the "Invoices" table, so that people could see all the invoices for that customer. Only developers need to understand this concept. In other documents and applications, relationships are sometimes called "Joins".