lib/DBIx/Class/Manual/Component.pod

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