# Användarguide för Glom v0.1

för Glom v0.8
2004
Murray Cumming
2006
Daniel Nylander (po@danielnylander.se)
Gloms utvecklingsteam

Tillstånd att kopiera, distribuera och/eller modifiera detta dokument ges under villkoren i GNU Free Documentation License (GFDL), version 1.1 eller senare, utgivet av Free Software Foundation utan standardavsnitt och omslagstexter. En kopia av GFDL finns att hämta på denna länk eller i filen COPYING-DOCS som medföljer denna handbok.

Denna handbok utgör en av flera GNOME-handböcker som distribueras under villkoren i GFDL. Om du vill distribuera denna handbok separat från övriga handböcker kan du göra detta genom att lägga till en kopia av licensavtalet i handboken enligt instruktionerna i avsnitt 6 i licensavtalet.

Flera namn på produkter och tjänster är registrerade varumärken. I de fall dessa namn förekommer i GNOME-dokumentation - och medlemmarna i GNOME-dokumentationsprojektet är medvetna om dessa varumärken - är de skrivna med versaler eller med inledande versal.

DOKUMENTET OCH MODIFIERADE VERSIONER AV DOKUMENTET TILLHANDAHÅLLS UNDER VILLKOREN I GNU FREE DOCUMENTATION LICENSE ENDAST UNDER FÖLJANDE FÖRUTSÄTTNINGAR:

1. DOKUMENTET TILLHANDAHÅLLS I "BEFINTLIGT SKICK" UTAN NÅGRA SOM HELST GARANTIER, VARE SIG UTTRYCKLIGA ELLER UNDERFÖRSTÅDDA, INKLUSIVE, MEN INTE BEGRÄNSAT TILL, GARANTIER ATT DOKUMENTET ELLER EN MODIFIERAD VERSION AV DOKUMENTET INTE INNEHÅLLER NÅGRA FELAKTIGHETER, ÄR LÄMPLIGT FÖR ETT VISST ÄNDAMÅL ELLER INTE STRIDER MOT LAG. HELA RISKEN VAD GÄLLER KVALITET, EXAKTHET OCH UTFÖRANDE AV DOKUMENTET OCH MODIFIERADE VERSIONER AV DOKUMENTET LIGGER HELT OCH HÅLLET PÅ ANVÄNDAREN. OM ETT DOKUMENT ELLER EN MODIFIERAD VERSION AV ETT DOKUMENT SKULLE VISA SIG INNEHÅLLA FELAKTIGHETER I NÅGOT HÄNSEENDE ÄR DET DU (INTE DEN URSPRUNGLIGA SKRIBENTEN, FÖRFATTAREN ELLER NÅGON ANNAN MEDARBETARE) SOM FÅR STÅ FÖR ALLA EVENTUELLA KOSTNADER FÖR SERVICE, REPARATIONER ELLER KORRIGERINGAR. DENNA GARANTIFRISKRIVNING UTGÖR EN VÄSENTLIG DEL AV DETTA LICENSAVTAL. DETTA INNEBÄR ATT ALL ANVÄNDNING AV ETT DOKUMENT ELLER EN MODIFIERAD VERSION AV ETT DOKUMENT BEVILJAS ENDAST UNDER DENNA ANSVARSFRISKRIVNING;

2. UNDER INGA OMSTÄNDIGHETER ELLER INOM RAMEN FÖR NÅGON LAGSTIFTNING, OAVSETT OM DET GÄLLER KRÄNKNING (INKLUSIVE VÅRDSLÖSHET), KONTRAKT ELLER DYLIKT, SKA FÖRFATTAREN, DEN URSPRUNGLIGA SKRIBENTEN ELLER ANNAN MEDARBETARE ELLER ÅTERFÖRSÄLJARE AV DOKUMENTET ELLER AV EN MODIFIERAD VERSION AV DOKUMENTET ELLER NÅGON LEVERANTÖR TILL NÅGON AV NÄMNDA PARTER STÄLLAS ANSVARIG GENTEMOT NÅGON FÖR NÅGRA DIREKTA, INDIREKTA, SÄRSKILDA ELLER OFÖRUTSEDDA SKADOR ELLER FÖLJDSKADOR AV NÅGOT SLAG, INKLUSIVE, MEN INTE BEGRÄNSAT TILL, SKADOR BETRÄFFANDE FÖRLORAD GOODWILL, HINDER I ARBETET, DATORHAVERI ELLER NÅGRA ANDRA TÄNKBARA SKADOR ELLER FÖRLUSTER SOM KAN UPPKOMMA PÅ GRUND AV ELLER RELATERAT TILL ANVÄNDNINGEN AV DOKUMENTET ELLER MODIFIERADE VERSIONER AV DOKUMENTET, ÄVEN OM PART SKA HA BLIVIT INFORMERAD OM MÖJLIGHETEN TILL SÅDANA SKADOR.

Murrayc
Cumming
Gloms utvecklingsteam

     murrayc@murrayc.com

Glom 0.8
20 Juni 2004

Murray Cumming

Murray Cumming

Den här handboken beskriver version 0.8 av Glom

## Återkoppling

To report a bug or make a suggestion regarding the Glom or this manual can be submitted to the GNOME Bugzilla , under the Glom product. Please search bugzilla before submitting your bug to ensure that yours hasn't already been reported.

Användarhandbok för Glom.

## Introduktion

Glom låter dig designa och använda databassystem.

## Komma igång

### Starta Glom

Du kan starta Glom på följande sätt:

Applications menu

  Choose Office Glom .

### When You Start Glom

When you start Glom, the following window is displayed.

#### Glom Start Up Window

Shows Glom 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.

### Navigering

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.

#### Primära nycklar

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.

#### Fälttyper

Glom offers a few simple field types:

1. Number

2. Text

3. Datum

4. Tid

5. Boolean - either true or false

6. Bild

#### 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..

## Dialogs

### Dialog: New database

### Dialog: Create database

### Dialog: Connection

This dialog requests a user name and password for connection to a database server. This is usually not the same username and password combination with which you log in to your system. All Glom systems require a database server on which the actual data will be stored. If the database server is not running on your local computer ("localhost"), then you must also provide its network hostname, such as "glomserver.openismus.com", though your hostname will be different.

Your system administrator can provide these database login details.

If you are the system administrator, see Glom's Postgres Configuration web page for help with installing and configuring a database server.

### Dialog: Connection Error

This dialog is shown when Glom could not connect to the specified database server. Either the database server is not running at the specified hostname, or the user name and password were not accepted by the database server. See the Connection Dialog section for more details.

### Dialog: Database preferences

### Dialog: Change language

### Window: Textobject

### Window: Imageobject

### Dialog: Notebook

### Dialog: Data invalid format

### Dialog: Relationship overview

### Window: Groups

### Dialog: Group by sort fields

### Dialog: Group by secondary fields

### Window: Button script

### Window: Field calculation

### Dialog: New group

### Dialog: Choose user

### Dialog: User

### Dialog: Translation identify original

### Dialog: Translation copy

### Dialog: Choose Date

## About Glom

Glom is maintained by Glom and GNOME community volunteers. To find more information about Glom, please visit the Glom 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 Glom 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".

## Calculated fields and button scripts

Calculated fields and button scripts use the Python programming language. The calculation or script is the implementation of a function whose signature is provided for you.

### Editing the definition of a calculated field

Editing the definition of a calculated field.

### Field values

For instance,

    record["name_first"]

is the value of the name_first field in the current record.

### Related Records

For instance,

    record.related["location"]

provides the related records for the current record.

#### Single related records

For relationships that specify a single record, you can get the value of a field in that record. For instance,

    record.related["location"]["name"]

is the value of the name field in the table indicated by the location relationship (often called location::name).

#### Multiple related records

For relationships that specify multiple records, you can use the aggregate functions (sum, count, average) to get overall values. For instance,

    record.related["invoice_lines"].sum("total_price")

.

### Testing for empty values

How you test for empty values depends on the type of field:

#### Non-text fields

Non-text fields may be empty, indicating that the user has not entered any value in the field. For instance, Glom does not assume that an empty value in a numeric field should mean 0.

You can test whether a field is empty by using Python's None. For instance:

      if(record["contact_id"] == None):
        return "No Contact"
      else:
        return record.related["contacts"]["name_full"]

You might also test whether there are any related records. For instance:

      if(record.related["contacts"] == None):
        return "No Contact"
      else:
        return record.related["contacts"]["name_full"]

#### Text fields

For text fields, you should check for zero-length strings. It is not possible in Glom to distinguish between zero-length strings and the absence of any string, because there is no advantage to doing so. For instance:

      if(record["name_full"] == ""):
        return "No Name"
      else:
        return record["name_full"]

#### Using the full pygda API

pygda is a python API for the libgda API. The record's `connection` attribute provides a gda.connection that can be used to access the current database directly. This allows you to run any SQL query, for instance to read data from the database with a SELECT, or to change values in the database with an UPDATE. Note that the connection is already open so you can avoid the difficult work of specifying the connection details.

The record's `table_name` attribute also provides the name of the current table.

(Note that the `record.connection` and `record.table_name` attributes are only available since Glom 1.1.6.)

This example reads all data from the current table and prints the values to the terminal:

    # Use the current database's connection
    # to get all the data for the current table.
    #
    # record.connection is an already-open gda.connection object,
    # saving us the bother of opening the connection,
    # or even knowing the name of the database.

    query = "SELECT * FROM %s" % record.table_name
    command = gda.Command(query)
    data_model = record.connection.execute_single_command(command)

    rows = data_model.get_n_rows()
    columns = data_model.get_n_columns()
    print "    Number of columns: ", columns

    for i in range(columns):
        print "      column ", i;
        print "        name=", data_model.get_column_title(i)

        # Find out whether it's the primary key:
        field = data_model.describe_column(i)
        if field.get_primary_key():
            print "        (primary key)"

        print "\n";

    print "    Number of rows: ", rows

    for row_index in range(rows):
        print "      row ", row_index;

        for col_index in range(columns):
            print "        value=", data_model.get_value_at(col_index, row_index).get()

        print "\n";