NAME

Locale::MakePhrase::BackingStore::Database - Base-class for a database driven backing store.

DESCRIPTION

This backing store is capable of loading language rules from a database table, which conforms to the structure defined below.

It assumes that the database is configured to use unicode as the text storage mechanism.

Unlike the file-based implementations, this module will hit the database looking for language translations, every time the language rules are requested. This allows you to update the database (say via a web interface), so that new translations are available immediately.

TABLE STRUCTURE

The table structure can be created with the following SQL statement:

CREATE TABLE some_table (
  key VARCHAR,
  language VARCHAR,
  expression VARCHAR,
  priority INTEGER,
  translation VARCHAR
);

As you can see, there is not much to it.

Upon construction, this module will try to connect to the database to confirm that the table exists and has a suitable structure. If it hasn't, this module will die.

API

The following methods are implemented:

$self new([...])

You will need to specify some of these options:

table

The name of the table that implements the table structure shown above. Note you can add more database fields if necessary; then by overloading either get_query or get_where. you can make use of the extra fields.

dbh

You can supply a pre-connected DBI handle, rather than supply the connection parameters.

owned

If you supply a database handle, you should specify whether you want this module to take ownership of the handle. If so, it will disconnect the database handle on destruction.

driver

The name of the DBI driver to use.

database

The name of the database that we will connect to.

host

port

user

password

By specifying these four options (rather than the dbh), this module will connect to the database using these options. Note that host and port defaults to whatever the underlying driver uses, user and password defaults to empty.

The defaults are used when you dont supply any connection parameters.

connect_options

This option is simply a placeholder - it is up to the driver-specific implementation to use this option.

Notes: you must specify either the dbh option, or suitable connection options.

$dbh dbh()

Returns the database connection handle

void owned(boolean)

Set/get ownership of the database handle.

\@rule_objs get_rules($contect,$key,\@languages)

Retrieve the translations from the database, using the selected languages. The implementation will fetch the language rule properties each time this is called, so that if the database gets updated, the next call will use the new properties.

$string get_query($table,$context,\@languages)

Under normal circumstances the generic SQL statement used by this module, is suitable to be used to query the database. However, in some cases you may want to do something unusual... By sub-classing this module, you can create your own specific SQL statement.

$string get_where()

Under some circumstances the generic get_query() command will generate an SQL statement that is mostly correct, but needs minor adjustment. By overloading this method, you can _add to_ the existing SQL statement.

If you want to know what this does, you should probably read the source code for this module.