NAME

DBIx::IO::Mask - Help make id values more meaningful to humans

SYNOPSIS

use DBIx::IO::Mask;


$masker = new DBIx::IO::Mask($dbh,$field_name);
$masker = new DBIx::IO::Mask($dbh,undef,$table_name,$masked_col_name,$id_col_name,$no_cache);

$valid_values = $masker->pick_list();

$masked_value = $masker->mask($id_val);

$id = $masker->unmask($masked_value);

$ids_to_mask_hash = $masker->ids_to_mask();

DESCRIPTION

For applications that interface a human to a database, e.g. CGI, this class makes database numeric ID values more meaningful to humans. It can also present a sorted list of valid values to use in pop-up lists, where only certain values are allowed in the database. It does this in conjunction with DBIx::IO::Search.

The general strategy is that any column you want masked or that has a discrete set of values, should have a corresponding table with those set of values. The table name should be the same as the ID column name except with no _ID at the end. The table should have at least 2 columns in it:

<COLUMN_NAME> - The name of the column you want masked,
it stores the ID values, and does not necessarily have
to be a numeric datatype.
USER_MASK - This column stores values that describe the id values

This way a new $masker object can be created by just knowing the name of the column you want masked. Example:

To get a sorted list of valid values for a column named STATE, create a table named STATE with 2 columns, STATE and USER_MASK with all states represented therein. Then:

$masker = new DBIx::IO::Mask($dbh,'STATE');
$states = $masker->pick_list();

This is the easy way, however if you have a table with a set of IDs and descriptions that doesn't conform to the guidelines above (or you just think the whole scenario is dumb), you can specify the table name and desired column names in the constructor.

All tables read are cached in class variables for efficiency. This may be significant if you're using persistent objects/classes with such environments as mod_perl.

Happy Halloween

METHOD DETAILS

new (constructor)

$masker = new DBIx::IO::Mask($dbh,$field_name);
$masker = new DBIx::IO::Mask($dbh,undef,$table_name,$masked_col_name,$id_col_name,$no_cache);

Create a new $masker object for all your masking pleasures with a db handle, $dbh from DBI (or DBIAccess). The rest of the arguments are optional: $table_name contains all the valid values; it defaults to $field_name minus '_ID', which may or may not be present. $id_col_name is the name of the column that contains the id values in $table_name that are masked; it defaults to $field_name. $masked_col_name is the column in $table_name that has the meaningful values the ids refer to; it defaults to 'USER_MASK'. If $no_cache is true, then the cache will be refreshed (data will be pulled from the db, not the cache).

Return 0 if $table_name doesn't exist, or no values to mask were found. Return undef if error.

pick_list

$valid_values = $masker->pick_list();

Return a machine sorted list of masks and ids where each element is a hash with keys:

ID => the id value
MASK => a meaningful indicator of what ID refers to

ids_to_mask

$ids_to_mask_hash = $masker->ids_to_mask();

Return a hash ref of id => mask_value pairs where each key is an id value and each value is meaningful to a human.

mask

$masked_value = $masker->mask($id_val);

Return the $masked_value of $id_val.

unmask

$id = $masker->unmask($masked_value);

Return the $id of a $masked_value. CAUTION: Use ONLY if the masked value column has a unique constraint on it.

BUGS

No known bugs.

SEE ALSO

DBIx::IO::Table, DBIx::IO::Search, DBIx::IO

AUTHOR

Reed Sandberg, <reed_sandberg Ó’ yahoo>

COPYRIGHT AND LICENSE

Copyright (C) 2000-2008 Reed Sandberg

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.