$Id: README.txt,v 1.1.2.3 2009-03-27 15:43:12 mikeryan Exp $

OVERVIEW

The Table Wizard facilitates dealing with database tables:

* It allows surfacing any table in the Drupal default database through Views 2.
* Relationships between the tables it manages can be defined, so views 
  combining data in the tables can be constructed.
* It performs analysis of the tables it manages, reporting on empty fields, 
  data ranges, ranges of string lengths, etc.
* It provides an API for other modules to views-enable their tables.
* It provides an API for importing data into tables in the Drupal default 
  database (automatically doing the views integration above).
* It is bundled with an implementation of this API, for importing comma- and 
  tab-delimited files.

Applications of Table Wizard include:

* Module developers can use Table Wizard to views-enable their data tables 
  without writing their own Views hook.
* Developers and administrators can use Table Wizard to create views of all 
  tables in the database, whether or not their creators provided Views integration.
* Users could upload spreadsheets and apply Views to them.

INSTALLATION

Table Wizard requires the Schema and Views modules. In addition, as of 3/27/09 you 
may need to install the following patches to support external tables (check to see if
these patches are in the Schema and Views versions you have installed):

Schema: http://drupal.org/node/411538
Views:  http://drupal.org/node/380560

BASIC USAGE

To add existing tables in your Drupal default database to the Table Wizard, go to
Content management => Table Wizard, expand Add existing tables, and choose a table
to add. Once added, a table can be used as the base for a view, and a default view
of the table is provided (click on the table name in the list). The Analyze page for
a table gives you information on the contents of the table (identifying empty fields,
data ranges, etc.) and allows you to identify fields which can be used to join to
other tables. You can Reanalyze tables if their contents have changed.

Go to Content management => Table Wizard => Relationships to create relationships
among the tables you've added to Table Wizard. When you create a relationships between,
say, ExampleTbl1.key and ExampleTbl2.key, then in a view containing ExampleTbl1 you can
add a relationship to ExampleTbl2, and bring fields from that table into the view.

External comma-separated and tab-delimited files can be imported into the default
Drupal database using the provided tw_import_delimited module. After enabling this module,
the Table Wizard page has an additional fieldset, Upload delimited files. When you
import a file, it is automatically added to the Table Wizard and analyzed.

EXTERNAL TABLES

Table Wizard is also capable of managing tables which are in a database than your
default Drupal installation. The external database needs to be defined in settings.php:

$db_url['default'] = 'mysqli://root:pass1@localhost/drupaldb';
$db_url['extdb'] =   'mysqli://root:pass1@localhost/otherdb';

Once you do this, the Available tables list on the Table Wizard page will also show
tables in the external database, as extdb.exampletbl1, extdb.exampletbl2, etc. At this
time, although Table Wizard does not prevent you from creating relationships across
databases, the Views module does not support this.

TABLE PREFIXING

If you use table prefixing (http://drupal.org/node/2622), to make tables that are
in the same physical database as your Drupal installation but are not part of it
(i.e., are not prefixed) available to Table Wizard, you need to add the database
as if it were external:

$db_url['default'] = 'mysqli://root:pass1@localhost/drupaldb';
$db_url['defaultnotdrupal'] =   'mysqli://root:pass1@localhost/drupaldb';

Note that, at this time, the tables that are prefixed will appear twice.

When using external tables in a table prefix environment, Drupal will prefix the external
tables by default, which in most cases is not what you want. To get around this, you can
set empty prefixes in settings.php for the external tables you are using:

$db_prefix = array(
  'default' => 'pf1_',
  'externaltbl1' => '',
  'externaltbl2' => '',
);

SOURCE API

The Table Wizard itself supports adding existing tables to its list, and comes bundled
with the module tw_import_delimited as an alternative source of data. Additional sources
can be supported by implementing the following two hooks (look at tw_import_delimited.module
for an example implementation):

hook_tw_form() - Construct and return a fieldset containing form controls prompting the user
for any necessary information for identifying your source. The fieldset needs to include
a submit button, and needs to have a unique name not matching any other active source (e.g.,
you should not use 'existing' or 'delimited', which would conflict with hooks already
provided).

hook_tw_form_submit_<fieldset name>($values) - When the submit button in your fieldset is
clicked, the fieldset name is used to construct this hook name and call it, pass the
form values for your fieldset. Return an array of tablenames you've created. Please
note that you most likely will need to apply db_prefix_tables('{'.$tablename.'}') 
(particularly if you've used db_create_table()) to be sure the tablename is properly
saved in a prefixed environment.

CREDITS

Table Wizard was developed by Cyrve (http://cyrve.com/).

Much of the initial development was sponsored by GenomeWeb (http://www.genomeweb.com/)
and The Economist (http://www.economist.com/).

The basis of the tw_import_delimited module was Node Import 
(http://drupal.org/project/node_import).