This section provides a quick tutorial for you to learn about the available methods and the somewhat proper way to use them. For simplicity's sake, the sample database table is nothing more than a glorified flat file, but it will suffice:

Say that you have a table stored in a database. A snapshot of it might look like this:

    Artist           Album                 Title
----------------------------------------------------------
Bjork            Telegram              Army Of Me
The Police       Reggatta De Blanc     Does Everyone Stare
Ozric Tentacles  The Hidden Step       Holohedron
Ozric Tentacles  The Hidden Step       Pixel Dream
Air              Moon Safari           La Femme DArgent
Ozric Tentacles  The Hidden Step       Tight Spin
The Police       Reggatta De Blanc     Walking On The Moon
Bjork            Telegram              Isobel
The Police       Ghost In The Machine  Invisible Sun
Ozric Tentacles  Jurassic Shift        Sunhair
----------------------------------------------------------

Step 1. Establish a connection to the database server.

Here is where the mileage varies. Different databases have subtle differences for the connection arguments. This tutorial uses MySQL. Now might be a good time to read the DBI docs.

Connecting to your database with DBIx::XHTML_Table is no different than connecting to a database with DBI. The following code will connect to the host deadbeef for the user sparky with the password l33t. The table is named songs and is stored in the database mp3. You will need to change these values accordingly.

use strict;
use DBIx::XHTML_Table; 

my $table = DBIx::XHTML_Table->new('DBI:mysql:mp3:deadbeef', 'sparky', 'l33t');
If you feel more comfortable creating a DBI object first, then go right ahead:
my $dbh = DBI->connect(
  'DBI:mysql:mp3:deadbeef', 'sparky', 'l33t',
  { RaiseError => 1 }
);

my $table = DBIx::XHTML_Table->new($dbh);
Just don't forget to disconnect() the database handle when you are finished with it.

Make sure that you can successfully connect to your database and instantiate a DBIx::XHTML_Table object before moving on.

Step 2. Execute a SQL query

Once you have successfully connected to your database, the next step is to 'execute' a query:

$table->exec_query('
   select artist, album, title as song
   from temp
   order by artist,album
');

print $table->output();

Step 3. Mold an XHTML table

The rest of the tutorial is incremental - use the following code template:

my $table = DBIx::XHTML_Table->new(
  'DBI:mp3:songs:host', 'user', 'password'
);

# insert new code here

print $table->output();
Copy the first example below and paste it to the template where the comment 'insert new code here' is. Run the code to see it's results - a CGI script is the most effective.

Then, copy the second example and paste it just below the first example. Run the code. Keep repeating, pasting the next example below the previous, until you have the same code found on the Home page. The results for each code example are to the right of each code example.

Code Result

Let's get all the songs, listed by the album and the year first.
  
$table->exec_query("
  select artist, album, 
         title as song
  from temp
  order by artist,album
");

  

Artist Album Song
Air Moon Safari La Femme DArgent
Bjork Telegram Army Of Me
Bjork Telegram Isobel
Ozric Tentacles Jurassic Shift Sunhair
Ozric Tentacles The Hidden Step Pixel Dream
Ozric Tentacles The Hidden Step Tight Spin
Ozric Tentacles The Hidden Step Holohedron
The Police Ghost In The Machine Invisible Sun
The Police Reggatta De Blanc Does Everyone Stare
The Police Reggatta De Blanc Walking On The Moon

Add a border to the table:
  
$table->modify(table => { 
  style => {
    'border-style' => 'outset',
    'border-width' => 'thick',
  }
});

  

Artist Album Song
Air Moon Safari La Femme DArgent
Bjork Telegram Army Of Me
Bjork Telegram Isobel
Ozric Tentacles Jurassic Shift Sunhair
Ozric Tentacles The Hidden Step Pixel Dream
Ozric Tentacles The Hidden Step Tight Spin
Ozric Tentacles The Hidden Step Holohedron
The Police Ghost In The Machine Invisible Sun
The Police Reggatta De Blanc Does Everyone Stare
The Police Reggatta De Blanc Walking On The Moon

Add borders to the table data cells.
  
$table->modify(td => {
  style => {
    'border-style' => 'inset',
    'border-width' => 'thin',
  }
});

  

Artist Album Song
Air Moon Safari La Femme DArgent
Bjork Telegram Army Of Me
Bjork Telegram Isobel
Ozric Tentacles Jurassic Shift Sunhair
Ozric Tentacles The Hidden Step Pixel Dream
Ozric Tentacles The Hidden Step Tight Spin
Ozric Tentacles The Hidden Step Holohedron
The Police Ghost In The Machine Invisible Sun
The Police Reggatta De Blanc Does Everyone Stare
The Police Reggatta De Blanc Walking On The Moon

Add a caption:
  
$table->modify(
  caption => 'My MP3 Collection',
  { style => 'font-size: x-large'},
);

  

My MP3 Collection
Artist Album Song
Air Moon Safari La Femme DArgent
Bjork Telegram Army Of Me
Bjork Telegram Isobel
Ozric Tentacles Jurassic Shift Sunhair
Ozric Tentacles The Hidden Step Pixel Dream
Ozric Tentacles The Hidden Step Tight Spin
Ozric Tentacles The Hidden Step Holohedron
The Police Ghost In The Machine Invisible Sun
The Police Reggatta De Blanc Does Everyone Stare
The Police Reggatta De Blanc Walking On The Moon

You can suppress duplicates on one column:
  
$table->set_group('artist',1);

  

My MP3 Collection
Artist Album Song
Air Moon Safari La Femme DArgent
Bjork Telegram Army Of Me
  Telegram Isobel
Ozric Tentacles Jurassic Shift Sunhair
  The Hidden Step Pixel Dream
  The Hidden Step Tight Spin
  The Hidden Step Holohedron
The Police Ghost In The Machine Invisible Sun
  Reggatta De Blanc Does Everyone Stare
  Reggatta De Blanc Walking On The Moon

Add color and borders to the column headers:
  
$table->modify(th => {
  style => { 
    'border-style' => 'inset',
    color      => '#a9b9a9',
    background => '#444444',
  }
});

  

My MP3 Collection
Artist Album Song
Air Moon Safari La Femme DArgent
Bjork Telegram Army Of Me
  Telegram Isobel
Ozric Tentacles Jurassic Shift Sunhair
  The Hidden Step Pixel Dream
  The Hidden Step Tight Spin
  The Hidden Step Holohedron
The Police Ghost In The Machine Invisible Sun
  Reggatta De Blanc Does Everyone Stare
  Reggatta De Blanc Walking On The Moon

Add alternating colors to the body rows, notice how the two colors repeat until there are no more rows left to display.
  
$table->set_row_colors(
  ['#bacaba','#cbdbcb']
);

  

My MP3 Collection
Artist Album Song
Air Moon Safari La Femme DArgent
Bjork Telegram Army Of Me
  Telegram Isobel
Ozric Tentacles Jurassic Shift Sunhair
  The Hidden Step Pixel Dream
  The Hidden Step Tight Spin
  The Hidden Step Holohedron
The Police Ghost In The Machine Invisible Sun
  Reggatta De Blanc Does Everyone Stare
  Reggatta De Blanc Walking On The Moon