widget documentation
phaylon [Mon, 16 Feb 2009 02:40:11 +0000 (02:40 +0000)]
41 files changed:
lib/Reaction/Manual/Tutorial.pod
lib/Reaction/Manual/Widgets.pod [new file with mode: 0644]
lib/Reaction/UI/Widget.pm
lib/Reaction/UI/Widget/Action.pm
lib/Reaction/UI/Widget/Action/Link.pm
lib/Reaction/UI/Widget/Collection.pm
lib/Reaction/UI/Widget/Collection/Grid.pm
lib/Reaction/UI/Widget/Collection/Grid/Member.pm
lib/Reaction/UI/Widget/Collection/Grid/Member/WithActions.pm
lib/Reaction/UI/Widget/Container.pm
lib/Reaction/UI/Widget/Data.pm
lib/Reaction/UI/Widget/Field.pm
lib/Reaction/UI/Widget/Field/Array.pm
lib/Reaction/UI/Widget/Field/Collection.pm
lib/Reaction/UI/Widget/Field/Container.pm
lib/Reaction/UI/Widget/Field/Image.pm
lib/Reaction/UI/Widget/Field/Mutable.pm
lib/Reaction/UI/Widget/Field/Mutable/Boolean.pm
lib/Reaction/UI/Widget/Field/Mutable/ChooseMany.pm
lib/Reaction/UI/Widget/Field/Mutable/ChooseOne.pm
lib/Reaction/UI/Widget/Field/Mutable/DateTime.pm
lib/Reaction/UI/Widget/Field/Mutable/File.pm
lib/Reaction/UI/Widget/Field/Mutable/HiddenArray.pm
lib/Reaction/UI/Widget/Field/Mutable/MatchingPasswords.pm
lib/Reaction/UI/Widget/Field/Mutable/Password.pm
lib/Reaction/UI/Widget/Field/Mutable/String.pm
lib/Reaction/UI/Widget/Field/Mutable/Text.pm
lib/Reaction/UI/Widget/Field/Mutable/TimeRange.pm
lib/Reaction/UI/Widget/Field/String.pm
lib/Reaction/UI/Widget/Field/Text.pm
lib/Reaction/UI/Widget/Image.pm
lib/Reaction/UI/Widget/ListView.pm
lib/Reaction/UI/Widget/Object.pm
lib/Reaction/UI/Widget/Object/Mutable.pm
lib/Reaction/UI/Widget/SiteLayout.pm
lib/Reaction/UI/Widget/URI.pm
lib/Reaction/UI/Widget/Value.pm
lib/Reaction/UI/Widget/Value/Collection.pm
lib/Reaction/UI/Widget/Value/DateTime.pm
lib/Reaction/UI/Widget/Value/Image.pm
lib/Reaction/UI/WidgetClass.pm

index 4dd23d4..1753577 100644 (file)
@@ -427,6 +427,25 @@ Now you can restart your application and visit
 and you have a complete CRUD interface for C<Foo> with listing, viewing, creating, updating
 and deleting capabilities.
 
+=head1 WHERE TO GO NEXT
+
+=over
+
+=item L<Reaction::Manual::Templates>
+
+When a viewport tries to render a layout, it will involve the view to figure out the corresponding
+template (or any other kind of GUI description) and render it. The template documentation is concerned
+mostly with the C<Reaction::UI::View::TT> implementation allowing the developer to use the L<Template>
+engine to render the layouts.
+
+=item L<Reaction::Manual::Widgets>
+
+A widget is the backend Perl object providing the Perl view logic to a layout. What the rendered
+output actually looks like is determined by the layout. The widget is concerned with storing, providing
+and managing data used and rendered by the layout.
+
+=back
+
 =head1 SEE ALSO
 
 =over 
diff --git a/lib/Reaction/Manual/Widgets.pod b/lib/Reaction/Manual/Widgets.pod
new file mode 100644 (file)
index 0000000..14d1fc0
--- /dev/null
@@ -0,0 +1,283 @@
+=head1 NAME
+
+Reaction::Manual::Widgets - Creating and extending Reaction Widgets
+
+=head1 WHAT IS A WIDGET
+
+A widget represents the Perl code used by the layout. Which widget to use
+can be set with the C<=widget> directive. For more on templates, look at
+L<Reaction::Manual::Templates>.
+
+The widget that is used defaults to a name built by the controller class
+and the name of the action. E.g. the action C<MyApp::Controller::Foo-E<gt>bar>
+would assume a widget named C<Foo::Bar> and look for it in the C<widget_search_path>
+defined in the C<share/skin/$skin_name/skin.conf> or the C<share/skin/defaults.conf>.
+
+=head1 A SIMPLE WIDGET
+
+The simplest widget would be this:
+
+  package MyApp::Widget::Foo;
+  use Reaction::UI::WidgetClass;
+
+  use namespace::clean -except => 'meta';
+  
+  __PACKAGE__->meta->make_immutable;
+  
+  1;
+
+The use of L<Reaction::UI::WidgetClass> will import L<strict>, L<warnings>, L<Moose> and
+L<Reaction::Class>. It will also set L<Reaction::UI::Widget> as the base class of the 
+widget. If you want to extend an existing widget rather than create a new one, use 
+L<Moose/extends>.
+
+=head1 FRAGMENTS
+
+Layouts can use the C<=for layout $fragmet> POD syntax to define fragments and use them
+like usual L<Template> variables.
+
+But sometimes it is desirable to have a fragment that invokes Perl code in the widget
+to render certain outputs. For this, the widget has its own mechanisms to handle
+fragments.
+
+=head2 Implementing a fragment
+
+A layout fragment can access the widgets attributes and other fragments like normal 
+L<Template> variables. But if a widget implements a fragment, that implementation will
+be used to provide the data and some additional control over the rendering of the layout.
+
+This abstracts the data manipulation view logic from the layouting view logic.
+
+A widget can a new fragment like this:
+
+  package MyApp::Widget::Foo;
+  use Reaction::UI::WidgetClass;
+  
+  use namespace::clean -except => 'meta';
+  
+  implements fragment now {
+      arg timestamp => time();
+  };
+  
+  __PACKAGE__->meta->make_immutable;
+  
+  1;
+
+Now we can layout the provided data like this:
+
+  =widget Foo
+  
+  =for layout widget
+  
+  <h1>Info:</h1>
+  
+  [% now %]
+  
+  =for layout now
+  
+  <p>Timestamp: [% timestamp %]</p>
+  
+  =cut
+
+The C<widget> fragment is the root fragment of every widget. The widget directive sets
+the desired widget to C<Foo>. One of our C<widget_search_path>s should contain 
+C<MyApp::Widget>, so the widget class defined above can be found.
+
+The C<widget> fragment defined here will render the C<now> fragment implemented by the
+widget and layed out by the layout template. Assuming the current timestamp is
+C<1234567890>, the rendered output will look like this:
+
+  <h1>Info:</h1>
+  
+  <p>Timestamp: 1234567890</p>
+
+Let us take a closer look at the fragment implementation in the widget:
+
+  implements fragment now {
+      arg timestamp => time();
+  };
+
+This syntax might look a bit unusual, but it's not a source filter. The declarative style
+is provided by L<Devel::Declare>. This implements a fragment named C<now> in the current 
+widget. The body uses the C<arg> keyword to provide a new argument C<timestamp> to the 
+template with the value of the current return value of C<time()>.
+
+=head1 Extending a fragment
+
+Sometimes you don't want to redefine how a fragment is implemented, but merely extend on
+the current definition. An example would be adding the total number of entries in a 
+collection below the listing of the entries.
+
+Fortunately, L<Reaction> is based on L<Moose> and trying to stay as flexible as possible.
+In this case, Reaction allows us to use Moose method modifiers with fragments:
+
+  package MyApp::Widget::Bar;
+  use Reaction::UI::WidgetClass;
+  
+  use namespace::clean -except => 'meta';
+  
+  extends 'MyApp::Widget::Foo';
+  
+  around fragment now {
+      call_next;
+      arg timestamp => sprintf '"%s"', $_{timestamp};
+  };
+  
+  __PACKAGE__->meta->make_immutable;
+  
+  1;
+
+The C<call_next> keyword will call the next implementation in the inheritance tree, just
+like it would call the next fragment when used in the layout template.
+
+The global hash C<%_> is used to provide the fragment arguments to the code block
+implementing it. For example, the viewport would be available in C<$_{viewport}>.
+
+Besides C<around>, you can also use C<before> and C<after>.
+
+=head1 Iterating over a fragment
+
+Many fragments are intended to be iterated over a collection of items. An example
+implementation of this is listed below:
+
+  package MyApp::Widget::Baz
+  use Reaction::UI::WidgetClass;
+  
+  use DateTime;
+  
+  use namespace::clean -except => 'meta';
+  
+  my @Fields = qw( year month day hour minute second );
+  
+  implements fragment now {
+      arg dt_obj => DateTime->now;
+      render datetime_field => over [@Fields];
+  };
+  
+  implements fragment datetime_field {
+      arg field_name  => $_;
+      arg field_value => $_{dt_obj}->$_();
+  };
+  
+  __PACKAGE__->meta->make_immutable;
+  
+  1;
+
+Which could have a layout template like this:
+
+  =widget Baz
+  
+  =for layout widget
+  
+  <h1>Now:</h1>
+  
+  [% now %]
+  
+  =for layout now
+  
+  <ul>
+  [% content %]
+  </ul>
+  
+  =for layout datetime_field
+  
+  <li>[% field_name | ucfirst %]: [% field_value %]</li>
+  
+  =cut
+
+The C<widget> fragment defined in the layout template will render the C<now> fragment
+implemented in the widget class. It is setting the C<dt_obj> argument to a L<DateTime>
+object representing the current date and time. Then it will C<render> the fragment
+C<datetime_field> once for every item in the C<@Fields> array.
+
+The global topic variable C<$_> will be set to each corresponding value in the arguments
+to C<over>. The C<datetime_field> fragment will then for each field name set C<field_name>
+to the aforementioned value, and store the result of the method of that name on the C<dt_obj>
+in the C<field_value> argument.
+
+The layout simply formats and puts the components in place.
+
+=head1 WIDGETS PROVIDED BY REACTION
+
+=over
+
+=item L<Reaction::UI::Widget::SiteLayout>
+
+The common wrapper around the fully rendered site.
+
+=item L<Reaction::UI::Widget::ListView>
+
+Extends L<Reaction::UI::Widget::Grid> to provide actions and paging.
+
+=item L<Reaction::UI::Widget::Object>
+
+Rendering of a single object by a collection of viewports.
+
+=item L<Reaction::UI::Widget::Container>
+
+A base class that automatically provides callbacks to render attributes containing
+viewports on the current viewport.
+
+=item L<Reaction::UI::Widget::Collection>
+
+Renders a collection of member viewports in the current viewport.
+
+=item L<Reaction::UI::Widget::Grid>
+
+A subclass of L<Reaction::UI::Widget::Collection> providing header and footer
+as well as member actions. The C<default> skin contains layout sets to output
+this widget as a HTML table.
+
+=item L<Reaction::UI::Widget::Image>
+
+An image with optional width and height properties.
+
+=item L<Reaction::UI::Widget::Field>
+
+Base widget for fields. Contains a list of subclasses.
+
+=item L<Reaction::UI::Widget::Action>
+
+A widget representing a mutation of an object.
+
+=item L<Reaction::UI::Widget::Action::Link>
+
+Object mutation widget rendering a hyperlink.
+
+=item L<Reaction::UI::Widget::Data>
+
+Renders the data stored in the viewport's C<args> attribute.
+
+=item L<Reaction::UI::Widget::Value>
+
+Will take the C<value_string> or C<value> viewport method return value and provide it as 
+argument C<value> to the C<widget> fragment. It also contains a list of subclasses.
+
+=item L<Reaction::UI::Widget::URI>
+
+A hyperlink reference via an URI stored in the viewport.
+
+=back
+
+=head1 SEE ALSO
+
+=over
+
+=item * L<Reaction::UI::WidgetClass>
+
+=item * L<Reaction::UI::Widget>
+
+=item * L<Reaction::Manual::Templates>
+
+=back
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
+
index 07a109f..50085af 100644 (file)
@@ -132,10 +132,76 @@ __PACKAGE__->meta->make_immutable;
 
 =head1 NAME
 
-Reaction::UI::Widget
+Reaction::UI::Widget - The base widget.
 
 =head1 DESCRIPTION
 
+This is the base class for all widgets. It provides common functionality and 
+fragments. It is also concerned with the rendering of the fragments.
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+This is the root fragment for every widget.
+
+=head2 viewport
+
+This fragment is used to render another viewport from inside a fragment. It
+assumes the viewport is stored in the C<_> argument.
+
+=head1 ENVIRONMENT FLAGS
+
+=over
+
+=item REACTION_UI_WIDGET_DEBUG_FRAGMENTS
+
+Log additional debugging output for fragment processing.
+
+=item REACTION_UI_WIDGET_DEBUUG_LAYOUTS
+
+Log additional debugging output for layout processing.
+
+=back
+
+=head1 ATTRIBUTES
+
+=head2 view
+
+The widget's view object. Is required, readonly and must be a L<Reaction::UI::View>.
+
+=head2 layout_set
+
+The widget's layout set. Is required, readonly and must be a L<Reaction::UI::LayoutSet>.
+
+=head2 fragment_names
+
+List of names of known fragments for the current widget. Lazily computed from all 
+methods that are named in the pattern C<_fragment_$name>.
+
+=head2 basic_layout_args
+
+A lazily built hash reference containing the rendered fragments defined in both the widget and
+the layout set, keyed by the fragments' names.
+
+=head
+
+=head1 METHODS
+
+=head2 render
+
+  $widget->render('fragment_name', $reaction_ctx, \%passed_args);
+
+This method is concerned with rendering a fragment.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::Manual::Widgets>
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index 9c94174..0994e6e 100644 (file)
@@ -58,14 +58,172 @@ Reaction::UI::Widget::Action
 
 =head1 DESCRIPTION
 
+This is a subclass of L<Reaction::UI::Widget::Object::Mutable>.
+
 =head1 FRAGMENTS
 
+=head2 widget
+
+Additionally provides the C<method> argument containing the value of
+the viewport's C<method>.
+
+=head2 message
+
+Empty if the viewport's C<has_message> returns false. Otherwise sets
+the C<message_string> argument to the viewport's C<message> and
+renders the C<message_layout> fragment.
+
+=head2 error_message
+
+Same as the C<message> fragment above except that it checks 
+C<has_error_message>, sets C<message_string> to the viewport's
+C<error_message> and renders C<error_message_layout>.
+
 =head2 ok_button_fragment
 
+Renders nothing unless the viewport accepts the C<ok> event.
+
+If it does, it provides the following arguments before rendering C<ok_button>:
+
+=over 4
+
+=item event_id
+
+Is set to the event id C<ok>.
+
+=item label
+
+Is set to the localized C<ok_label> of the viewport.
+
+=back
+
 =head2 apply_button_fragment
 
+Renders nothing unless the viewport accepts the C<apply> event.
+
+If it does, it provides the following arguments before rendering C<apply_button>:
+
+=over 4
+
+=item event_id
+
+Is set to the event id C<apply>.
+
+=item label
+
+Is set to the localized C<apply_label> of the viewport.
+
+=back
+
 =head2 cancel_button_fragment
 
+Renders nothing unless the viewport accepts the C<close> event.
+
+If it does, it provides the following arguments before rendering C<cancel_button>:
+
+=over 4
+
+=item event_id
+
+Is set to the event id C<close>.
+
+=item label
+
+Is set to the localized C<close_label> of the viewport.
+
+=back
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/action.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders a C<div> element containing a C<form>. The C<form> element contains the rendered
+C<header>, C<container_list>, C<buttons> and C<footer> fragments.
+
+=item header
+
+Renders the error message.
+
+=item container_list
+
+Simply renders the parent C<container_list>.
+
+=item container
+
+Simply renders the parent C<container>.
+
+=item buttons
+
+First renders the C<message> fragment, then the C<ok_button_fragment>, the C<apply_button_fragment>
+and the C<cancel_button_fragment>.
+
+=item message_layout
+
+Renders the C<message_string> argument in a C<span> element with an C<action_message> class.
+
+=item error_message_layout
+
+Renders the C<message_string> argument in a C<span> element with an C<action_error_message> class.
+
+=item standard_button
+
+Renders a submit button in a C<span> with the C<name> set to the C<event_id> argument, and the
+value set to the C<label> argument.
+
+=item ok_button
+
+Renders the C<standard_button> fragment.
+
+=item apply_button
+
+Renders the C<standard_button> fragment.
+
+=item cancel_button
+
+Renders the C<standard_button> fragment.
+
+=item footer
+
+Empty by default.
+
+=back
+
+=head2 default
+
+  share/skin/base/layout/action.tt
+
+Extends the layout set of the same name in the parent skin.
+
+The following layouts are provided:
+
+=over 4
+
+=item container
+
+Adds a C<br> element after the original C<container> fragment.
+
+=item message_layout
+
+Adds a C<br> element after the original C<message_layout> fragment.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<Reaction::UI::Widget::Object::Mutable>
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index 1063ed0..0c40670 100644 (file)
@@ -18,3 +18,78 @@ __PACKAGE__->meta->make_immutable;
 
 __END__;
 
+=head1 NAME
+
+Reaction::UI::Widget::Action::Link - A hyperlink representing an object mutation
+
+=head1 DESCRIPTION
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+The following additional arguments are provided:
+
+=over 4
+
+=item uri
+
+The viewport's C<uri>.
+
+=item label
+
+The localised value of the viewport's C<label>.
+
+=back
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/action/link.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders a hyperlink with a C<href> attribute set to the C<uri> argument and
+the content set to the C<label> argument.
+
+=back
+
+=head2 default
+
+  share/skin/default/layout/action/link.tt
+
+This layout set extends the C<NEXT> layout set with the same name in the parent
+skin.
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders a C<br> element after the original C<widget> fragment.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::UI::Widget::Action>
+
+=back
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
index e679740..e991c4c 100644 (file)
@@ -22,12 +22,50 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Collection
+Reaction::UI::Widget::Collection - Render the current viewport's member viewports
 
 =head1 DESCRIPTION
 
+This widget will allow you to render the viewports stored in the current viewports
+C<members> attribute.
+
 =head1 FRAGMENTS
 
+=head2 members
+
+Renders the C<member> fragment for every entry in the viewports C<members> attribute.
+
+=head2 member
+
+Renders the C<viewport> fragment, which will in turn render the C<_> argument. That
+will be one of the viewports in the current viewport's C<members> attribute when
+called from C<members>.
+
+=head1 LAYOUT SETS
+
+  share/skin/base/layout/collection.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders a C<div> element with a class attribute of C<collection_members> and the
+C<members> fragment as the content.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::UI::Widget::Collection::Grid>
+
+=item * L<Reaction::UI::ViewPort::Collection>
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index 823afc6..2856793 100644 (file)
@@ -29,12 +29,130 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Grid
+Reaction::UI::Widget::Grid - A collection with header and footer
 
 =head1 DESCRIPTION
 
+This widget is a subclass of L<Reaction::UI::Widget::Collection>. Additionally
+to its superclass, it provides abstract means of a header and a footer.
+
 =head1 FRAGMENTS
 
+=head2 header_cells
+
+Will set the C<labels> argument to the viewport's C<field_labels> attribute
+value.
+
+Afterwards, the C<header_cell> fragment will be rendered once for every entry
+in the viewport's C<computed_field_order>.
+
+Additionally, the C<header_action_cell> will be rendered when the current
+viewport's C<member_action_count> is larger than 0.
+
+=head2 header_cell
+
+Populates the C<label> argument with a localised value of the C<labels>
+hash reference argument. The used key is extracted from the C<_> topic
+argument.
+
+=head2 header_action_cell
+
+Populates the C<col_count> argument with the viewports C<member_action_count>
+attribute value.
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/collection/grid.tt
+
+The base grid layout set does not provide an markup, just abstract layouting.
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders, in sequence, the C<header>, C<body> and C<footer> fragments.
+
+=item header
+
+Renders the C<header_row> fragment.
+
+=item header_row
+
+Renders the C<header_cells> fragment.
+
+=item header_cell
+
+Renders the C<header_cell_contents> fragment.
+
+=item header_cell_contents
+
+Renders the value of the C<label> argument.
+
+=item header_action_cell
+
+Renders the string C<Actions>.
+
+=item body
+
+Renders the C<members> fragment implemented in L<Reaction::UI::Widget::Collection>.
+
+=back
+
+=head2 default
+
+  share/skin/default/layout/collection/grid.tt
+
+This layout set extends the C<NEXT> in the skin inheritance hierarchy.
+
+It is meant to extend upon the layout set with the same name in the C<base> skin and
+provides the same abstract structure but with a table based markup.
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders the next skin's C<widget> fragment surrounded by a C<table> element with the
+class attribute C<grid>.
+
+=item header
+
+Renders the next skin's C<header> fragment surrounded by a C<thead> element.
+
+=item header_row
+
+Wrap's the next skin's C<header_row> fragment in a C<tr> element.
+
+=item header_cell
+
+Wrap's the next skin's C<header_cell> fragment in a C<th> element.
+
+=item header_action_cell
+
+Wrap's the next skin's C<header_action_cell> fragment in a C<th> element with a C<colspan>
+attribute set to the number of actions found in the C<col_count> attribute
+
+=item body
+
+Wrap's the next skin's C<body> fragment in a C<tbody> element.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::UI::Widget::Collection>
+
+=item * L<Reaction::UI::Widget::Collection::Grid::Member>
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index 19c355a..24168a6 100644 (file)
@@ -13,12 +13,70 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Collection::Grid::Member
+Reaction::UI::Widget::Collection::Grid::Member - A member widget of the Grid widget
 
 =head1 DESCRIPTION
 
+A pure subclass of L<Reaction::UI::Widget::Object> representing a member
+in a L<Reaction::UI::Widget::Collection::Grid>.
+
 =head1 FRAGMENTS
 
+This widget defines no additional fragments.
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/collection/grid/member.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders the C<field_list> fragment provided initially by L<Reaction::UI::Widget::Object>.
+
+=item field
+
+Renders the next C<field> fragment in the inheritance hierarchy.
+
+=back
+
+=head2 default
+
+  share/skin/default/layout/collection/grid/member.tt
+
+This layout set extends the C<NEXT> skin in the inheritance hierarchy.
+
+Like with L<Reaction::UI::Widget::Collection::Grid>, the C<default> layout set provides
+a table based markup for the abstract view logic defined in the C<base> skin.
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders the next C<widget> fragment surrounded by a C<tr> element.
+
+=item field
+
+Renders the next C<field> fragment surrounded by a C<td> element.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::UI::Widget::Collection::Grid>
+
+=item * L<Reaction::UI::Widget::Collection::Grid::Member::WithActions>
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index 156f216..f3b4454 100644 (file)
@@ -21,12 +21,79 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Grid::Member::WithActions
+Reaction::UI::Widget::Grid::Member::WithActions - Grid members with actions
 
 =head1 DESCRIPTION
 
+This is a subclass of L<Reaction::UI::Widget::Grid::Member> additionally
+providing actions per member.
+
 =head1 FRAGMENTS
 
+=head2 actions
+
+Renders the C<action> fragment with every item in the viewports C<actions>.
+
+=head2 action
+
+Renders the C<viewport> fragment provided by L<Reaction::UI::Widget>, thus
+rendering the current viewport stored in the C<_> topic argument provided
+by the C<actions> fragment.
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/collection/grid/member/with_actions.tt
+
+This layout set extends the C<collection/grid/member> layout set in the parent
+skin.
+
+The following layouts are provided:
+
+=over 4
+
+=item field_list
+
+First renders the original C<field_list> fragment, then the C<actions> fragment.
+
+=item action
+
+Simply renders the next C<action> fragment in line.
+
+=back
+
+=head2 default
+
+  share/skin/default/layout/collection/grid/member/with_actions.tt
+
+This layout skin extends the C<collection/grid/member> layout set in the parent
+skin.
+
+The following layouts are provided:
+
+=over 4
+
+=item field_list
+
+The same as in the C<base> skin.
+
+=item action
+
+Renders the original C<action> fragment surrounded by a C<td> element.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::UI::Widget::Grid::Member>
+
+=item * L<Reaction::UI::Widget::Grid>
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index 11ac72f..f470d51 100644 (file)
@@ -57,5 +57,35 @@ implements _contained_names => sub {
 
 __PACKAGE__->meta->make_immutable;
 
-
 1;
+
+__END__
+
+=head1 NAME
+
+Reaction::UI::Widget::Container - Provide viewport attibutes in the current viewport
+
+=head1 DESCRIPTION
+
+This widget base class (with no corresponding layout set) will search the viewports
+attributes for those that contain L<Reaction::UI::ViewPort> classes or subclasses.
+
+These attributes will then be provided as arguments to the C<widget> fragment and
+can be rendered by their attribute name.
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+Provides rendering callbacks to those attributes of the viewport that can contain
+viewport objects as arguments to the C<widget> layout.
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
index 95da53c..39f3348 100644 (file)
@@ -11,3 +11,47 @@ before fragment widget {
 };
 
 1;
+
+__END__
+
+=head1 NAME
+
+Reaction::UI::Widget::Data - Abstract class to render a data hash reference
+
+=head1 DESCRIPTION
+
+This takes the C<args> method return value of the viewport and populates the
+arguments with names and values from that value.
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+Sets an argument for every key and value in the viewport's C<args> method return
+value (which is expected to be a hash reference).
+
+=head1 EXAMPLE LAYOUT
+
+Assuming this hash reference:
+
+  { first_name => "Foo", last_name => "Bar" }
+
+we can access it in a layout set like this:
+
+  =widget Data
+  
+  =for layout widget
+  
+  Hello [% last_name | html %], [% first_name | html %]!
+  
+  =cut
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
index 0a7e140..7e5fcd3 100644 (file)
@@ -22,36 +22,122 @@ implements fragment label_fragment {
 
 __PACKAGE__->meta->make_immutable;
 
-
 1;
 
 __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field
+Reaction::UI::Widget::Field - A simple labelled text field
 
 =head1 DESCRIPTION
 
+This widget renders a simple labelled text field.
+
 =head1 FRAGMENTS
 
 =head2 widget
 
-Additional variables available in topic hash: "viewport", "id", "name".
+Sets the C<field_value> argument either to the result of the C<value_string>
+method on the viewport, or to an empty string if the viewport does not support
+the method.
+
+=head2 label_fragment
+
+Will set the C<label> argument to the localised value of the viewport's C<label>
+method and render the C<label> fragment I<if> the viewport's C<label> value
+is true.
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/field.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders the C<label_fragment> and C<value_layout> fragments.
+
+=item label
+
+Renders a C<span> element with a C<field_label> class attribute containing the
+C<label> argument and a double colon.
+
+=item value_layout
+
+Renders a C<span> element with a C<field_value> class attribute containing the
+C<field_value> argument.
+
+=back
+
+=head2 default
+
+  share/skin/default/layout/field.tt
+
+This layout set inherits from the C<NEXT> one in the skin inheritance.
+
+The following layouts are provided:
+
+=item label
+
+The same as in the C<base> skin except that the C<label> argument is surrounded
+by a C<strong> element.
+
+=head1 SUBCLASSES
+
+For mutable fields see L<Reaction::UI::Widget::Field::Mutable>.
+
+=over 4
+
+=item L<Reaction::UI::Field::Text>
+
+A simple text subclass of L<Reaction::UI::Field>.
+
+=item L<Reaction::UI::Field::String>
+
+A simple string subclass of L<Reaction::UI::Field>.
+
+=item L<Reaction::UI::Field::RelatedObject>
+
+A simple subclass of L<Reaction::UI::Field>.
+
+=item L<Reaction::UI::Field::Number>
+
+A simple number subclass of L<Reaction::UI::Field>.
+
+=item L<Reaction::UI::Field::Integer>
+
+A simple integer subclass of L<Reaction::UI::Field>.
+
+=item L<Reaction::UI::Field::Image>
+
+A field representing an optional image.
+
+=item L<Reaction::UI::Field::DateTime>
+
+A simple DateTime subclass of L<Reaction::UI::Field>.
+
+=item L<Reaction::UI::Field::Container>
+
+A container field for multiple values.
 
-Renders "label","field" and "message"
+=item L<Reaction::UI::Field::Collection>
 
-=head2 field
+A field containing a collection of localised values.
 
- C<content> will contain the value, if any,  of the field.
+=item L<Reaction::UI::Field::Boolean>
 
-=head2 label
+A simple boolean subclass of L<Reaction::UI::Field>.
 
- C<content> will contain the label, if any, of the field.
+=item L<Reaction::UI::Field::Array>
 
-=head2 message
+A field representing an array of values, like L<Reaction::UI::Field::Collection>.
 
- C<content> will contain the message, if any, of the field.
+=back
 
 =head1 AUTHORS
 
index fc1bf33..f80bf67 100644 (file)
@@ -26,10 +26,12 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::DisplayField::Array
+Reaction::UI::Widget::Field::Array - A field representing an array of localised items
 
 =head1 DESCRIPTION
 
+See L<Reaction::UI::Widget::Field::Collection>, of which this widget is not a subclass.
+
 =head1 FRAGMENTS
 
 =head2 widget
index 6f59532..c54f8a6 100644 (file)
@@ -27,10 +27,13 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::Collection
+Reaction::UI::Widget::Field::Collection - A field representing a collection
 
 =head1 DESCRIPTION
 
+This field class will render a collection of values found in the viewport's
+C<value_names> and localised before passed to the layout.
+
 =head1 FRAGMENTS
 
 =head2 widget
@@ -49,6 +52,51 @@ renders fragment item over the viewport's C<value_names>
 
 C<content> contains the value of the current item ($_ / $_{_})
 
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/field/collection.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders the C<label_box> and C<list> fragments.
+
+=item label_box
+
+Renders a C<span> element containing the C<label> argument.
+
+=item list
+
+Renders the C<item>s inside a C<div> and C<ul> element.
+
+=item item
+
+Renders the C<name> argument inside a C<li> element.
+
+=back
+
+=head2 default
+
+  share/skin/default/layout/field/collection.tt
+
+This layout set extends the C<NEXT> one in the parent skin.
+
+The following layouts are provided:
+
+=over 4
+
+=item label_box
+
+The same as in the C<base> skin, except the label is surrounded by
+a C<strong> element.
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index ba7fa28..e95f1f7 100644 (file)
@@ -30,12 +30,24 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::Container
+Reaction::UI::Widget::Field::Container - A field containing multiple values
 
 =head1 DESCRIPTION
 
+This widget implements a field containing multiple value viewports found in
+the current viewport's C<fields> attribute.
+
 =head1 FRAGMENTS
 
+=head2 widget
+
+Sets the C<name> argument to the viewport's C<name> attribute.
+
+=head2 maybe_label
+
+Sets the C<label> argument to the viewport's C<label> attribute value and
+renders the C<label> fragment when the viewport has a label defined.
+
 =head2 field_list
 
 Sequentially renders the C<fields> of the viewport;
@@ -44,6 +56,31 @@ Sequentially renders the C<fields> of the viewport;
 
 Renders the C<field> viewport passed by C<field_list>
 
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/field/container.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders a C<fieldset> element containing the C<maybe_label> and C<field_list>
+fragments.
+
+=item label
+
+Renders a C<legend> element for the C<fieldset> containing the C<label> argument.
+
+=item field
+
+Wraps the next C<field> fragment in a C<span> element.
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index 839545e..b2a379a 100644 (file)
@@ -18,5 +18,44 @@ implements fragment image {
 
 __PACKAGE__->meta->make_immutable;
 
-
 1;
+
+__END__
+
+=head1 NAME
+
+Reaction::UI::Widget::Field::Image - An image field
+
+=head1 DESCRIPTION
+
+This L<Reaction::UI::Widget::Field> widget represents an image.
+
+=head1 FRAGMENTS
+
+=head2 image
+
+If the viewport's C<value_string> is true, it will render the C<has_image>
+fragment after setting the C<uri> argument to the value of the viewport's
+C<uri>.
+
+If the C<value_string> is false the C<no_image> fragment will be rendered.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::UI::Widget::Field>
+
+=item * L<Reaction::UI::Widget::Value::Image>
+
+=back
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
index 73b14e3..9fc565e 100644 (file)
@@ -46,3 +46,191 @@ __PACKAGE__->meta->make_immutable;
 1;
 
 __END__;
+
+=head1 NAME
+
+Reaction::UI::Widget::Field::Mutable - Mutable fields
+
+=head1 DESCRIPTION
+
+An extension of L<Reaction::UI::Widget::Field> representing fields
+whose values can be mutated.
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+The following additional arguments are provided:
+
+=over 4
+
+=item field_id
+
+Contains the viewport's event id for C<value_string>.
+
+=item field_name
+
+Defaults to the C<field_id> argument unless already defined
+
+=item field_type
+
+Defaults to C<text>.
+
+=item field_class
+
+A string containing the joined class attribute. Defaults to
+C<action-field> and the current viewport's C<name>.
+
+=item exists_event
+
+Contains the event id for C<exists>.
+
+=item exists_value
+
+Defaults to C<1>.
+
+=back
+
+=head2 message_fragment
+
+Renders nothing if the viewport doesn't have a message.
+
+Otherwise, the C<message> argument will be set to the localised string contained
+in the viewport's C<message> attribute and the C<message> fragment will be rendered.
+
+=head2 field_is_required
+
+Will render either C<field_is_required_yes> or C<field_is_required_no> depending on
+if C<value_is_required> on the viewport returns true and the viewports C<value_string>
+is empty.
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/field/mutable.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Builds a C<span> element with a class attribute set to the C<field_class> argument.
+The element contents will be the C<label_fragment>, C<field> and C<message_fragment>
+fragments.
+
+=item label
+
+Builds a C<label> element with the C<for> attribute set to the value of C<field_id> and
+the other attributes used from the C<field_is_required> argument. The content will be
+the C<label> argument.
+
+=item field_is_required_yes
+
+Sets the class attribute to C<required_field>.
+
+=item field_is_required_no
+
+Empty.
+
+=item message
+
+Renders a C<span> element with the C<message> as content.
+
+=item field
+
+Renders the input field. The C<field_body> fragment is used to set the value.
+
+=item field_body
+
+Creates the C<value> attribute for the input element.
+
+=back
+
+=head2 default
+
+  share/skin/default/layout/field/mutable.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item message
+
+Will render the original C<message> fragment followed by a C<br> element.
+
+=back
+
+=head1 SUBCLASSES
+
+=over 4
+
+=item L<Reaction::UI::Widget::Field::Mutable::Boolean>
+
+A widget allowing the manipulation of boolean values.
+
+=item L<Reaction::UI::Widget::Field::Mutable::ChooseMany>
+
+Allows the user to choose many items from a list of available values.
+
+=item L<Reaction::UI::Widget::Field::Mutable::ChooseOne>
+
+Allows the user to choose a single item from a list of available values.
+
+=item L<Reaction::UI::Widget::Field::Mutable::DateTime>
+
+A simple DateTime L<Reaction::UI::Widget::Field::Mutable> subclass.
+
+=item L<Reaction::UI::Widget::Field::Mutable::File>
+
+A simple file input field.
+
+=item L<Reaction::UI::Widget::Field::Mutable::HiddenArray>
+
+Renders an array reference value as a series of hidden fields.
+
+=item L<Reaction::UI::Widget::Field::Mutable::Integer>
+
+A simple integer L<Reaction::UI::Widget::Field::Mutable>.
+
+=item L<Reaction::UI::Widget::Field::Mutable::MatchingPasswords>
+
+Password input requiring that the password be entered twice, e.g. to input a new
+password.
+
+=item L<Reaction::UI::Widget::Field::Mutable::Password>
+
+A password input L<Reaction::UI::Widget::Field::Mutable>.
+
+=item L<Reaction::UI::Widget::Field::Mutable::Number>
+
+A simple number L<Reaction::UI::Widget::Field::Mutable> input field.
+
+=item L<Reaction::UI::Widget::Field::Mutable::String>
+
+A simple string L<Reaction::UI::Widget::Field::Mutable> input field.
+
+=item L<Reaction::UI::Widget::Field::Mutable::Text>
+
+A multiline input L<Reaction::UI::Widget::Field::Mutable>.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::UI::Widget::Field>
+
+=back
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
index 97c1803..4b17058 100644 (file)
@@ -28,11 +28,53 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::Boolean
+Reaction::UI::Widget::Field::Boolean - A mutable boolean field
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::Field>
+Provides a widget to manipulate a boolean value. This is a subclass of
+L<Reaction::UI::Widget::Field::Mutable>.
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+Will set the argument C<field_type> to C<checkbox>.
+
+=head2 is_checked
+
+Will render the C<is_checked_yes> fragment if the viewport has a true C<value_string>
+or C<is_checked_no> if it does not.
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/field/mutable/boolean.tt
+
+This layout set extends the next C<field/mutable> layout set in the skin inheritance.
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders the input element that will be the checkbox.
+
+=item field_body
+
+Sets the value element attribute to 1 and renders the C<is_checked> fragment afterwards.
+
+=item is_checked_yes
+
+Sets the C<checked> attribute of the input element to C<checked>.
+
+=item is_checked_no
+
+Empty.
+
+=back
 
 =head1 AUTHORS
 
index bb80615..62f6747 100644 (file)
@@ -55,39 +55,71 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::ChooseMany
+Reaction::UI::Widget::Field::ChooseMany - Choose a number of items
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::Field>
+See L<Reaction::UI::Widget::Field::Mutable>
 
 This needs a refactor to not be tied to a dual select box, but ENOTIME
 
 =head1 FRAGMENTS
 
-=head2 field
+=head2 action_buttons
 
-renders C<available_values>, C<action_buttons>, C<selected_values> and C<current_values>
+Sets the following events by the name C<event_id_$name> as arguments with their viewport 
+event ids as values:
+
+  add_all_values
+  do_add_values
+  do_remove_values
+  remove_all_values
+
+=head2 current_values
+
+Renders the C<hidden_value> fragment to store the currently selected values either once
+for every item in the viewport's C<current_value_choices> (with the C<field_name> argument
+set to the viewport's event id for C<value>. Or, if no current values exist, uses the 
+C<no_current_value> event id from the viewport and sets the topic argument C<_> to 1.
+
+=head2 selected_values
+
+Sets C<event_id_remove_values> to the viewport's event id for C<remove_values> and renders
+the C<value_option> fragment over the viewport's C<current_value_choices>.
 
-=head2 current values
+=head2 available_values
 
-renders the viewport's current_value_choices over hidden_value
+Sets C<event_id_add_values> to the viewport's event id for C<add_values> and renders
+the C<value_option> fragment over the viewport's C<available_value_choices>.
+
+=head2 value_option
+
+Sets the C<option_name> argument to the current topic argument's C<name> key and the
+C<option_value> to the current topic argument's C<value> key.
 
 =head2 hidden_value
 
-C<content> is the value of the current choice
+Sets C<hidden_value> to the current topic's C<value> key.
+
+=head2 field
+
+renders C<available_values>, C<action_buttons>, C<selected_values> and C<current_values>
+
+=head1 LAYOUT SETS
 
-=head2 available_value
+=head2 base
 
-rendersthe viewport's current_available_value_choices over the option fragment
+  share/skin/base/layout/field/mutable/choose_many.tt
 
-=head2 selected_value
+This layout set provides a table containing two lists separated by action buttons that
+allow the user to add values from the available list to the selected list.
 
-rendersthe viewport's current_selected_value_choices over the option fragment
+=head2 default
 
-=head2 option
+  share/skin/default/layout/field/mutable/choose_many.tt
 
-C<content> is a dummy value but C<v_value> and C<v_name> are both set.
+Same as in the C<base> skin, except that after each action button a C<br> element will
+be rendered.
 
 =head1 AUTHORS
 
index 98b9b7d..b8ac8aa 100644 (file)
@@ -41,11 +41,12 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::ChooseOne
+Reaction::UI::Widget::Field::ChooseOne - Choose one from a list of available values
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::Field>
+See L<Reaction::UI::Widget::Field::Mutable>. This widget provides the user with a 
+field where he can select a single value from a list of many.
 
 =head1 FRAGMENTS
 
@@ -60,6 +61,30 @@ Additional varibles set: C<is_required> - Boolean, self-explanatory
 C<content> is a dummy variable, but th additional variables C<v_value>, C<v_name>
 and C<is_selected> are set
 
+=head2 option_is_required
+
+Renders either C<option_is_required_yes> or C<option_is_required_no> depending on
+the viewport's C<value_is_required> attribute.
+
+=head2 option_list
+
+Renders the C<option> fragment over the viewport's C<value_choices>. This populates
+the list of available values.
+
+=head2 option_is_selected
+
+Renders either C<option_is_selected_yes> or C<option_is_selected_no> depending on
+if the viewport's C<is_current_value> method returns true on the current topic
+arguments C<value> key.
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/field/mutable/choose_one.tt
+
+This layout set renders a C<select> element with the available values as C<option>s.
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index ab626fa..ac5973d 100644 (file)
@@ -24,13 +24,17 @@ Reaction::UI::Widget::Field::DateTime
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::Field>
+See L<Reaction::UI::Widget::Field::Mutable.>
 
 =head1 FRAGMENTS
 
+=head2 widget
+
+Sets C<field_name> to the C<value_string> event id of the viewport.
+
 =head2 field
 
-C<content> contains viewport's C<value_string>
+C<content> contains viewport's C<value_string>.
 
 =head1 AUTHORS
 
index b8d399f..7578e30 100644 (file)
@@ -20,11 +20,17 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::File
+Reaction::UI::Widget::Field::File - A file input field
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::Field>
+See L<Reaction::UI::Widget::Field::Mutable>
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+The C<field_type> argument will be set to C<file>.
 
 =head1 AUTHORS
 
index 0cecc5e..0b8cce7 100644 (file)
@@ -29,10 +29,20 @@ Reaction::UI::Widget::Field::Mutable::HiddenArray
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::Field>
+See L<Reaction::UI::Widget::Field::Mutable>. This renders a list of values
+as a series of hidden fields to transport them across forms.
 
 =head1 FRAGMENTS
 
+=head2 hidden_list
+
+Renders C<hidden_field> over the array reference stored in the viewpoint's
+C<value>.
+
+=head2 hidden_field
+
+Sets the C<field_value> argument to the current topic argument C<_>.
+
 =head2 field
 
 renders fragment C<item> over the values of 'value' arrayref
@@ -41,6 +51,14 @@ renders fragment C<item> over the values of 'value' arrayref
 
 C<content> is $_{_} / $_ (current item in the 'value' array)
 
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/field/mutable/hidden_array.tt
+
+Provides a C<hidden_field> layout that renders a hidden input element.
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index 5668510..544b11a 100644 (file)
@@ -23,3 +23,51 @@ __PACKAGE__->meta->make_immutable;
 1;
 
 __END__;
+
+=head1 NAME
+
+Reaction::UI::Widget::Field::Mutable::MatchingPasswords - Require double input of password
+
+=head1 DESCRIPTION
+
+This is a subclass of L<Reaction::UI::Widget::Field::Mutable::Password> implementing
+a second field to repeat the password input.
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+Will render the C<check_field> fragment after the original C<widget> fragment.
+
+=head2 check_field
+
+Renders C<field> with C<field_id> and C<field_name> set to the viewport's C<check_value> event.
+
+=head2 check_label
+
+Localises the C<label> argument with a value from the viewport's C<check_label> attribute if
+one is specified and renders the C<label> fragment.
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/field/mutable/matching_passwords.tt
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::UI::Widget::Field::Mutable::Password>
+
+=back
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
index e83b564..1b19057 100644 (file)
@@ -22,11 +22,18 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::Password
+Reaction::UI::Widget::Field::Password - A password input field
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::Field>
+See L<Reaction::UI::Widget::Field::Mutable>. Creates a password type input field
+and never sets the current value as the field's value.
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+Sets C<field_type> to C<password> and C<field_value> to an empty string.
 
 =head1 AUTHORS
 
index f93a087..32b8e1f 100644 (file)
@@ -16,11 +16,11 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::String
+Reaction::UI::Widget::Field::String - Simple string input field
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::Field>
+See L<Reaction::UI::Widget::Field::Mutable>
 
 =head1 AUTHORS
 
index d902f18..d2dab85 100644 (file)
@@ -16,11 +16,20 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::Text
+Reaction::UI::Widget::Field::Text - A multiline text input field
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::Field>
+See L<Reaction::UI::Widget::Field::Mutable>
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/field/mutable/text.tt
+
+This layout set renders a C<textarea> element to allow the input
+of multiline texts.
 
 =head1 AUTHORS
 
index aad4895..3ccb1d0 100644 (file)
@@ -16,7 +16,7 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::TimeRange
+Reaction::UI::Widget::Field::TimeRange - Input a time range
 
 =head1 DESCRIPTION
 
index 3a4a4ae..0515bbd 100644 (file)
@@ -16,11 +16,11 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::DisplayField::String
+Reaction::UI::Widget::Field::String - A simple string field
 
 =head1 DESCRIPTION
 
-See L<Reaction::UI::Widget::DisplayField>
+See L<Reaction::UI::Widget::Field>
 
 =head1 AUTHORS
 
index 293c6da..16f8cd5 100644 (file)
@@ -16,7 +16,7 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Field::Text
+Reaction::UI::Widget::Field::Text - A text field
 
 =head1 DESCRIPTION
 
index 18eb310..705859d 100644 (file)
@@ -18,3 +18,46 @@ __PACKAGE__->meta->make_immutable;
 1;
 
 __END__;
+
+=head1 NAME
+
+Reaction::UI::Widget::Image - An image with optional height and width properties
+
+=head1 DESCRIPTION
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+The widget layout will be provided with an additional C<img_attrs> argument containing
+a rendered string of the image's attributes containing:
+
+=over 4
+
+=item src
+
+The return value of the viewports C<uri> method.
+
+=item width
+
+The value of the viewports C<width> attribute if one was found.
+
+=item height
+
+The value of the viewports C<height> attribute if one was found.
+
+=back
+
+=head1 LAYOUT SETS
+
+  share/skin/base/layout/image.tt
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
index 966493a..1db21ba 100644 (file)
@@ -89,11 +89,12 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::ListView
+Reaction::UI::Widget::ListView - Extends Grid to a full list interface
 
 =head1 DESCRIPTION
 
-This class is a subclass of L<Reaction::UI::ViewPort::Collection::Grid>
+This class is a subclass of L<Reaction::UI::ViewPort::Collection::Grid>. It additionally
+provides means of paging and actions.
 
 =head1 FRAGMENTS
 
index a44a66d..de83e25 100644 (file)
@@ -29,7 +29,7 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Object
+Reaction::UI::Widget::Object - Widget to implement rendering of an object
 
 =head1 DESCRIPTION
 
@@ -37,11 +37,12 @@ Reaction::UI::Widget::Object
 
 =head2 container_list
 
-Sequentially renders the C<fields> of the viewport;
+Sequentially renders the C<fields> of the viewport found in its C<containers>
+method return values.
 
 =head2 container
 
-Renders the C<field> viewport passed by C<field_list>
+Renders the C<field> viewport passed by C<container_list>.
 
 =head1 DEPRECATED FRAGMENTS
 
@@ -53,6 +54,42 @@ Sequentially renders the C<fields> of the viewport;
 
 Renders the C<field> viewport passed by C<field_list>
 
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/object.tt
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+Renders the C<container_list> fragment.
+
+=item container
+
+Renders the container viewport.
+
+=back
+
+=head2 default
+
+  share/skin/default/layout/object.tt
+
+This layout set inherits from the one with the same name in the C<base> skin.
+
+The following layouts are provided:
+
+=over 4
+
+=item container
+
+Renders the container viewport.
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index 563c72b..8f391a5 100644 (file)
@@ -13,12 +13,26 @@ __END__;
 
 =head1 NAME
 
-Reaction::UI::Widget::Object::Mutable
+Reaction::UI::Widget::Object::Mutable - A widget base representing mutable objects
 
 =head1 DESCRIPTION
 
+This is an empty subclass of L<Reaction::UI::Widget::Object>.
+
 =head1 FRAGMENTS
 
+No fragments were implemented in this widget.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Reaction::UI::Widget::Object>
+
+=item * L<Reaction::UI::Widget::Action>
+
+=back
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.
index d37003f..a02df37 100644 (file)
@@ -34,5 +34,164 @@ implements fragment meta_member {
 
 __PACKAGE__->meta->make_immutable;
 
-
 1;
+
+__END__
+
+=head1 NAME
+
+Reaction::UI::Widget::SiteLayout - The layout of the site as a whole
+
+=head1 DESCRIPTION
+
+This is a subclass of L<Reaction::UI::Widget::Container>. It is generally
+used as the widget surrounding the site's content.
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+Additionally provides these arguments after the parent widget fragment
+has been rendered:
+
+=over 4
+
+=item static_base
+
+The C<static_base_uri> of the viewport.
+
+=item title
+
+The C<title> attribute value of the viewport.
+
+=back
+
+=head2 meta_info
+
+If the viewports C<meta_info> contains a value for C<http_header>, It will
+be removed and set as C<http_header> argument. Next, the C<meta_http_header>
+fragment will be rendered for each key of the C<http_header> hash reference.
+
+After the C<http_header> processing, the remaining keys of the viewports
+C<meta_info> attribute hash reference will be rendered via the C<meta_member>
+fragment.
+
+=head2 meta_http_header
+
+Additionally provides these arguments:
+
+=over 4
+
+=item meta_name
+
+The current value of the C<_> argument, which will be set to the key of
+the C<http_header> argument hash reference when rendered by the
+C<meta_info> fragment.
+
+=item meta_value
+
+The value of the C<meta_name> key in the C<http_header> argument hash
+reference.
+
+=back
+
+=head2 meta_member
+
+Additionally provides these arguments:
+
+=over 4
+
+=item meta_name
+
+The current value of the C<_> argument, which will be set to the key of
+the viewport's C<meta_info> attribte value when rendered by the
+C<meta_info> fragment.
+
+=item meta_value
+
+The value of the C<meta_name> key in the viewport's C<meta_info> attribute
+hash reference.
+
+=back
+
+=head1 LAYOUT SETS
+
+=head2 base
+
+  share/skin/base/layout/site_layout.tt
+
+The base layout set will provide the following layouts:
+
+=over 4
+
+=item widget
+
+This layout will render the C<doctype> fragment at the top of the page. Then
+the traditional HTML layout with a C<html> element containing C<head> (rendering
+the C<head> fragment and C<body> (rendering the C<body> fragment) elements.
+
+=item head
+
+Will render the C<title> argument in a C<title> element. After that it will render
+the C<head_meta>, C<head_scripts> and C<head_style> fragments.
+
+=item head_meta
+
+Renders the C<meta_info> fragment.
+
+=item meta_http_header
+
+Renders a C<meta> element where the value of the C<http-equiv> attribute is set to
+the C<meta_name> argument and the C<content> attribute is set to the C<meta_value>
+argument.
+
+=item meta_member
+
+Renders a C<meta> element where the C<name> attribute is set to the C<meta_name>
+argument and the C<content> attribute is set to the C<meta_value> argument.
+
+=item head_scripts
+
+Is empty by default.
+
+=item head_style
+
+Is empty by default.
+
+=item doctype
+
+By default this renders an C<XHTML 1.0 Transitional> doctype.
+
+=item body
+
+This will render the C<inner> viewports in the focus stack.
+
+=back
+
+=head2 default
+
+  share/skin/default/layout/site_layout.tt
+
+The C<site_layout> layout set in the C<default> skin extends the one in the
+C<base> skin documented above.
+
+The following layouts are provided:
+
+=over 4
+
+=item widget
+
+This layout is mostly the same as the one in the C<base> skin, except that
+the C<html> element has C<xmlns> and C<xml:lang> attributes set.
+
+=back
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
index db35a08..485a8b5 100644 (file)
@@ -26,3 +26,54 @@ __PACKAGE__->meta->make_immutable;
 1;
 
 __END__;
+
+=head1 NAME
+
+Reaction::UI::Widget::URI - A hyperlink reference by URI value
+
+=head1 DESCRIPTION
+
+This widget allows a layout template to render a hyperlink with either a
+simple string or another viewport as the contents of the link.
+
+=head1 FRAGMENTS
+
+=head2 widget
+
+Before the C<widget> fragment is rendered, the C<uri> argument will be set
+to the return value of the C<uri> method on the viewport. The layout
+will render a hyperlink with the C<uri> as value of the C<href> attribute and
+the C<display_fragment> fragment as content of the element.
+
+=head2 display_fragment
+
+This will render nothing if the viewport doesn't return true when C<has_display>
+is called on it. If it has a C<display> defined and it is a viewport, the C<_>
+argument will be set to it and the C<viewport> fragment (inherited from
+L<Reaction::UI::Widget> will be rendered. If the C<display> is not a viewport,
+the C<string_value> argument will be set and the C<display_string> layout
+will be rendered.
+
+C<display_fragment> is only implemented in the widget class.
+
+=head2 display_string
+
+Only implemented in the layout set. This will simply output the value of the
+C<string_value> argument as content of the hyperlink element.
+
+=head1 LAYOUT SET
+
+  share/skin/base/layout/uri.tt
+
+This layout set will look for a widget called C<URI> in the 
+C<widget_search_path>.
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
index 1ab37be..eb83c39 100644 (file)
@@ -26,6 +26,52 @@ Reaction::UI::Widget::Value
 
 =head1 DESCRIPTION
 
+This widget provides the return value of the C<vlues_string> or C<value>
+method on the viewport (depending on which is available first) via the
+C<value> argument to widget.
+
+=head1 INCLUDED SUBCLASSES
+
+=over
+
+=item L<Reaction::UI::Widget::Value::Boolean>
+
+Will simply display the C<value>.
+
+=item L<Reaction::UI::Widget::Value::Collection>
+
+This widget iterates over a collection of values provided by the viewport
+and renders an unordered list out of them.
+
+=item L<Reaction::UI::Widget::Value::DateTime>
+
+A simple subclass of L<Reaction::UI::Widget::Value>, currently not doing
+much.
+
+=item L<Reaction::UI::Widget::Value::Image>
+
+Provides C<has_image> and C<no_image> blocks that will be rendered depending
+on the viewports C<value_string> attribute. The defaults are to either render
+an image tag, or to output nothing at all.
+
+=item L<Reaction::UI::Widget::Value::Number>
+
+A simple subclass of C<Reaction::UI::Widget::Value> that doesn't do much yet.
+
+=item L<Reaction::UI::Widget::Value::RelatedObject>
+
+A simple subclass of C<Reaction::UI::Widget::Value> that doesn't do much yet.
+
+=item L<Reaction::UI::Widget::Value::String>
+
+A simple subclass of C<Reaction::UI::Widget::Value> that doesn't do much yet.
+
+=item L<Reaction::UI::Widget::Value::Text>
+
+A simple subclass of C<Reaction::UI::Widget::Value> that doesn't do much yet.
+
+=back
+
 =head1 FRAGMENTS
 
 =head2 widget
index 5ac5d60..cbd69b7 100644 (file)
@@ -31,19 +31,34 @@ Reaction::UI::Widget::Value::Collection
 
 =head1 DESCRIPTION
 
-=head1 FRAGMENTS
+This widget provides an additional C<label> argument for the C<widget>
+fragment containing the localised value of the viewports C<label> attribute.
+
+It also implements the fragments C<list> and C<item>. 
+
+=head1 FRAGMENTS AND LAYOUTS
 
 =head2 widget
 
-renders C<label> and C<list> passing additional variable "viewport"
+This will set the C<label> argument to the return value of the C<label> method
+on the viewport. The base layout will then render the C<list> fragment.
 
 =head2 list
 
-renders fragment item over the viewport's C<value_names>
+This will render the C<item> fragment once for every entry in the viewports
+C<value_names>. The base layout will surround the rendered output with a unordered
+list.
 
 =head2 item
 
-C<content> contains the value of the current item ($_ / $_{_})
+This will set the argument C<name> to the localised value of the current iteration
+(stored in C<$_>). The base layout will render a list item with the value as
+html escaped content of the item.
+
+=head1 LAYOUT SETS
+
+  share/skin/base/layout/value/collection.tt
+  share/skin/base/layout/value/list.tt
 
 =head1 AUTHORS
 
index 15afbbb..f8cd1a9 100644 (file)
@@ -26,7 +26,7 @@ See L<Reaction::UI::Widget::Value>
 
 =head2 value
 
-C<content> contains the viewport's value_string
+C<value> contains the viewport's value_string.
 
 =head1 AUTHORS
 
index c072255..9338aff 100644 (file)
@@ -16,5 +16,56 @@ implements fragment image {
 
 __PACKAGE__->meta->make_immutable;
 
+=head1 NAME
+
+Reaction::UI::Widget::Value::Image - An image tag or non-image alternative
+
+=head1 DESCRIPTION
+
+This widget allows you to render an image container that uses different
+fragments for available and non-available images.
+
+=head1 FRAGMENTS AND LAYOUTS
+
+=head2 widget
+
+Has only layout implementation. The widget fragment is inherited from
+L<Reaction::UI::Widget>. The layout will simply render the
+C<image> fragment. This fragment can be overwritten by your own layout to
+render, for example, a frame around the image.
+
+=head2 image
+
+Is only implemented in the widget. If the viewport has a true value in
+C<value_string>, the C<uri> argument will be set to the value of the C<uri>
+attribute or method return value of the viewport, and the C<has_image>
+fragment will be rendered. 
+
+If C<value_string> is false, the C<no_image> fragment will be rendered.
+
+=head2 has_image
+
+This is only implemented in the layout file. It contains just an image
+tag and will be rendered when the viewport has a true C<value_string>.
+
+=head2 no_image
+
+This has only an empty implementation in the layout file. It will output
+nothing and is called when then viewport has a false C<value_string>.
+
+=head1 LAYOUT TEMPLATE
+
+  share/skin/base/layout/value/image.tt
+
+=head1 AUTHORS
+
+See L<Reaction::Class> for authors.
+
+=head1 LICENSE
+
+See L<Reaction::Class> for the license.
+
+=cut
+
 
 1;
index e68add0..f9c1b5a 100644 (file)
@@ -132,10 +132,98 @@ __PACKAGE__->meta->make_immutable;
 
 =head1 NAME
 
-Reaction::UI::WidgetClass
+Reaction::UI::WidgetClass - Create a new widget class
 
 =head1 DESCRIPTION
 
+Turns the importing package into a widget class. It will export:
+
+=over 4
+
+=item All of L<Moose>
+
+=item All of L<Reaction::Class>
+
+=item L<strict> and L<warnings>
+
+=item See L</EXPORTS> for this package's own exports
+
+=back
+
+It will also set the value of C<default_base> as new superclass. The default is
+C<Reaction::UI::Widget>.
+
+=head1 EXPORTS
+
+=head2 over
+
+  over $collection
+
+Used in combination with L</render> to render a fragment for a series of values:
+
+  render fragment_name => over [1, 2, 3];
+
+=head2 render
+
+  render $fragment_name;
+  render $fragment_name, $over;
+
+With only the fragment name as argument, it renders that fragment. If an C<$over>
+collection is specified with the L</over> keyword, the fragment is rendered once
+for every value in the collection. The value will be accessible in the topic
+argument C<_>.
+
+=head2 arg
+
+  arg $arg_name, $arg_value;
+
+Sets the fragment argument C<$arg_name> to C<$arg_value>;
+
+=head2 localized
+
+  localize $value;
+
+Calls the view's C<localize> method to localize the passed value.
+
+=head2 call_next
+
+  call_next;
+
+Calls the parent fragment.
+
+=head2 event_id
+
+  event_id $event_name;
+
+Fetches the event id for the event C<$event_name> from the viewport via its C<event_id_for>
+method.
+
+=head2 event_uri
+
+  event_uri \%events;
+
+Returns an L<URI> object with the event ids corresponding to the keys in the C<%events> 
+argument and the values being the values of the hash reference.
+
+=head2 attrs
+
+  attrs \%attrs;
+
+Builds a string of rendered element attributes out of the C<%attrs> hash reference argument.
+
+=head2 implements
+
+  implements fragment foo { ... };
+  implements bar => sub { ... };
+
+Implements a method or a fragment in the widget class.
+
+=head2 fragment
+
+  fragment foo { ... };
+
+Creates a new fragment named C<foo> with a implementation in the block.
+
 =head1 AUTHORS
 
 See L<Reaction::Class> for authors.