lib/DBIx/Class/Manual/Component.pod

   1
   2 =head1 NAME
   3
   4 DBIx::Class::Manual::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 important, 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 COMPONENTS
  35
  36 =head2 Extra
  37
  38 These components provide extra functionality beyond
  39 basic functionality that you can't live without.
  40
  41 L<DBIx::Class::CDBICompat> - Class::DBI Compatibility layer.
  42
  43 L<DBIx::Class::FormTools> - Build forms with multiple interconnected objects.
  44
  45 L<DBIx::Class::HTMLWidget> - Like FromForm but with DBIx::Class and HTML::Widget.
  46
  47 L<DBIx::Class::PK::Auto> - Retrieve automatically created primary keys upon insert.
  48
  49 L<DBIx::Class::QueriesTime> - Display the amount of time it takes to run queries.
  50
  51 L<DBIx::Class::RandomStringColumns> - Declare virtual columns that return random strings.
  52
  53 L<DBIx::Class::UTF8Columns> - Force UTF8 (Unicode) flag on columns.
  54
  55 L<DBIx::Class::UUIDColumns> - Implicit UUID columns.
  56
  57 L<DBIx::Class::WebForm> - CRUD methods.
  58
  59 =head2 Experimental
  60
  61 These components are under development, there interfaces may
  62 change, they may not work, etc.  So, use them if you want, but
  63 be warned.
  64
  65 L<DBIx::Class::Serialize> - Hooks for Storable freeze/thaw.
  66
  67 L<DBIx::Class::Serialize::Storable> - Hooks for Storable freeze/thaw.
  68
  69 L<DBIx::Class::Validation> - Validate all data before submitting to your database.
  70
  71 L<DBIx::Class::Positional> - Modify the position of objects in an ordered list.
  72
  73 L<DBIx::Class::Tree::AdjacencyList> - Manage a tree of data using the common adjacency list model.
  74
  75 L<DBIx::Class::Tree::NestedSet> - Manage a positional tree of data using the nested set model.
  76
  77 =head2 Core
  78
  79 These are the components that all, or nearly all, people will use
  80 without even knowing it.  These components provide most of
  81 DBIx::Class' functionality.
  82
  83 L<DBIx::Class::AccessorGroup> - Lets you build groups of accessors.
  84
  85 L<DBIx::Class::Core> - Loads various components that "most people" would want.
  86
  87 L<DBIx::Class::DB> - Non-recommended classdata schema component.
  88
  89 L<DBIx::Class::InflateColumn> - Automatically create objects from column data.
  90
  91 L<DBIx::Class::PK> - This class contains methods for handling primary keys and methods depending on them.
  92
  93 L<DBIx::Class::Relationship> - Inter-table relationships.
  94
  95 L<DBIx::Class::ResultSourceProxy::Table> - Provides a classdata table object and method proxies.
  96
  97 L<DBIx::Class::Row> - Basic row methods.
  98
  99 =head1 CREATEING COMPONENTS
 100
 101 Making your own component is very easy.
 102
 103   package DBIx::Class::MyComp;
 104   use base qw(DBIx::Class);
 105   # Create methods, accessors, load other components, etc.
 106   1;
 107
 108 When a component is loaded it is included in the calling
 109 class' inheritance chain using L<Class::C3>.  As well as
 110 providing custom utility methods, a component may also
 111 override methods provided by other core components, like
 112 L<DBIx::Class::Row> and others.  For example, you
 113 could override the insert and delete methods.
 114
 115   sub insert {
 116     my $self = shift;
 117     # Do stuff with $self, like set default values.
 118     return $self->nest::method( @_ );
 119   }
 120
 121   sub delete {
 122     my $self = shift;
 123     # Do stuff with $self.
 124     return $self->nest::method( @_ );
 125   }
 126
 127 Now, the order that a component is loaded is very important.  Components
 128 that are loaded first are the first ones in the inheritance stack.  So, if
 129 you override insert() but the DBIx::Class::Row component is loaded first
 130 then your insert() will never be called, since the DBIx::Class::Row insert()
 131 will be called first.  If you are unsure as to why a given method is not
 132 being called try printing out the Class::C3 inheritance stack.
 133
 134   print join ', ' => Class::C3::calculateMRO('YourClass::Name');
 135
 136 Check out the L<Class::C3> docs for more information about inheritance.
 137
 138 =head1 SEE ALSO
 139
 140 L<DBIx::Class::Manual::Cookbook>
 141
 142 L<DBIx::Class::Manual::FAQ>
 143
 144 =head1 AUTHOR
 145
 146 Aran Clary Deltac <bluefeet@cpan.org>
 147