NAME

Gtk2::Ex::DbLinker::Datasheet - a module that display data from a database in a tabular format using a treeview

VERSION

See Version in Gtk2::Ex::DbLinker

SYNOPSIS

This display a table having to 6 columns: 3 text entries, 2 combo, 1 toogle, we have to create a dataManager object for each combo, and a dataManager for the table itself. The example here use Rose::DB::Object to access the tables.

This gets the Rose::DB::Object::Manager (we could have use plain sql command, or DBIx::Class object)

        my $datasheet_rows = Rdb::Mytable::Manager->get_mytable(sort_by => 'field1');

This object is used to instanciante a RdbDataManager, that will be used in the datasheet constructor.

        my $dman = Gtk2::Ex::DbLinker::RdbDataManager->new(data => $datasheet_rows, meta => Rdb::Mytable->meta );

We create the RdbDataManager for the combo rows

    my $combo_data = Rdb::Combotable::Manager->get_combotable( select => [qw/t1.id t1.name/], sort_by => 'name');
        my $dman_combo_1 = Gtk2::Ex::DbLinker::RdbDataManager->new(data => $combo_data, meta => Rdb::Combotable->meta);


        my $combo2_data =  Rdb::Combotable2::Manager->get_combotable2( sort_by => 'country');
        my $dman_combo_2 = Gtk2::Ex::DbLinker::RdbDataManager->new( 
                                                        data =>$combo2_data,
                                                        meta => Rdb::Combotable2->meta,
                                                        );

We create the Datasheet object with the columns description

        my $treeview = Gtk2::TreeView->new();

        $self->{datasheet} = Gtk2::Ex::DbLinker::Datasheet->new(
                treeview => $treeview,
                fields => [{name=>"field1", renderer=>"text"},
                        {name=>"field2"}, 
                        {name=>"url", renderer=>"text", custom_render_functions => [sub {display_url (@_, $self);},]},
                        {name => 'nameid', renderer => 'combo', data_manager => $dman_combo_1, fieldnames=>["id", "name"]},
                        {name => 'countryid', renderer => 'combo', 
                                     data_manager=> $dman_combo_2,
                                        fieldnames=>["id", "country"]}, 
                        {name => 'idle', renderer => 'toggle'},
                                ],
                data_manager => $dman,          
        );

To change a set of rows in the table when we navigate between records for example, we fetch the rows using a object derived from Rose::DB::Object::Manager and pass it to the Gt2::Ex::DbLinker::RdbDatamanager object using the query method:

          my $data =  Rdb::Mytable::Manager->get_mytable(query =>[pk_field =>{eq=> $primarykey_value}], sort_by => 'field1');
          $self->{dataseet}->get_data_manager->query($data);

          $self->{datasheet}->update();

DESCRIPTION

This module automates the process of setting up a model and treeview based on field definitions you pass it. An additional column named _status_column_ is added in front of a the other fields. It holds icons that shows if a row is beeing edited, mark for deletion or is added.

Steps for use:

  • Instanciate a xxxDataManager that will fetch a set of rows.

  • Create a 'bare' Gtk2::TreeView.

  • Create a xxxDataManager holding the rows to display, if the datasheet has combo box, create the corresponding DataManager that hold the combo box content.

  • Create a Gtk2::Ex::DbLinker::Datasheet object and pass it your TreeView and DataManagers objects.

    You would then typically connect some buttons to methods such as inserting, deleting, etc.

METHODS

constructor

The new() method expects a list of parameters name => value or a hash reference of parameters name (keys) / value pairs.

The parameters are:

  • data_manager a instance of a xxxDataManager object.

  • tree a Gtk2::TreeView

  • fields a reference to an array of hash refs. Each hash has the following key / value pairs.

    • name / name of the field to display.

    • renderer / one of "text combo toggle hidden image".

    if the renderer is a combo the following key / values are needed in the same hash reference:

    • data_manager / an instance holding the rows of the combo.

    • fieldnames / a reference to an array of the fields that populate the combo. The first one is the return value that correspond to the field given in name.

update();

Reflect in the user interface the changes made after the data manager has been queried, or on the datasheet creation.

get_data_manager();

Returns the data manager to be queried.

Methods applied to a row of data:

  • insert();

    Displays an empty rows.

  • delete();

    Marks the current row to be deleted. The delele itself will be done on apply.

  • apply();

    Create a new row in the DataManager and fetchs the values from the grid, and add this row to the database. Save changes on an existing row, or delete the row(s) marked for deletion. An array ref of fields name can be given to prevent these from being saved. This is usefull to change the row flag from modified to unmodif when the change are saved directly with the DataManager.

  • undo();

    Revert the row to the original state in displaying the values fetch from the database.

SUPPORT

Any Gk2::Ex::DbLinker questions or problems can be posted to me (rappazf) on my gmail account.

The current state of the source can be extract using Mercurial from http://sourceforge.net/projects/gtk2-ex-dblinker/.

AUTHOR

François Rappaz <rappazf@gmail.com>

COPYRIGHT AND LICENSE

Copyright (c) 2014-2017 by François Rappaz. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Gtk2::Ex::Datasheet::DBI

CREDIT

Daniel Kasak, whose modules initiate this work.