diff options
author | cvs2git <cvs2git> | 2010-12-27 00:04:45 +0000 |
---|---|---|
committer | cvs2git <cvs2git> | 2010-12-27 00:04:45 +0000 |
commit | c82d349f864e6bd9f96fd1156903bc1f7193a203 (patch) | |
tree | e117a87533656110b6acd56fc0ca64289892a9f5 /rt/docs/using_forms_widgets.pod | |
parent | 74e058c8a010ef6feb539248a550d0bb169c1e94 (diff) |
This commit was manufactured by cvs2svn to create tag 'TORRUS_1_0_9'.TORRUS_1_0_9
Diffstat (limited to 'rt/docs/using_forms_widgets.pod')
-rw-r--r-- | rt/docs/using_forms_widgets.pod | 113 |
1 files changed, 0 insertions, 113 deletions
diff --git a/rt/docs/using_forms_widgets.pod b/rt/docs/using_forms_widgets.pod deleted file mode 100644 index 8deb91362..000000000 --- a/rt/docs/using_forms_widgets.pod +++ /dev/null @@ -1,113 +0,0 @@ -=head1 Using widgets F<html/Widgets/Form*> - -This widgets was implemented to address several common issues in handling -request arguments and allow developers to avoid reinventing the wheel. - -=head2 General info - -Each component shows widget by default and has two methods: Process and -InputOnly. The first one method process arguments and return new value -of a parametr. The second one is helper that shows only form elements -with minimum of required text labels. - -So you show a widget with: - <& /Widgets/Form/Integer, - Name => 'NameOfInputElement', - Description => 'Input integer', - &> - -You can show only C<input> box using: - <& /Widgets/Form/Integer:InputOnly, - Name => 'NameOfInputElement', - &> - -In such a simple case you even can avoid processing. Yeah, most probably -you want to check if value is really integer, but these widgets don't -do validation for you, but they are more about fetching values from -hash of arguments, showing these values to user and preserving state -of value between form reloads (see below). - -=head2 Processing - -Processing is required when you use L<extended features|/Extendent features>, -such as Default, Multiple or Alternative. - -To process arguments of a request you have to do the following: - $ARGS{'NameOfInputElement'} = $m->comp( - '/Widgets/Form/Integer:Process', - Arguments => \%ARGS, - Name => 'NameOfInputElement', - ); - -The method returns processed value in canonical form. For different widgets -a canonical form is different and depends on activated features, so you must -always activate the same features during showing a widget and processing -results. - -=head2 Extendent features - -=head3 Default value - -If C<Default> argument is true then widgets expect that there is some -default value for argument if user fills nothing. 'Nothing' in each -widget is different, for example in select box it's special option -which is always the first one, in integer box string '' means empty -value, but boolean box uses radio buttons in this case with three -options: Yes, No and Default. - -Each widget that supports C<Default> feature as well has C<DefaultLabel> and -C<DefaultValue> arguments. - -=head4 Processing and showing with activated Default feature - -When this option is activated then C<Process> method returns undef -value if user selected default value. So for integer box it's empty -string and so on. - -As well when you show a widget you should pass undef as C<CurrentValue> -to inform widget that the current value is default one. - -As all methods of a widget are consistent in this behaviour so you -shouldn't care much about that, but this allows you to implement -custom actions if processing returned undef, for example delete user's -preference record instead of updating it (default value may change later to). - -=head4 C<DefaultValue> when C<Default> is not active - -DefaultValue argument is still actual in the Process method even if -C<Default> is not true. This argument defines intial value. If value -of a key in Arguments is not defined then it's treated as intial state -and the method returns default value. - -=head3 Multiple and Alternative - -These options are only supported by the select widget. - -TODO: Add more info - -=head2 Implementation details - -=head3 Boolean widget - -This widget a little bit tricky. When you use Default option then -things are simple and you see three radio buttons, but in other -case we use a checkbox. But as you know browsers don't pass unchecked -boxes to server, so arguments of a request has no entry for them. - -In the latter case it's hard to figure out case when user unselected -value. Imagine form with a checkbox, you want show it checked by -default and as well form is reloadable (like Reply forms that have -"Add Another File" buttons). User uncheck the box and then upload -file, in this case you want to show user's choice instead of default, -but browser doesn't send any value and you can not figure out if -it's initial state or page reload. To solve this problem we use magic -hidden input field with the same name as the box and value equal to -zero (0). Mason folds arguments with the same name into array refs, so -we get 0 if box is unchecked and [0, 1] if box is checked. An array -reference is true value and 0 is defined value so we know that it's -not initial state and avoid switching back to default. As well this -trick works good in a case when you want show a link to a page and -define default choice for some boolean argument, you don't need -to set argument twice, you just set it to true value (for ex. 1) and -things just work. - |