NAME

GT::SQL::Tree::Rebuild - Helps to turn a table into one usable by GT::SQL::Tree.


SYNOPSIS

    use GT::SQL::Tree;
    use GT::SQL::Tree::Rebuild;
    my $rebuild = GT::SQL::Tree::Rebuild->new(
        table => $DB->table('MyTable'),
        missing_root => \&root_code,
        missing_father => \&father_code,
        missing_depth => \&depth_code,
        order_by => 'column_name'
    );
    $DB->editor('MyTable')->add_tree(root => $root_col, father => $father_col, depth => $depth_col, rebuild => $rebuild);


DESCRIPTION

GT::SQL::Tree::Rebuild is designed to go hand-in-hand with GT::SQL::Tree and aids in turning an existing table into one with the neccessary root, father and depth columns needed by GT::SQL::Tree.

The main purpose is to do a one-shot conversion of a table to make it compatible with GT::SQL::Tree.

new - Create a Rebuild object

There is only one method that is called - new. You pass the arguments needed and get back a GT::SQL::Tree::Rebuild object. This object should then be passed into GT::SQL::Tree->create (typically via $editor->add_tree())

new() takes a hash with up to 4 argument pairs: ``table'' (required), and one or more of ``missing_root'', ``missing_father'', or ``missing_depth''. The values are explained below.

table

Required. You specify the table object for the table to rebuild. For example, if you are going to add a tree to the ``Category'' table, you provide the ``Category'' table object here.

cols

By default, an entire row will be returned. To speed up the process and lower the memory usage, you can use the cols option, which specifies the columns to select for $row. It is recommended that you only select columns that you need as doing so will definately save time and memory.

missing_father, missing_root, missing_depth

Each of these arguments takes a code reference as its value. The arguments to the code references are as follows:

$row

The first argument is a hash reference of the row being examined. Your job, in the code reference, is to examine $row and determine the missing value, depending on which code reference is being called. missing_root needs to return the root_id for this row; missing_father needs to return the father_id, and the missing_depth code reference should return the depth for the row.

$table

The second argument passed to the code references is the same table object that you pass into new(), which you can select from if neccessary.

missing_father

The missing_father code reference is called first - before missing_root and missing_depth. The code reference is called as described above and should return the ID of the father of the row passed in. A false return (0 or undef) is interpreted as meaning that this is a root and therefore has no father.

missing_root

missing_root has to return the root of the row passed in. This is called after missing_father, so the $row will contain whatever you returned in missing_father in the father ID column. Of course, this only applies if using both missing_root and missing_father.

missing_depth

missing_depth has to return the depth of the row passed in. This is called last, so if you are also using missing_father and/or missing_root, you will have whatever was returned by those code refs available in the $row.

order_by

The query done to retrieve records can be sorted using the order_by option. It should be anything valid for ``ORDER BY _____''. Often it can be useful to have your results returned in a certain order - for example: order_by => 'depth_column ASC' would insure that parents come before roots. Of course, this example wouldn't work if you are using ``missing_depth'' since none of the depth values will be set.

Once you have a GT::SQL::Tree::Rebuild object, you should pass it into GT::SQL::Tree->create (which typically involves passing it into $editor->add_tree(), which passed it through). Before calculating the tree, GT::SQL::Tree will call on the rebuild object to reproduce the father, root, and/or depth columns (whichever you specified).


COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/


VERSION

Revision: $Id: Rebuild.pm,v 1.10 2005/04/06 23:11:08 jagerman Exp $