Much documentation updates

5 files changed, 184 insertions, 84 deletions

diff --git a/lib/Reaction/UI/Controller.pm b/lib/Reaction/UI/Controller.pm
index 361a5c2..aa1b8be 100644
--- a/lib/Reaction/UI/Controller.pm
+++ b/lib/Reaction/UI/Controller.pm
@@ -97,11 +97,29 @@ Base Reaction Controller class. Inherits from:
 
 =head2 push_viewport $vp_class, %args
 
-Will create a new instance of $vp_class with the arguments of %args
-merged in with any arguments in the ViewPort attribute of the current
-Catalyst action (also accessible through the controller config), add
-it to the main FocusStack (C<$c-E<gt>stash-E<gt>{focus_stack}>) and
-return the instantiated viewport.
+Creates a new instance of the L<Reaction::UI::ViewPort> class
+($vp_class) using the rest of the arguments given (%args). Defaults of
+the action can be overridden by using the C<ViewPort> key in the
+controller configuration. For example to override the default number
+of items in a CRUD list action:
+
+__PACKAGE__->config(
+                    action => { 
+                        list => { ViewPort => { per_page => 50 } },
+    }
+  );
+
+The ViewPort is added to the L<Reaction::UI::Window>'s FocusStack in
+the stash, and also returned to the calling code.
+
+Related items:
+
+=over
+
+=item L<Reaction::UI::Controller::Root>
+=item L<Reaction::UI::Window>
+
+=back
 
 TODO: explain how next_action as a scalar gets converted to the redirect arrayref thing
 
@@ -109,22 +127,29 @@ TODO: explain how next_action as a scalar gets converted to the redirect arrayre
 
 =head2 pop_viewport_to $vp
 
-Shortcut to subs of the same name in the main FocusStack (C<$c-E<gt>stash-E<gt>{focus_stack}>)
+Call L<Reaction::UI::FocusStack/pop_viewport> or
+L<Reaction::UI::FocusStack/pop_viewport_to> on 
+the C<< $c->stash->{focus_stack} >>.
 
 =head2 redirect_to $c, $to, $captures, $args, $attrs
 
-If C<$to> is a string then redirects to the action of the same name  in the current
- controller (C<$c-E<gt>controller> not C<$self>).
+Construct a URI and redirect to it.
+
+$to can be:
+
+=over
 
-If C<$to> isa L<Catalyst::Action>
-it will pass the argument directly to C<$c-E<gt>uri_for>.
+=item The name of an action in the current controller.
 
-If C<$to> is an ArrayRef with two items it will treat the first as a Controller name
-and the second as the action name whithin that controller.
+=item A L<Catalyst::Action> instance.
+
+=item An arrayref of controller name and the name of an action in that
+controller.
+
+=back
 
-C<$captures>, C<$args>, and C<$attrs> are equivalent to the same arguments in
-C<uri_for>. If left blank the current request captures and args will be used
-and C<$attrs> will be passed as an empty HashRef.
+$captures and $args default to the current requests $captures and
+$args if not supplied.
 
 =head1 AUTHORS
 
diff --git a/lib/Reaction/UI/Controller/Root.pm b/lib/Reaction/UI/Controller/Root.pm
index e143bc1..7ab40b4 100644
--- a/lib/Reaction/UI/Controller/Root.pm
+++ b/lib/Reaction/UI/Controller/Root.pm
@@ -67,7 +67,7 @@ Reaction::UI::Controller::Root - Base component for the Root Controller
   );
 
   # Create UI elements:
-  $c->stash->{focus_stack}->push_viewport('Reaction::UI::ViewPort');
+  $c->self->push_viewport('Reaction::UI::ViewPort', %args);
 
   # Access the window title in a template:
   [% window.title %]
@@ -80,12 +80,12 @@ object containing an empty L<Reaction::UI::FocusStack> for your UI
 elements. The stack is also resolved and rendered for you in the
 C<end> action.
 
-At the C<begin> of each request, a L<Reaction::UI::Window> object is
+At the C<begin> of each request, the Window object is
 created using the configured L</view_name>, L</content_type> and
 L</window_title>. These thus should be directly changed on the stashed
 window object at runtime, if needed.
 
-=head1 METHODS
+=head1 ATTRIBUTES
 
 =head2 view_name
 
@@ -120,6 +120,33 @@ by a call to config or in a config file. Defaults to 'text/html'.
 Set or retrieve the title of the page created. Can also be set by a
 call to config or in a config file. No default.
 
+=head1 ACTIONS
+
+=head2 begin
+
+Stuffs a new L<Reaction::UI::Window> object into the stash, using the
+L</view_name> and L</content_type> provided in the
+L<configuration|/SYNOPSIS>.
+
+Make sure you call this base C<begin> action if writing your own.
+
+=head2 end
+
+Draws the UI via the L<Reaction::UI::Window/flush> method.
+
+=head1 METHODS
+
+=head2 error_404
+
+Sets $c->res (the L<Catalyst::Response>) body, status and content type
+to output a 404 (File not found) error.
+
+=head2 error_403
+
+Sets $c->res (the L<Catalyst::Response>) body, status and content type
+to output a 403 (Forbidden) error.
+
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
diff --git a/lib/Reaction/UI/FocusStack.pm b/lib/Reaction/UI/FocusStack.pm
index e582d9f..3d1306e 100644
--- a/lib/Reaction/UI/FocusStack.pm
+++ b/lib/Reaction/UI/FocusStack.pm
@@ -40,6 +40,7 @@ sub push_viewport {
   $self->vp_tail($vp);
   return $vp;
 };
+
 sub pop_viewport {
   my ($self) = @_;
   my $head = $self->vp_head;
@@ -54,11 +55,13 @@ sub pop_viewport {
   $self->vp_count($self->vp_count - 1);
   return $vp;
 };
+
 sub pop_viewports_to {
   my ($self, $vp) = @_;
   1 while ($self->pop_viewport ne $vp);
   return $vp;
 };
+
 sub apply_events {
   my $self = shift;
   my $vp = $self->vp_tail;
diff --git a/lib/Reaction/UI/View.pm b/lib/Reaction/UI/View.pm
index db95e7b..5158429 100644
--- a/lib/Reaction/UI/View.pm
+++ b/lib/Reaction/UI/View.pm
@@ -125,5 +125,104 @@ sub layout_set_args_for {
 
 __PACKAGE__->meta->make_immutable;
 
+=pod
+
+=head1 NAME
+
+Reaction::UI::View - Render the UI.
+
+=head1 SYNOPSIS
+
+  package MyApp::View::TT;
+  use base 'Reaction::UI::View::TT';
+
+  __PACKAGE__->config(
+    skin_name => 'MyApp',
+  );
+
+  ## In the Window class:
+  $res->body($self->view->render_window($self));
+
+=head1 DESCRIPTION
+
+Render the viewports in the current window using the chosen skin and
+layoutset, via the matching widgets.
+
+See also:
+
+=over
+
+=item L<Reaction::UI::Controller::Root>
+=item L<Reaction::UI::ViewPort>
+=item L<Reaction::UI::Window>
+=item L<Reaction::UI::LayoutSet>
+=item L<Reaction::UI::Widget>
+
+=back
+
+=head1 ATTRIBUTES
+
+=head2 app
+
+=over
+
+=item Arguments: $app?
+
+=back
+
+The application L<Catalyst> class. This is set at
+L<Catalyst/COMPONENT> time for you.
+
+=head2 skin_name
+
+=over
+
+=item Arguments: $skinname?
+
+=back
+
+The name of the skin to use to render the pages. This should be the
+name of a subdirectory under the F<share/skin> in your application
+directory. The default skin name is C<default>, the default skin is
+provided with Reaction.
+
+See also: L<Reaction::UI::Skin>
+
+=head2 skin
+
+=over
+
+=item Arguments: $skin?
+
+=back
+
+A L<Reaction::UI::Skin> object based on the L</skin_name>. It will be
+created for you if not provided.
+
+=head2 layout_set_class
+
+The class of the L<Reaction::UI::LayoutSet> used to layout the
+view. Defaults to searching down the precedence tree of the View class
+looking for a class of the same name with C<View> replaced with
+C<LayoutSet>.
+
+=head2 rendering_context_class
+
+The class of the L<Reaction::UI::RenderingContext> used to layout the
+view. Defaults to searching down the precedence tree of the View class
+looking for a class of the same name with C<View> replaced with
+C<RenderingContext>.
+
+=head1 METHODS
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
 
 1;
diff --git a/lib/Reaction/UI/Window.pm b/lib/Reaction/UI/Window.pm
index 637f75c..8257c28 100644
--- a/lib/Reaction/UI/Window.pm
+++ b/lib/Reaction/UI/Window.pm
@@ -116,35 +116,15 @@ L<Reaction::UI::Controller::Root>, it is used to contain all the
 elements (ViewPorts) that make up the UI. The Window is rendered in
 the end action of the Root Controller to make up the page.
 
-To add L<ViewPorts|Reaction::UI::ViewPort> to the stack, read the
-L<Reaction::UI::FocusStack> and L<Reaction::UI::ViewPort> documentation.
+To add L<ViewPorts|Reaction::UI::ViewPort> to the stack, use the
+L<Reaction::UI::Controller/push_viewport> method. For more detailed
+information, read the L<Reaction::UI::FocusStack> and
+L<Reaction::UI::ViewPort> documentation.
 
-Several Window attributes are set by
-L<Reaction::UI::Controller::Root/begin> when a new Window is created,
-these are as follows:
+=head1 ATTRIBUTES
 
-=over
-
-=item ctx
-
-The current L<Catalyst> context object is set.
-
-=item view_name
-
-The view_name is set from the L<Reaction::UI::Controller::Root> attributes.
-
-=item content_type
-
-The content_type is set from the L<Reaction::UI::Controller::Root> attributes.
-
-=item title
-
-The title is set from the L<Reaction::UI::Controller::Root>
-window_title attribute.
-
-=back
-
-=head1 METHODS
+These are set for you by L<Reaction::UI::Controller::Root/begin> from
+your Root controller configuration.
 
 =head2 ctx
 
@@ -154,13 +134,13 @@ window_title attribute.
 
 =back
 
-Retrieve/set the current L<Catalyst> context object.
+The current L<Catalyst> context object.
 
 =head2 view_name
 
 =over
 
-=item Arguments: %viewname?
+=item Arguments: $viewname?
 
 =back
 
@@ -218,40 +198,7 @@ for this Window. Use L<Reaction::UI::FocusStack/push_viewport> on this
 to create more elements. An empty FocusStack is created by the
 Controller::Root when the Window is created.
 
-=head2 render_viewport
-
-=over
-
-=item Arguments: $viewport
-
-=back
-
-  $window->render_viewport($viewport);
-
-  [% window.render_viewport(self.inner) %]
-
-Calls render on the L<view> object used by this Window. The following
-arguments are given:
-
-=over
-
-=item ctx
-
-The L<Catalyst> context object.
-
-=item self
-
-The ViewPort object to be rendered.
-
-=item window
-
-The Window object.
-
-=item type
-
-The string that describes the layout from L<Reaction::UI::ViewPort/layout>.
-
-=back
+=head1 METHODS
 
 =head2 flush
 
@@ -288,9 +235,8 @@ is called by L<flush>.
 
 Renders the page into the L<Catalyst::Response> body, unless the
 response status is already set to 3xx, or the body has already been
-filled. This calls L<render_viewport> with the root
-L<Reaction::UI::ViewPort> from the L<focus_stack>. This method is
-called by L<flush>.
+filled. This is done via L<Reaction::UI::View/render_window>. This
+method is called by L<flush>.
 
 =head1 AUTHORS