lib/DBIx/Class/Manual/Component.pod

   1
   2 =head1 NAME
   3
   4 DBIx::Class::Manula::Component - Existing components and how to develop new ones.
   5
   6 =head1 USING
   7
   8 Components are loaded using the load_components() method within your
   9 DBIx::Class classes.
  10
  11   package My::Thing;
  12   use base qw( DBIx::Class );
  13   __PACKAGE__->load_components(qw( PK::Auto Core ));
  14
  15 Generally you do not want to specify the full package name
  16 of a component, instead take off the DBIx::Class:: part of
  17 it and just include the rest.  If you do want to load a
  18 component outside of the normal namespace you can do so
  19 by prepending the component name with a +.
  20
  21   __PACKAGE__->load_components(qw( +My::Component ));
  22
  23 Once a component is loaded all of it's methods, or otherwise,
  24 that it provides will be available in your class.
  25
  26 The order in which is you load the components may be
  27 very imporant, depending on the component.  The general
  28 rule of thumb is to first load extra components and then
  29 load core ones last.  If you are not sure, then read the
  30 docs for the components you are using and see if they
  31 mention anything about the order in which you should load
  32 them.
  33
  34 =head1 EXISTING
  35
  36 =head2 Extra
  37
  38 These components provide extra functionality above
  39 and beyond what any normal user would need out of the
  40 box.
  41
  42 L<DBIx::Class::CDBICompat> - Class::DBI Compatability layer.
  43
  44 L<DBIx::Class::PK::Auto> - Retrieve automatically created primary keys upon insert.
  45
  46 L<DBIx::Class::FormTools> - Build forms with multiple interconnected objects.
  47
  48 L<DBIx::Class::HTMLWidget> - Like FromForm but with DBIx::Class and HTML::Widget.
  49
  50 L<DBIx::Class::QueriesTime> - Display the amount of time it takes to run queries.
  51
  52 L<DBIx::Class::RandomStringColumns> - Declare virtual columns that return random strings.
  53
  54 L<DBIx::Class::UTF8Columns> - Force UTF8 (Unicode) flag on columns.
  55
  56 L<DBIx::Class::UUIDColumns> - Implicit UUID columns.
  57
  58 L<DBIx::Class::WebForm> - CRUD methods.
  59
  60 =head2 Experimental
  61
  62 These components are under development, there interfaces may
  63 change, they may not work, etc.  So, use them if you want, but
  64 be warned.
  65
  66 L<DBIx::Class::Serialize> - Hooks for Storable freeze/thaw.
  67
  68 L<DBIx::Class::Serialize::Storable> - Hooks for Storable freeze/thaw.
  69
  70 L<DBIx::Class::Validation> - Validate all data before submitting to your database.
  71
  72 =head2 Core
  73
  74 These are the components that all, or nearly all, people will use
  75 without even knowing it.  These components provide most of
  76 DBIx::Class' functionality.
  77
  78 L<DBIx::Class::Core> - Loads various components that "most people" would want.
  79
  80 L<DBIx::Class::DB> - Non-recommended classdata schema component.
  81
  82 L<DBIx::Class::InflateColumn> - Automatically create objects from column data.
  83
  84 L<DBIx::Class::Relationship> - Inter-table relationships.
  85
  86 L<DBIx::Class::PK> - This class contains methods for handling primary keys and methods depending on them.
  87
  88 L<DBIx::Class::Row> - Basic row methods.
  89
  90 L<DBIx::Class::ResultSourceProxy::Table> - Provides a classdata table object and method proxies.
  91
  92 L<DBIx::Class::AccessorGroup> - Lets you build groups of accessors.
  93
  94 =head1 CREATEING
  95
  96 Making your own component is very easy.
  97
  98   package DBIx::Class::MyComp;
  99   use base qw(DBIx::Class);
 100   # Create methods, accessors, load other components, etc.
 101   1;
 102
 103 When a component is loaded it is included in the calling
 104 classes inheritance chain using L<Class::C3>.  As well as
 105 providing custom utility methods, a component may also
 106 override methods provided by other core components, like
 107 L<DBIx::Class::Row> and others.  For example, you
 108 could override the insert and delete methods.
 109
 110   sub insert {
 111     my $self = shift;
 112     # Do stuff with $self, like set default values.
 113     return $self->nest::method( @_ );
 114   }
 115
 116   sub delete {
 117     my $self = shift;
 118     # Do stuff with $self.
 119     return $self->nest::method( @_ );
 120   }
 121
 122 Now, the order that a component is loaded is very important.  Components
 123 that are loaded first are the first ones in the inheritance stack.  So, if
 124 you override insert() but the DBIx::Class::Row component is loaded first
 125 then your insert() will never be called, since the DBIx::Class::Row insert()
 126 will be called first.  If you are unsure as to why a given method is not
 127 being called try printing out the Class::C3 inheritance stack.
 128
 129   print join ', ' => Class::C3::calculateMRO('YourClass::Name');
 130
 131 Check out the L<Class::C3> docs for more information.
 132
 133 =head1 SEE ALSO
 134
 135 L<DBIx::Class::Manual::Cookbook>
 136
 137 L<DBIx::Class::Manual::FAQ>
 138
 139 =head1 AUTHOR
 140
 141 Aran Clary Deltac <bluefeet@cpan.org>
 142