NAME

RapidApp::DBIC::RelationTreeFlattener

SYNOPSIS

  my $spec= RapidApp::DBIC::RelationTreeSpec->new(
    source => $db->source('Object'),
    colSpec => [qw( user.* -user.password contact.* creator_id owner_id is_deleted contact.timezone.ofs )]
  );
  
  my $flattener= RapidApp::DBIC::RelationTreeFlattener->new(spec => $spec);
  
  my $treed= {
    creator_id => 5,
    owner_id => 7,
    is_deleted => 0,
    user => { username => 'foo', department => 'billing' },
    contact => {
      first => 'John',
      last => 'Doe',
      timezone => { ofs => -500 }
    },
  };
  my $flattened= {
    creator_id => 5,
    owner_id => 7,
    is_deleted => 0,
    user_username => 'foo',
    user_department => 'billing',
    contact_first => 'John',
    contact_last => 'Doe',
    contact_timezone_ofs => -500,
  };
  
  is_deeply( $flattener->flatten($treed), $flattened, 'flatten a tree' );
  is_deeply( $flattener->restore($flattened), $treed, 'restore a tree' );

DESCRIPTION

This module takes a tree of DBIC data and flattens it into a simple hash that can be used by things that expect a single-level hash, like ExtJS's Stores, and all the components based on Stores like AppStoreForm2.

In the default naming convention, the key names of the flattened hash are chosen by concatenating the path of relations that lead up to a column, separated by underscore. This is not guaranteed to work in all cases, though, because underscore is often used in column names.

Other naming conventions can work around this problem. However, they have not been tested yet with the rest of RapidApp. So, for now, stick with "concat_"

ATTRIBUTES

spec : RapidApp::DBIC::RelationTreeSpec

The spec determines what relations and columns are considered. Any hash keys encountered which are not in the spec will either be ignored or throw an error, depending on the attribute "ignoreUnexpected".

namingConvention : enum

The naming convention to use for flattening column names. Defaults to standard "concat_" system of DbicLink / DataStore2, which joins relation and columns with underscore.

Other (untested) schemes are "concat__" and "brief".

ignoreUnexpected : bool

Whether or not unexpected hash keys should generate exceptions. Defaults to true (ignore them).

METHODS

$flatHash= $self->flatten( $hashTree )

Takes a tree of values and converts it to a flattened hash.

Example:

  {
    foo => 12,
    bar => { baz => 13 }
  }

Becomes:

  {
    foo => 12,
    bar_baz => 13,
  }

$keyName= $self->colToFlatKey( @colPath || \@colPath || $ColPath )

Converts a column specified by relation path into the name of a key used for the flattened view.

$hashTree= $self->restore( $flatHash )

Take a flattened hash and restore it to its treed form.

Reverse of ->flatten();

$colPath= $self->flatKeyToCol( $key )

Returns the column that maps to the specified flat key.

$colPath= $self->flatKeyToCol( $key )

Returns a list (not arrayref) of all flat key names supported by this flattener.

$newFlattener= $self->subset( @colspec || \@colspec || $relationTreeSpec )

This method creates a new RelationTreeFlattener which only deals with a subset of the columns of the current one. An especially useful feature of this method is that the new RelationTreeFlattener uses the exact same name mapping as the current one, which might not be the case if you were to create a RelationTreeFlattener from the smaller column list.

cpanm RapidApp

perl -MCPAN -e shell
install RapidApp