diff options
author | phaylon <phaylon@03d0b0b2-0e1a-0410-a411-fdb2f4bd65d7> | 2009-02-16 02:40:11 +0000 |
---|---|---|
committer | phaylon <phaylon@03d0b0b2-0e1a-0410-a411-fdb2f4bd65d7> | 2009-02-16 02:40:11 +0000 |
commit | f9b32c83550e273bec97c9be5b63079addd4846b (patch) | |
tree | c7bdd746379aa8bb3ffd1e2500d86daf32d3b8e0 | |
parent | 63bb30b44346800078dc638dcc484828d89c2ad4 (diff) | |
download | reaction-f9b32c83550e273bec97c9be5b63079addd4846b.tar.gz reaction-f9b32c83550e273bec97c9be5b63079addd4846b.zip |
widget documentation
41 files changed, 2117 insertions, 65 deletions
diff --git a/lib/Reaction/Manual/Tutorial.pod b/lib/Reaction/Manual/Tutorial.pod index 4dd23d4..1753577 100644 --- a/lib/Reaction/Manual/Tutorial.pod +++ b/lib/Reaction/Manual/Tutorial.pod @@ -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 index 0000000..14d1fc0 --- /dev/null +++ b/lib/Reaction/Manual/Widgets.pod @@ -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 + diff --git a/lib/Reaction/UI/Widget.pm b/lib/Reaction/UI/Widget.pm index 07a109f..50085af 100644 --- a/lib/Reaction/UI/Widget.pm +++ b/lib/Reaction/UI/Widget.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Action.pm b/lib/Reaction/UI/Widget/Action.pm index 9c94174..0994e6e 100644 --- a/lib/Reaction/UI/Widget/Action.pm +++ b/lib/Reaction/UI/Widget/Action.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Action/Link.pm b/lib/Reaction/UI/Widget/Action/Link.pm index 1063ed0..0c40670 100644 --- a/lib/Reaction/UI/Widget/Action/Link.pm +++ b/lib/Reaction/UI/Widget/Action/Link.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Collection.pm b/lib/Reaction/UI/Widget/Collection.pm index e679740..e991c4c 100644 --- a/lib/Reaction/UI/Widget/Collection.pm +++ b/lib/Reaction/UI/Widget/Collection.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Collection/Grid.pm b/lib/Reaction/UI/Widget/Collection/Grid.pm index 823afc6..2856793 100644 --- a/lib/Reaction/UI/Widget/Collection/Grid.pm +++ b/lib/Reaction/UI/Widget/Collection/Grid.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Collection/Grid/Member.pm b/lib/Reaction/UI/Widget/Collection/Grid/Member.pm index 19c355a..24168a6 100644 --- a/lib/Reaction/UI/Widget/Collection/Grid/Member.pm +++ b/lib/Reaction/UI/Widget/Collection/Grid/Member.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Collection/Grid/Member/WithActions.pm b/lib/Reaction/UI/Widget/Collection/Grid/Member/WithActions.pm index 156f216..f3b4454 100644 --- a/lib/Reaction/UI/Widget/Collection/Grid/Member/WithActions.pm +++ b/lib/Reaction/UI/Widget/Collection/Grid/Member/WithActions.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Container.pm b/lib/Reaction/UI/Widget/Container.pm index 11ac72f..f470d51 100644 --- a/lib/Reaction/UI/Widget/Container.pm +++ b/lib/Reaction/UI/Widget/Container.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Data.pm b/lib/Reaction/UI/Widget/Data.pm index 95da53c..39f3348 100644 --- a/lib/Reaction/UI/Widget/Data.pm +++ b/lib/Reaction/UI/Widget/Data.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field.pm b/lib/Reaction/UI/Widget/Field.pm index 0a7e140..7e5fcd3 100644 --- a/lib/Reaction/UI/Widget/Field.pm +++ b/lib/Reaction/UI/Widget/Field.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Array.pm b/lib/Reaction/UI/Widget/Field/Array.pm index fc1bf33..f80bf67 100644 --- a/lib/Reaction/UI/Widget/Field/Array.pm +++ b/lib/Reaction/UI/Widget/Field/Array.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Collection.pm b/lib/Reaction/UI/Widget/Field/Collection.pm index 6f59532..c54f8a6 100644 --- a/lib/Reaction/UI/Widget/Field/Collection.pm +++ b/lib/Reaction/UI/Widget/Field/Collection.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Field/Container.pm b/lib/Reaction/UI/Widget/Field/Container.pm index ba7fa28..e95f1f7 100644 --- a/lib/Reaction/UI/Widget/Field/Container.pm +++ b/lib/Reaction/UI/Widget/Field/Container.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Field/Image.pm b/lib/Reaction/UI/Widget/Field/Image.pm index 839545e..b2a379a 100644 --- a/lib/Reaction/UI/Widget/Field/Image.pm +++ b/lib/Reaction/UI/Widget/Field/Image.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable.pm b/lib/Reaction/UI/Widget/Field/Mutable.pm index 73b14e3..9fc565e 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable/Boolean.pm b/lib/Reaction/UI/Widget/Field/Mutable/Boolean.pm index 97c1803..4b17058 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/Boolean.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/Boolean.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable/ChooseMany.pm b/lib/Reaction/UI/Widget/Field/Mutable/ChooseMany.pm index bb80615..62f6747 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/ChooseMany.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/ChooseMany.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable/ChooseOne.pm b/lib/Reaction/UI/Widget/Field/Mutable/ChooseOne.pm index 98b9b7d..b8ac8aa 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/ChooseOne.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/ChooseOne.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Field/Mutable/DateTime.pm b/lib/Reaction/UI/Widget/Field/Mutable/DateTime.pm index ab626fa..ac5973d 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/DateTime.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/DateTime.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable/File.pm b/lib/Reaction/UI/Widget/Field/Mutable/File.pm index b8d399f..7578e30 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/File.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/File.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable/HiddenArray.pm b/lib/Reaction/UI/Widget/Field/Mutable/HiddenArray.pm index 0cecc5e..0b8cce7 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/HiddenArray.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/HiddenArray.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Field/Mutable/MatchingPasswords.pm b/lib/Reaction/UI/Widget/Field/Mutable/MatchingPasswords.pm index 5668510..544b11a 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/MatchingPasswords.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/MatchingPasswords.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable/Password.pm b/lib/Reaction/UI/Widget/Field/Mutable/Password.pm index e83b564..1b19057 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/Password.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/Password.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable/String.pm b/lib/Reaction/UI/Widget/Field/Mutable/String.pm index f93a087..32b8e1f 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/String.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/String.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable/Text.pm b/lib/Reaction/UI/Widget/Field/Mutable/Text.pm index d902f18..d2dab85 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/Text.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/Text.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Mutable/TimeRange.pm b/lib/Reaction/UI/Widget/Field/Mutable/TimeRange.pm index aad4895..3ccb1d0 100644 --- a/lib/Reaction/UI/Widget/Field/Mutable/TimeRange.pm +++ b/lib/Reaction/UI/Widget/Field/Mutable/TimeRange.pm @@ -16,7 +16,7 @@ __END__; =head1 NAME -Reaction::UI::Widget::Field::TimeRange +Reaction::UI::Widget::Field::TimeRange - Input a time range =head1 DESCRIPTION diff --git a/lib/Reaction/UI/Widget/Field/String.pm b/lib/Reaction/UI/Widget/Field/String.pm index 3a4a4ae..0515bbd 100644 --- a/lib/Reaction/UI/Widget/Field/String.pm +++ b/lib/Reaction/UI/Widget/Field/String.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Field/Text.pm b/lib/Reaction/UI/Widget/Field/Text.pm index 293c6da..16f8cd5 100644 --- a/lib/Reaction/UI/Widget/Field/Text.pm +++ b/lib/Reaction/UI/Widget/Field/Text.pm @@ -16,7 +16,7 @@ __END__; =head1 NAME -Reaction::UI::Widget::Field::Text +Reaction::UI::Widget::Field::Text - A text field =head1 DESCRIPTION diff --git a/lib/Reaction/UI/Widget/Image.pm b/lib/Reaction/UI/Widget/Image.pm index 18eb310..705859d 100644 --- a/lib/Reaction/UI/Widget/Image.pm +++ b/lib/Reaction/UI/Widget/Image.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/ListView.pm b/lib/Reaction/UI/Widget/ListView.pm index 966493a..1db21ba 100644 --- a/lib/Reaction/UI/Widget/ListView.pm +++ b/lib/Reaction/UI/Widget/ListView.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Object.pm b/lib/Reaction/UI/Widget/Object.pm index a44a66d..de83e25 100644 --- a/lib/Reaction/UI/Widget/Object.pm +++ b/lib/Reaction/UI/Widget/Object.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/Object/Mutable.pm b/lib/Reaction/UI/Widget/Object/Mutable.pm index 563c72b..8f391a5 100644 --- a/lib/Reaction/UI/Widget/Object/Mutable.pm +++ b/lib/Reaction/UI/Widget/Object/Mutable.pm @@ -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. diff --git a/lib/Reaction/UI/Widget/SiteLayout.pm b/lib/Reaction/UI/Widget/SiteLayout.pm index d37003f..a02df37 100644 --- a/lib/Reaction/UI/Widget/SiteLayout.pm +++ b/lib/Reaction/UI/Widget/SiteLayout.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/URI.pm b/lib/Reaction/UI/Widget/URI.pm index db35a08..485a8b5 100644 --- a/lib/Reaction/UI/Widget/URI.pm +++ b/lib/Reaction/UI/Widget/URI.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Value.pm b/lib/Reaction/UI/Widget/Value.pm index 1ab37be..eb83c39 100644 --- a/lib/Reaction/UI/Widget/Value.pm +++ b/lib/Reaction/UI/Widget/Value.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Value/Collection.pm b/lib/Reaction/UI/Widget/Value/Collection.pm index 5ac5d60..cbd69b7 100644 --- a/lib/Reaction/UI/Widget/Value/Collection.pm +++ b/lib/Reaction/UI/Widget/Value/Collection.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Value/DateTime.pm b/lib/Reaction/UI/Widget/Value/DateTime.pm index 15afbbb..f8cd1a9 100644 --- a/lib/Reaction/UI/Widget/Value/DateTime.pm +++ b/lib/Reaction/UI/Widget/Value/DateTime.pm @@ -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 diff --git a/lib/Reaction/UI/Widget/Value/Image.pm b/lib/Reaction/UI/Widget/Value/Image.pm index c072255..9338aff 100644 --- a/lib/Reaction/UI/Widget/Value/Image.pm +++ b/lib/Reaction/UI/Widget/Value/Image.pm @@ -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; diff --git a/lib/Reaction/UI/WidgetClass.pm b/lib/Reaction/UI/WidgetClass.pm index e68add0..f9c1b5a 100644 --- a/lib/Reaction/UI/WidgetClass.pm +++ b/lib/Reaction/UI/WidgetClass.pm @@ -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. |