documentation update, some api docs, overview and tutorial upto first DM and IM including CRUD

6 files changed, 297 insertions, 13 deletions

diff --git a/lib/Reaction/UI/ViewPort/Action.pm b/lib/Reaction/UI/ViewPort/Action.pm
index b2af674..f883b92 100644
--- a/lib/Reaction/UI/ViewPort/Action.pm
+++ b/lib/Reaction/UI/ViewPort/Action.pm
@@ -68,10 +68,16 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::ViewPort::Action
+Reaction::UI::ViewPort::Action - Provide user with a form with OK, Apply and Close.
 
 =head1 SYNOPSIS
 
+  $controller->push_viewport('Reaction::UI::ViewPort::Action',
+    model           => $interface_model_action,
+    field_order     => [qw( firstname lastname )],
+    excluded_fields => [qw( password )],
+  );
+
 =head1 DESCRIPTION
 
 This subclass of L<Reaction::UI::ViewPort::Object::Mutable> is used for 
@@ -79,6 +85,15 @@ rendering a complete form supporting Apply, Close and OK.
 
 =head1 ATTRIBUTES
 
+=head2 message
+
+=head2 model
+
+Inherited from L<Reaction::UI::ViewPort::Object::Mutable>. Must be a
+L<Reaction::InterfaceModel::Action>.
+
+Also handles C<error_message> and C<has_error_message> methods.
+
 =head2 method
 
 post / get
@@ -91,10 +106,41 @@ Returns true if a field has been edited.
 
 =head2 can_apply
 
+Returns true if no field C<needs_sync> and the L</model> C<can_apply>.
+
 =head2 do_apply
 
+Delegates to C<do_apply> on the L</model>, which is a 
+L<Reaction::InterfaceModel::Action>.
+
 =head2 sync_action_from_fields
 
+Firstly calls C<sync_to_action> on every L<Reaction::UI::ViewPort::Field::Mutable>
+in L<fields|Reaction::UI::ViewPort::Object/fields>. Then it calls C<sync_all> on
+the L<Reaction::InterfaceModel::Action> in L</model>. Next it will call
+C<sync_from_action> on every field to repopulate them from the L</model>.
+
+=head1 SUBCLASSING
+
+  package MyApp::UI::ViewPort::Action;
+  use Reaction::Class;
+  use MooseX::Types::Moose qw( Int );
+
+  use namespace::clean -except => 'meta';
+
+  extends 'Reaction::UI::ViewPort::Action';
+
+  has render_timestamp => (
+    is       => 'ro',
+    isa      => Int,
+    default  => sub { time },
+    required => 1,
+  );
+
+  has '+field_order' => (default => sub {[qw( firstname lastname )]});
+
+  1;
+
 =head1 SEE ALSO
 
 L<Reaction::UI::ViewPort>
diff --git a/lib/Reaction/UI/ViewPort/Action/Role/Apply.pm b/lib/Reaction/UI/ViewPort/Action/Role/Apply.pm
index e65b9e7..23d5b97 100644
--- a/lib/Reaction/UI/ViewPort/Action/Role/Apply.pm
+++ b/lib/Reaction/UI/ViewPort/Action/Role/Apply.pm
@@ -32,27 +32,60 @@ __END__
 
 =head1 NAME
 
-Reaction::UI::ViewPort::Action::Role::Apply
+Reaction::UI::ViewPort::Action::Role::Apply - Integrate an Apply event into the ViewPort
+
+=head1 SYNOPSIS
+
+  package MyApp::UI::ViewPort::SomeAction;
+  use Reaction::Class;
+
+  use namespace::clean -except => 'meta';
+
+  extends 'Reaction::UI::ViewPort::Object::Mutable';
+  with    'Reaction::UI::ViewPort::Action::Role::Apply';
+
+  ...
+  1;
+
+=head1 DESCRIPTION
+
+This role integrates an C<apply> event into the consuming viewport that will call the
+required L</do_apply> role.
+
+=head1 REQUIRED METHODS
+
+=head2 do_apply
+
+Will be called when an L</apply> event comes in.
 
 =head1 ATTRIBUTES
 
 =head2 apply_label
 
-Default: 'apply'
+Defaults to 'apply', returned by L</_build_apply_label>.
 
 =head2 on_apply_callback
 
-CodeRef.
+CodeRef. Will be called after L</apply> if L</can_apply> and L</do_apply> return
+true. See L</apply> for argument details.
 
 =head1 METHODS
 
 =head2 can_apply
 
+Returns true by default. Determines if L</do_apply> can be called.
+
 =head2 apply
 
 Calls a user-supplied C<do_apply> and if it is successful runs the
 C<on_apply_callback> passing C<$self> and the result of C<do_apply> as args.
 
+=head1 INTERNAL METHODS
+
+=head2 _build_apply_label
+
+Defaults to C<apply>.
+
 =head1 SEE ALSO
 
 L<Reaction::UI::ViewPort::Action::Role::Close>
diff --git a/lib/Reaction/UI/ViewPort/Action/Role/Close.pm b/lib/Reaction/UI/ViewPort/Action/Role/Close.pm
index f236a9d..fec6f91 100644
--- a/lib/Reaction/UI/ViewPort/Action/Role/Close.pm
+++ b/lib/Reaction/UI/ViewPort/Action/Role/Close.pm
@@ -42,34 +42,71 @@ __END__
 
 =head1 NAME
 
-Reaction::UI::ViewPort::Action::Role::Close
+Reaction::UI::ViewPort::Action::Role::Close - Integrate Close and Apply events into ViewPort
+
+=head1 SYNOPSIS
+
+  package MyApp::UI::ViewPort::SomeAction;
+  use Reaction::Class;
+
+  use namespace::clean -except => 'meta';
+
+  extends 'Reaction::UI::ViewPort::Object::Mutable';
+  with    'Reaction::UI::ViewPort::Action::Role::Close';
+
+  ...
+  1;
+
+=head1 DESCRIPTION
+
+This role integrates a C<close> event and inherits an
+L<apply|Reaction::UI::ViewPort::Action::Role::Close/apply>
+event into the consuming viewport.
 
 =head1 ATTRIBUTES
 
 =head2 close_label
 
-Default: C<close_label_close>
+Defaults to returned string value of L</_build_close_label> (C<close>).
 
 =head2 close_label_close
 
-Default: 'close'
+Defaults to returned string value of L</_build_close_label_close> (C<close>).
 
 =head2 close_label_cancel
 
-This label is only shown when C<changed> is true.
+This label is only shown when C<changed> is true. It is initialised
+with the returned string value of L</_build_close_label_cancel>.
 
 Default: 'cancel'
 
 =head2 on_close_callback
 
-CodeRef.
+CodeRef. If set will be called on L</close>.
 
 =head1 METHODS
 
 =head2 close
 
+Calls L</on_close_callback> if one is set.
+
 =head2 can_close
 
+Returns true.
+
+=head2 apply
+
+Extends L<Reaction::UI::ViewPort::Action::Role::Apply/apply> and sets
+the L</close_label> to L</close_label_cancel> if the original call to
+C<apply> was not successfull.
+
+Returns the result of the original C<apply> call.
+
+=head2 accept_events
+
+Extends L<Reaction::UI::ViewPort::Action::Role::Apply/accept_events>
+with the C<close> event if an L</on_close_callback> was provided.
+
 =head1 SEE ALSO
 
 L<Reaction::UI::ViewPort::Action::Role::Apply>
diff --git a/lib/Reaction/UI/ViewPort/Action/Role/OK.pm b/lib/Reaction/UI/ViewPort/Action/Role/OK.pm
index 38001f8..06fe0c7 100644
--- a/lib/Reaction/UI/ViewPort/Action/Role/OK.pm
+++ b/lib/Reaction/UI/ViewPort/Action/Role/OK.pm
@@ -25,13 +25,33 @@ __END__
 
 =head1 NAME
 
-Reaction::UI::ViewPort::Action::Role::Close
+Reaction::UI::ViewPort::Action::Role::OK - Integrate OK, Apply and Close events
+
+=head1 SYNOPSIS
+
+  package MyApp::UI::ViewPort::SomeAction;
+  use Reaction::Class;
+
+  use namespace::clean -except => 'meta';
+
+  extends 'Reaction::UI::ViewPort::Object::Mutable';
+  with    'Reaction::UI::ViewPort::Action::Role::OK';
+
+  ...
+  1;
+
+=head1 DESCRIPTION
+
+This role integrates an C<ok> event and inherits a 
+L<close|Reaction::UI::ViewPort::Action::Role::Close/close>
+and an L<apply|Reaction::UI::ViewPort::Action::Role::Apply/apply>
+event into the consuming viewport.
 
 =head1 ATTRIBUTES
 
 =head2 ok_label
 
-Default: 'ok'
+Defaults to C<ok>. String is built by L</_build_ok_label>.
 
 =head1 METHODS
 
@@ -39,6 +59,18 @@ Default: 'ok'
 
 Calls C<apply>, and then C<close> if successful.
 
+=head2 accept_events
+
+Extends L<Reaction::UI::ViewPort::Action::Role::Close/accept_events> with the
+event C<ok> if an L<on_close_callback|Reaction::UI::ViewPort::Action::Role::Close/on_close_callback>
+was provided.
+
+=head1 INTERNAL METHODS
+
+=head2 _build_ok_label
+
+Returns the string representing the label for the OK action. Defaults to C<ok>.
+
 =head1 SEE ALSO
 
 L<Reaction::UI::ViewPort::Action::Role::Apply>
diff --git a/lib/Reaction/UI/ViewPort/Object.pm b/lib/Reaction/UI/ViewPort/Object.pm
index ed68f20..9c96237 100644
--- a/lib/Reaction/UI/ViewPort/Object.pm
+++ b/lib/Reaction/UI/ViewPort/Object.pm
@@ -247,26 +247,66 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::ViewPort::Object
+Reaction::UI::ViewPort::Object - Display an InterfaceModel::Object
+
+=head1 SYNOPSIS
+
+  use aliased 'Reaction::UI::ViewPort::Object';
+
+  ...
+  $controller->push_viewport(Object,
+    model           => $person_interface_model_object,
+    fields_order    => [qw( firstname lastname )],
+    excluded_fields => [qw( password )],
+  );
 
 =head1 DESCRIPTION
 
+Takes a L<Reaction::InterfaceModel::Object> class and displays the
+configured fields.
+
 =head1 ATTRIBUTES
 
 =head2 model
 
+Required L<Reaction::InterfaceModel::Object>.
+
 =head2 fields
 
+Initialised via L</_build_fields>
+
 =head2 field_args
 
+Hash reference keyed by field names. Values are hash references containing
+arguments to the field builder method of the attribute.
+
 =head2 field_order
 
+Array reference of strings defining the order of all fields (including
+the ones that might be excluded).
+
 =head2 builder_cache
 
+Hash reference containing resolved builder method names per field. Utilised
+by L</_build_fields>
+
 =head2 excluded_fields
 
+Array reference of strings naming fields to exclude from the interface.
+
 =head2 computed_field_order
 
+Array reference of strings Initialised by the L</_computed_field_order> method.
+Contains the fields to show in the correct order.
+
+=head2 containers
+
+Array reference populated by L</_build_containers>.
+
+=head2 container_layouts
+
+Array reference containing container layout specifications.
+
 =head1 INTERNAL METHODS
 
 These methods, although stable, are subject to change without notice. These are meant
@@ -275,10 +315,61 @@ avoid potential breakages.
 
 =head2 BUILD
 
+Takes the value of the C<Field> constructor argument, if true, and sets it as
+the new L</field_args> hash reference.
+
 =head2 get_builder_for
 
+Takes an attribute object as argument and returns a string containing
+the name of the method that builds the fields for this attribute.
+
+If the viewport implements it, C<_build_fields_for_name_${attr_name}> will be used.
+
+If that is not available, it will take the C<isa> information of the type constraint
+and see if it is a loaded class implementing C<meta>. If it is, every class in its
+C<class_precedence_list> will be taken and used to try to find a 
+C<_build_fields_for_type_${mangled_class_name}> method on the viewport.
+
+"mangled" means here that every C<:*> will be replaced with C<_>. For example:
+C<Foo::Bar> would become C<Foo_Bar>.
+
+If the C<isa> information was not obtainable or no fitting method was found, it will
+try the type name in a method named C<_build_fields_for_type_${mangled_type_name}>.
+
+If could be found on this constraint, it will make the same attempts to find a
+method on its parent type constraint.
+
+This method will die if it can't locate a method to build a field for this
+attribute.
+
+=head2 _build_containers
+
+Uses L</container_layouts> to build a list of L<Reaction::UI::ViewPort::Field::Container>
+objects.
+
+=head2 _build_fields
+
+Takes the L</model>s C<parameter_attributes> to build fields via L</get_builder_for>.
+They will be ordered as specified in L</computed_field_order>.
+
+=head2 _build_computed_field_order
+
+Takes the names of the L</model>s C<parameter_attributes>' reader methods and assumes
+them as field names. Then it uses L</field_order> and L</excluded_fields> to calculate
+the order of all included fields and returns those names.
+
 =head2 _build_simple_field
 
+  $self->_build_simple_field(
+    attribute => $attribute_object,
+    class     => $field_class,
+    %field_attrs,
+  );
+
+Takes an attribute meta object, a field class (a L<Reaction::UI::ViewPort::Field> subclass)
+and an additional set of arguments to pass to the field constructor and returns the new
+field. Field classes themselves are L<Reaction::UI::ViewPort> subclasses.
+
 =head2 _build_fields_for_type_Num
 
 =head2 _build_fields_for_type_Int
@@ -301,6 +392,20 @@ avoid potential breakages.
 
 =head2 _build_fields_for_type_Reaction_InterfaceModel_Collection
 
+=head1 FIELD TYPES
+
+L<Text|Reaction::UI::ViewPort::Field::Text>,
+L<Number|Reaction::UI::ViewPort::Field::Number>,
+L<Integer|Reaction::UI::ViewPort::Field::Integer>,
+L<Boolean|Reaction::UI::ViewPort::Field::Boolean>,
+L<String|Reaction::UI::ViewPort::Field::String>,
+L<DateTime|Reaction::UI::ViewPort::Field::DateTime>,
+L<RelatedObject|Reaction::UI::ViewPort::Field::RelatedObject>,
+L<Array|Reaction::UI::ViewPort::Field::Array>,
+L<Collection|Reaction::UI::ViewPort::Field::Collection>,
+L<File|Reaction::UI::ViewPort::Field::File>,
+L<Container|Reaction::UI::ViewPort::Field::Container>
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
diff --git a/lib/Reaction/UI/ViewPort/Object/Mutable.pm b/lib/Reaction/UI/ViewPort/Object/Mutable.pm
index e58f1b4..66d6fa9 100644
--- a/lib/Reaction/UI/ViewPort/Object/Mutable.pm
+++ b/lib/Reaction/UI/ViewPort/Object/Mutable.pm
@@ -111,10 +111,17 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::ViewPort::Object::Mutable
+Reaction::UI::ViewPort::Object::Mutable - Allow the user to to perform an InterfaceModel Action
 
 =head1 SYNOPSIS
 
+  use aliased 'Reaction::UI::ViewPort::Object::Mutable';
+
+  ...
+  $controller->push_viewport(Mutable,
+    model => $interface_model_action,
+  );
+
 =head1 DESCRIPTION
 
 This subclass of L<Reaction::UI::ViewPort::Object> is used for rendering a
@@ -128,6 +135,30 @@ L<Reaction::InterfaceModel::Action>
 
 =head1 METHODS
 
+=head2 is_modified
+
+Returns true if any of the L<fields|Reaction::UI::ViewPort::Object/fields> has been
+modified.
+
+=head1 INTERNAL METHODS
+
+The builder methods are resolved in the same way as described in L<Reaction::UI::ViewPort::Object>,
+but they create L<Reaction::UI::ViewPort::Field::Mutable> objects.
+
+=head2 Mutable Field Types
+
+L<Text|Reaction::UI::ViewPort::Field::Mutable::Text>,
+L<Array|Reaction::UI::ViewPort::Field::Mutable::Array>,
+L<String|Reaction::UI::ViewPort::Field::Mutable::String>,
+L<Number|Reaction::UI::ViewPort::Field::Mutable::Number>,
+L<Integer|Reaction::UI::ViewPort::Field::Mutable::Integer>,
+L<Boolean|Reaction::UI::ViewPort::Field::Mutable::Boolean>,
+L<Password|Reaction::UI::ViewPort::Field::Mutable::Password>,
+L<DateTime|Reaction::UI::ViewPort::Field::Mutable::DateTime>,
+L<ChooseOne|Reaction::UI::ViewPort::Field::Mutable::ChooseOne>,
+L<ChooseMany|Reaction::UI::ViewPort::Field::Mutable::ChooseMany>,
+L<Files|Reaction::UI::ViewPort::Field::Mutable::File>
+
 =head2  _build_fields_for_type_Num
 
 =head2  _build_fields_for_type_Int