# Record collection (JavaScript)

Cree unha pequena aplicación con unha base de datos para ordenar a súa colección de música
Proxecto de documentación de GNOME
gnome-doc-list@gnome.org
Johannes Schmid
jhs@gnome.org
Marta Maria Casetti
mmcasettii@gmail.com 2013
Fran Dieguez
frandieguez@gnome.org 2012-2013.

# Record collection

      Neste titorial aprenderá:

        Como conectar con unha base de datos usando libgda
        Como insertar e examinar rexistros nunha táboa dunha base de datos

# Introdución

Esta demostración usa o linguaxe JavaScript. Vaise demostrar como conectar e usar unha base de datos desde un programa GTK, usando a biblioteca GDA («GNOME Data Access», Acceso a datos de GNOME). Polo tanto, é preciso ter instalada tamén esta biblioteca.

GNOME Data Access (GDA) é unha biblioteca cuxo propósito é fornecer acceso universal a diferentes tipos de orixes de datos. Isto vai desde os sistemas de bases de datos relacionais tradicionais a calquera tipo imaxinábel de orixe de datos como un servidor de correo, un directorio LDAP, ect. Para máis información e para obter a API completa e a documentación visite o sitio web de GDA.

Aínda que a maioría do código está relacionado con interfaces de usuario (GUI), imos enforcar este titorial nas partes relacionadas coa base de datos (aínda que podemos mencionar outras partes que son relevantes). Para saber máis sobre os programas JavaScript en GNOME vexa o titorial programa Visor de Imaxes.

# Cree un proxecto de Anjuta

Antes de comezar a programar, deberá configurar un proxecto novo en Anjuta. Isto creará todos os ficheiros que precise para construír e executar o código máis adiante. Tamén é útil para manter todo ordenado.

Inicie Anjuta e prema FicheiroNovoProxecto para abrir o asistente de proxectos.

Seleccione JavaScript xenérico desde a lapela JS, prema Adiante e complete os seus detalles nas seguintes páxinas. Use record-collection como nome do proxecto e cartafol.

Prema Rematar e o proxecto será creado. Abra src/main.js desde a lapela Proxecto ou Ficheiros. Contén código de exemplo moi básico.

# Estrutura do programa

Esta demostración é unha aplicación GTK (cunha única xanela) capaz de inserir rexistros nunha táboa de base de datos así como navegar por tódolos rexistros da toa. A táboa ten dous campos: `id`, un enteiro e `name`, un varchar. A primeira sección (na parte superior) da aplicación permítelle inserir un rexistro na táboa. A última sección (abaixo) permítelle ver tódolos rexistros dunha táboa. Os contidos actualízanse cada vez que se insire un novo rexistro e ao iniciar a aplicación.

# Comezar a diversión

Comezar examinando o esqueleto do programa:

const GLib = imports.gi.GLib; const Gtk = imports.gi.Gtk; const Gda = imports.gi.Gda; const Lang = imports.lang;

function Demo () { this._init (); }

Demo.prototype = {

_init: function () { this.setupWindow (); this.setupDatabase (); this.selectData (); } }

Gtk.init (null, null);

var demo = new Demo ();

Gtk.main ();

Liñas 1-4: importacións iniciais. Preste especial atención á liña 3, que indica que JavaScript importe a a biblioteca GDA, noso obxectivo neste titorial.

Liñas 6-17: Define a clase `Demo`. Poña especial atención ás liñas 13-15, onde chamamos a 3 métodos que farán o traballo. Falaremos deles máis adiante.

Liñas 19-23: Iniciar a aplicación.

# Deseñar a aplicación

Botémoslle unha ollada ao método `setupWindow`. É o responsábel de crear a Interface de Usuario (UI). Xa que a UI non é o noso enfoque explicaremos só as partes máis relevantes.

setupWindow: function () { this.window = new Gtk.Window ({title: "Data Access Demo", height_request: 350}); this.window.connect ("delete-event", function () { Gtk.main_quit(); return true; });

// main box var main_box = new Gtk.Box ({orientation: Gtk.Orientation.VERTICAL, spacing: 5}); this.window.add (main_box);

// first label var info1 = new Gtk.Label ({label: "<b>Insert a record</b>", xalign: 0, use_markup: true}); main_box.pack_start (info1, false, false, 5);

// "insert a record" horizontal box var insert_box = new Gtk.Box ({orientation: Gtk.Orientation.HORIZONTAL, spacing: 5}); main_box.pack_start (insert_box, false, false, 5);

// ID field insert_box.pack_start (new Gtk.Label ({label: "ID:"}), false, false, 5); this.id_entry = new Gtk.Entry (); insert_box.pack_start (this.id_entry, false, false, 5);

// Name field insert_box.pack_start (new Gtk.Label ({label: "Name:"}), false, false, 5); this.name_entry = new Gtk.Entry ({activates_default: true}); insert_box.pack_start (this.name_entry, true, true, 5);

// Insert button var insert_button = new Gtk.Button ({label: "Insert", can_default: true}); insert_button.connect ("clicked", Lang.bind (this, this._insertClicked)); insert_box.pack_start (insert_button, false, false, 5); insert_button.grab_default ();

// Browse textview var info2 = new Gtk.Label ({label: "<b>Browse the table</b>", xalign: 0, use_markup: true}); main_box.pack_start (info2, false, false, 5); this.text = new Gtk.TextView ({editable: false}); var sw = new Gtk.ScrolledWindow ({shadow_type:Gtk.ShadowType.IN}); sw.add (this.text); main_box.pack_start (sw, true, true, 5);

this.count_label = new Gtk.Label ({label: "", xalign: 0, use_markup: true}); main_box.pack_start (this.count_label, false, false, 0);

this.window.show_all (); },

Liñas 22 e 27: crear as dúas entradas (para os dous campos) nas que o usuario escribirá algo para inserilo na base de datos.

Liñas 31-34: crear o botón «Insertar». Conéctase o seu sinal `clicked` co método privado `_insertClicked` de clase. Este método detállase a continuación

Liña 39: Crear o widget (`TextView`) onde se mostrarán os contidos da táboa.

Liña 44: crea a etiqueta onde se mostrará o número de rexistros existentes na táboa. Inicialmente está baleiro, actualizarase máis tarde.

# Conectar e inicializar a base de datos

O código que fai a conexión coa base de datos está no método `setupDatabase` de embaixo:

setupDatabase: function () { this.connection = new Gda.Connection ({provider: Gda.Config.get_provider("SQLite"), cnc_string:"DB_DIR=" + GLib.get_home_dir () + ";DB_NAME=gnome_demo"}); this.connection.open ();

try { var dm = this.connection.execute_select_command ("select * from demo"); } catch (e) { this.connection.execute_non_select_command ("create table demo (id integer, name varchar(100))"); } },

Liña 2-3: crear o obxecto de GDA `Conection`. Debe fornecerlle ao seu construtor algunhas propiedades:

`provider`: un dos fornecedores con asistencia en GDA. GDA é compatíbel con SQLite, MySQL, PostgreSQL, Oracle e moitos outros. Para os propósitos desta demostración usaremos unha base de datos SQLite, xa que ven instalada por omisión na maioría das distribucións e é moi sinxela de usar (usa un só ficheiro por base de datos).

`cnc_string`: A cadea de conexión. Pode cambiar dun fornecedor a outro. A sintaxe para SQLite é: `DB_DIR=PATH;DB_NAME=FILENAME`. Nesta demostración accederemos a unha base de datos chamada gnome_demo no cartafol persoal do usuario (olle a chamada á función de GLib `get_home_dir`).

Se o fornecedor non é compatíbel con GDA, ou falta algún elemento na cadea de conexión, dispararase a excepción da liña 2. Polo que na vida real deberíamos xestionar as declaracións JavaScript entre bloques `try`...`catch`.

Liña 4: Abrir a conexión. No fornecedor de SQLite, se a conexión non existe crearase neste paso.

Liñas 6-10: Tenta facer unha selección sinxela para comprobar que a táboa existe (liña 7). Se non existe (porque a base de datos foi recén creada), esta orde disparará unha excepción, que está xestionada polo bloque `try`...`catch`. Se este é o caso executarase a declaración de creación de táboa (liña 9).

In order to run the SQL commands above we are using the GDA connection methods `execute_select_command` and `execute_non_select_command`. They are simple to use, and just require two arguments: The `Connection` object and the SQL command to be parsed.

Neste punto temos a base de datos configurada e lista para usala.

# Seleccionar

Despois de conectarse á base de datos, o construtor da nosa demostración chama ao método `selectData`. É responsábel de obter tódolos rexistros na táboa e para mostrarllas no widget `TextView`. Votémoslle unha ollada:

selectData: function () { var dm = this.connection.execute_select_command ("select * from demo order by 1, 2"); var iter = dm.create_iter ();

var text = "";

while (iter.move_next ()) { var id_field = Gda.value_stringify (iter.get_value_at (0)); var name_field = Gda.value_stringify (iter.get_value_at (1));

text += id_field + "\t=>\t" + name_field + '\n'; }

this.text.buffer.text = text; this.count_label.label = "<i>" + dm.get_n_rows () + " record(s)</i>"; },

Line 2: The `SELECT` command. We are using the GDA connection's `execute_select_command` method for that. It returns a `DataModel` object, which is later used to retrieve the rows.

Liña 3: Crea un obxecto `Iter`, que se usa para iterar sobre os rexistros de `DataModel`.

Liña 7: Iterar por tódolos rexistros e obtelos coa axuda do obxecto `Iter`. Neste punto a variábel `iter` contén os datos actualizados obtidos. O seu método `move_next` devolve `false` cando se chegue ao último rexistro.

Liñas 8-9: fanse dúas cousas en cada liña:

Use o método `get_value_at` de `Iter`, que só precisa un argumento: o número de columna que recuperar, comezando por 0. Xa que a orde `SELECT` só devolve dúas columnas, se está recuperando as columnas 0 e 1.

O método `get_value_at` devolve o campo no formato `GValue` de GLib. Unha forma sinxela de converter este formato a unha cadea é usando a función global de GDA `value_stringify`. Que é o facemos aquí, e almacenamos os resultados nas variábeis `id_field` e `name_field`.

Liña 11: Concaténanse os dous campos para facer unha única liña de texto, separada por `"=>"`, e almacenámolas na variábel `text`.

Liña 14: Logo de que o bucle remate, temos tódolos rexistros formatados na variábel `text`. Nesta liña estabelecemos os contidos de `TextView` con dita variábel.

Liña 15: mostrar o número de rexistros na táboa, usando o método `get_n_rows` de `DataModel` `get_n_rows`.

# Insertando

OK, sabemos como conectarse a unha base de datos e como seleccionar filas dunha táboa. Agora é tempo de facer un `INSERT` na táboa. Lembra arriba no método `setupWindow` que conectamos o sinal `clicked` do botón Insert ao método `_insertClicked`? Vexamos a implementación deste método.

_insertClicked: function () { if (!this._validateFields ()) return;

// Gda.execute_non_select_command (this.connection, // "insert into demo values ('" + this.id_entry.text + "', '" + this.name_entry.text + "')");

var b = new Gda.SqlBuilder ({stmt_type:Gda.SqlStatementType.INSERT}); b.set_table ("demo"); b.add_field_value_as_gvalue ("id", this.id_entry.text); b.add_field_value_as_gvalue ("name", this.name_entry.text); var stmt = b.get_statement (); this.connection.statement_execute_non_select (stmt, null);

this._clearFields (); this.selectData (); },

We have learned how to use the GDA connection's methods `execute_select_command` and `execute_non_select_command` to quickly execute SQL commands on the database. GDA allows one to build a SQL statement indirectly, by using its `SqlBuilder` object. What are the benefits of this? GDA will generate the SQL statement dynamically, and it will be valid for the connection provider used (it will use the same SQL dialect the provider uses). Let's study the code:

Liña 2-3: compróbase que o usuario completa tódolos campos. O código do método privato `_validateFields` é realmente sinxelo e pode lelo no código fonte completo da demostración.

Liña 5: A forma máis rápida é `INSERT`. Está descomentado xa que queremos ver como usar o obxecto `SqlBuilder` para construír unha declaración SQL portábel a través das bases de datos.

Liña 7: crea o obxecto `SqlBilder`. Debemos pasar o tipo de declaración que queremos construír. Pode ser `SELECT`, `UPDATE`, `INSERT` ou `DELETE`.

Liña 8: estabelecer o nome da base de datos na que operará a sentencia construída (xerará `INSERT INTO demo`)

Liñas 9-10: estabelecer os campos que formarán parte da sentenza e os seus valores. O primeiro campo é o nome do campo (como aparece na táboa). O segundo é o valor deste campo.

Liña 11: obter o obxecto `Statement` xerado dinamicamente, que representa unha sentenza SQL.

Liña 12: finalmente, executar a sentenza SQL (`INSERT`).

Liña 14: limpar os campos id e nome na pantalla. O código do método privado `_clearFields` é moi sinxelo e pode lelo no código fonte completo da demostración.

Liña 15: actualizar a vista na pantalla facendo outro `SELECT`.

Tamén pode usar parámetros mentres constrúe a sentenza. Usando obxectos e parámetros `SqlBuilder` será menos susceptíbel a ataques de inxección de SQL. Para obter información adicional sobre os parámetros, consulte a documentación de GDA.

# Executar a aplicación

Todo o código que precisa agora está no seu lugar, polo que tente executar o código. Agora ten unha base de datos para a súa colección de rexistros!

# Implementación de referencia

Se ten problemas co titorial, compare o seu código con este código de referencia.