view release on metacpan or  search on metacpan

DBIx/DBStag/Cookbook.pm  view on Meta::CPAN

You can also do this interactively using qsh

First, we need to inform stag-qsh what the schema is. The schema is
used to determine which templates are appropriate. Later we will
discover how to set up a resources file, which will allow stag to
infer the schema.

Call qsh from command line:

  stag-qsh -d dbi:Pg:dbname=cia -s cia

Interactive perl/qsh:
  
  \l
  t cia-country
  /borders_country=cid-cia-Germany

(do not leave spaces at the beginning of the line)

The above should fetch all countries bordering Germany

If we prefer objects over hierarchical formats such as XML, we can do
this using perl. For example, to print the religions of spanish
speaking countries:

Still in qsh (multi-line mode), type the following:

  # find all Spanish-speaking countries
  $dataset =
    $dbh->selectall_stag(-template=>'cia-country',-bind=>{languages_name=>'Spanish'});
  # get country objects from query results
  @lcountry = $dataset->get_country;

  foreach $country (@lcountry) { 
    printf("Country: %s\n  Religions:%s\n",
           $country->sget_name,
           join(' & ', 
                map {
                     $_->get_name.' '.$_->get_quant.'%'
                } $country->get_religions))
  }
  print "\n\nDone!\n";
  \q

See L<Data::Stag> for more details on using Stag objects

=head2 BUILDING A CGI/WEB INTERFACE

We can construct a generic but powerful default cgi interface for our
data, using ubiq.cgi, which should come with your distribution. 

You may have to modify some of the directories below, depending on
your web server set up (we assume Apache here).

We want to create the CGI, and give it access to our templates:

  mkdir /usr/local/httpd/cgi-bin/cia
  cp templates/*.stg /usr/local/httpd/cgi-bin/cia
  cp `which ubiq.cgi` /usr/local/httpd/cgi-bin/cia
  chmod +x /usr/local/httpd/cgi-bin/cia/ubiq.cgi
  mkdir /usr/local/httpd/cgi-bin/cia/cache
  chmod 777 /usr/local/httpd/cgi-bin/cia/cache

Set up the environment for the CGI script. It must be able to see the
templates and the necessary perl libraries (if not installed
system-wide)

  cat > /usr/local/httpd/cgi-bin/cia/dbenv.pl
  $ENV{DBSTAG_DBIMAP_FILE} = "./resources.conf";
  $ENV{DBSTAG_TEMPLATE_DIRS} = ".:./templates:/usr/local/share/sql/templates";
  $ENV{STAGLIB} = "/users/me/lib/DBIx-DBStag:/users/me/lib/stag";

We must create a basic resources file, currently containing one db:

  cat > /usr/local/httpd/cgi-bin/cia/resources.conf
  cia              rdb               Pg:cia        schema=cia

Fields are whitespace delimited; do not leave a space before the
initial 'cia'

(note that if you set DBSTAG_DBIMAP_FILE to the avove file on the
command line, you can use the shortened name of B<cia> instead of
B<dbi:Pg:dbname=cia>)

You should be able to use the interface via
http://localhost/cgi-bin/cia/ubiq.cgi

You can customize this by overriding some of the existing display functions;

  cat > /usr/local/httpd/cgi-bin/cia/ubiq-customize.pl
  # --- CUSTOM SETTINGS
  {
   no warnings 'redefine';
   
   *g_title = sub {
       "U * B * I * Q - CIA World Factbook";
   };
   *short_intro = sub {
       "Demo interface to CIA World Factbook"
   };
   add_initfunc(sub {
  		   $dbname = 'cia';
  		   $schema = 'cia';
  	       });
  }


From here on you can customise the web interface, create new
templates, integrate this with other data. Consult L<DBIx::DBStag> and
the script B<ubiq.cgi> for further details.

=head2 FURTHER EXPLORATION

This cookbook has focused on an example with relatively simple XML,
with only a few layers of nesting. 

There is a more complex example you can download from the Mondial
project site here:
L<http://www.dbis.informatik.uni-goettingen.de/Mondial/mondial-2.0.xml>

This also integrates data on cities, which increases the depth of the
XML tree.