lib/DBIx/Class/ResultSource/View.pm

   1 package DBIx::Class::ResultSource::View;
   2
   3 use strict;
   4 use warnings;
   5
   6 use DBIx::Class::ResultSet;
   7
   8 use base qw/DBIx::Class/;
   9 __PACKAGE__->load_components(qw/ResultSource/);
  10 __PACKAGE__->mk_group_accessors(
  11   'simple' => qw(is_virtual view_definition)
  12 );
  13
  14 =head1 NAME
  15
  16 DBIx::Class::ResultSource::View - ResultSource object representing a view
  17
  18 =head1 SYNOPSIS
  19
  20   package MyDB::Schema::Year2000CDs;
  21
  22   use DBIx::Class::ResultSource::View;
  23
  24   __PACKAGE__->load_components('Core');
  25   __PACKAGE__->table_class('DBIx::Class::ResultSource::View');
  26
  27   __PACKAGE__->table('year2000cds');
  28   __PACKAGE__->result_source_instance->is_virtual(1);
  29   __PACKAGE__->result_source_instance->view_definition(
  30       "SELECT cdid, artist, title FROM cd WHERE year ='2000'"
  31       );
  32
  33 =head1 DESCRIPTION
  34
  35 View object that inherits from L<DBIx::Class::ResultSource>
  36
  37 This class extends ResultSource to add basic view support.
  38
  39 A view has a L</view_definition>, which contains an SQL query. The
  40 query cannot have parameters. It may contain JOINs, sub selects and
  41 any other SQL your database supports.
  42
  43 View definition SQL is deployed to your database on
  44 L<DBIx::Class::Schema/deploy> unless you set L</is_virtual> to true.
  45
  46 Deploying the view does B<not> translate it between different database
  47 syntaxes, so be careful what you write in your view SQL.
  48
  49 Virtual views (L</is_virtual> unset or false), are assumed to not
  50 exist in your database as a real view. The L</view_definition> in this
  51 case replaces the view name in a FROM clause in a subselect.
  52
  53 =head1 SQL EXAMPLES
  54
  55 =over
  56
  57 =item is_virtual set to true
  58
  59   $schema->resultset('Year2000CDs')->all();
  60
  61   SELECT cdid, artist, title FROM year2000cds me
  62
  63 =item is_virtual set to false
  64
  65   $schema->resultset('Year2000CDs')->all();
  66
  67   SELECT cdid, artist, title FROM
  68     (SELECT cdid, artist, title FROM cd WHERE year ='2000') me
  69
  70 =back
  71
  72 =head1 METHODS
  73
  74 =head2 is_virtual
  75
  76   __PACKAGE__->result_source_instance->is_virtual(1);
  77
  78 Set to true for a virtual view, false or unset for a real
  79 database-based view.
  80
  81 =head2 view_definition
  82
  83   __PACKAGE__->result_source_instance->view_definition(
  84       "SELECT cdid, artist, title FROM cd WHERE year ='2000'"
  85       );
  86
  87 An SQL query for your view. Will not be translated across database
  88 syntaxes.
  89
  90
  91 =head1 OVERRIDDEN METHODS
  92
  93 =head2 from
  94
  95 Returns the FROM entry for the table (i.e. the view name)
  96 or the SQL as a subselect if this is a virtual view.
  97
  98 =cut
  99
 100 sub from {
 101   my $self = shift;
 102   return \"(${\$self->view_definition})" if $self->is_virtual;
 103   return $self->name;
 104 }
 105
 106 1;
 107
 108 =head1 AUTHORS
 109
 110 Matt S. Trout <mst@shadowcatsystems.co.uk>
 111
 112 With Contributions from:
 113
 114 Guillermo Roditi E<lt>groditi@cpan.orgE<gt>
 115
 116 Jess Robinson <castaway@desert-island.me.uk>
 117
 118 =head1 LICENSE
 119
 120 You may distribute this code under the same terms as Perl itself.
 121
 122 =cut
 123