1Maypole::Model::CDBI::AUssFeorrmC(o3n)tributed Perl DocuMmaeynptoaltei:o:nModel::CDBI::AsForm(3)
2
3
4

NAME

6       Maypole::Model:CDBI::AsForm - Produce HTML form elements for database
7       columns
8

SYNOPSIS

10           package Music::CD;
11           use Maypole::Model::CDBI::AsForm;
12           use base 'Class::DBI';
13           use CGI;
14           ...
15
16           sub create_or_edit {
17               my $self = shift;
18               my %cgi_field = $self->to_cgi;
19               return start_form,
20                      (map { "<b>$_</b>: ". $cgi_field{$_}->as_HTML." <br>" }
21                           $class->Columns),
22                      end_form;
23           }
24
25
26          . . .
27
28           # Somewhere else in a Maypole application about beer...
29
30
31
32
33          $beer->to_field('brewery', 'textfield', {
34                       name => 'brewery_id', value => $beer->brewery,
35                       # however, no need to set value since $beer is object
36          });
37
38          # Rate a beer
39          $beer->to_field(rating =>  select => {
40                       items => [1 , 2, 3, 4, 5],
41          });
42
43          # Select a Brewery to visit in the UK
44          Brewery->to_field(brewery_id => {
45                       items => [ Brewery->search_like(location => 'UK') ],
46          });
47
48         # Make a select for a boolean field
49         $Pub->to_field('open' , { items => [ {'Open' => 1, 'Closed' => 0 } ] });
50
51          $beer->to_field('brewery', {
52                       selected => $beer->brewery, # again not necessary since caller is obj.
53          });
54
55
56           $beer->to_field('brewery', 'link_hidden', {r => $r, uri => 'www.maypole.perl.org/brewery/view/'.$beer->brewery});
57           # an html link that is also a hidden input to the object. R is required to
58           # make the uri  unless you  pass a  uri
59
60
61
62           #####################################################
63           # Templates Usage
64
65           <form ..>
66
67           ...
68
69           <label>
70
71            <span class="field"> [% classmetadata.colnames.$col %] : </span>
72
73            [% object.to_field(col).as_XML %]
74
75           </label>
76
77           . . .
78
79           <label>
80
81            <span class="field"> Brewery : </span>
82
83            [% object.to_field('brewery', { selected => 23} ).as_XML %]
84
85           </label>
86
87           . . .
88
89           </form>
90
91
92           #####################################################
93           # Advanced Usage
94
95           # has_many select
96           package Job;
97           __PACKAGE__->has_a('job_employer' => 'Employer');
98           __PACKAGE__->has_a('contact'  => 'Contact')
99
100           package Contact;
101           __PACKAGE__->has_a('cont_employer' => 'Employer');
102           __PACKAGE__->has_many('jobs'  => 'Job',
103                                 { join => { job_employer => 'cont_employer' },
104                                   constraint => { 'finshed' => 0  },
105                                   order_by   => "created ASC",
106                                 }
107                                );
108
109           package Employer;
110           __PACKAGE__->has_many('jobs'  => 'Job',);
111           __PACKAGE__->has_many('contacts'  => 'Contact',
112                                 order_by => 'name DESC',
113                                );
114
115
116         # Choose some jobs to add to a contact (has multiple attribute).
117         my $job_sel = Contact->to_field('jobs'); # Uses constraint and order by
118
119
120         # Choose a job from $contact->jobs
121         my $job_sel = $contact->to_field('jobs');
122
123         1;
124

DESCRIPTION

126       This module helps to generate HTML forms for creating new database rows
127       or editing existing rows. It maps column names in a database table to
128       HTML form elements which fit the schema. Large text fields are turned
129       into textareas, and fields with a has-a relationship to other
130       "Class::DBI" tables are turned into select drop-downs populated with
131       objects from the joined class.
132

ARGUMENTS HASH

134       This provides a convenient way to tweak AsForm's behavior in
135       exceptional or not so exceptional instances. Below describes the
136       arguments hash and example usages.
137
138         $beer->to_field($col, $how, $args);
139         $beer->to_field($col, $args);
140
141       Not all _to_* methods pay attention to all arguments. For example,
142       '_to_textfield' does not look in $args->{'items'} at all.
143
144       name -- the name the element will have , this trumps the derived name.
145             $beer->to_field('brewery', 'readonly', {
146                           name => 'brewery_id'
147             });
148
149       value -- the initial value the element will have, trumps derived value
150             $beer->to_field('brewery', 'textfield', {
151                           name => 'brewery_id', value => $beer->brewery,
152                           # however, no need to set value since $beer is object
153             });
154
155       items -- array of items generally used to make select box options
156           Can be array of objects, hashes, arrays, or strings, or just a
157           hash.
158
159              # Rate a beer
160              $beer->to_field(rating =>  select => {
161                           items => [1 , 2, 3, 4, 5],
162              });
163
164              # Select a Brewery to visit in the UK
165              Brewery->to_field(brewery_id => {
166                           items => [ Brewery->search_like(location => 'UK') ],
167              });
168
169             # Make a select for a boolean field
170             $Pub->to_field('open' , { items => [ {'Open' => 1, 'Closed' => 0 } ] });
171
172       selected -- something representing which item is selected in a select
173       box
174              $beer->to_field('brewery', {
175                           selected => $beer->brewery, # again not necessary since caller is obj.
176              });
177
178           Can be an simple scalar id, an object, or an array of either
179
180       class -- the class for which the input being made for field pertains
181       to.
182           This in almost always derived in cases where it may be difficult to
183           derive, --
184              # Select beers to serve on handpump
185              Pub->to_field(handpumps => select => {           class =>
186           'Beer', order_by => 'name ASC', multiple => 1,      });
187
188       column_type -- a string representing column type
189             $pub->to_field('open', 'bool_select', {
190                           column_type => "bool('Closed', 'Open'),
191             });
192
193       column_nullable -- flag saying if column is nullable or not
194           Generally this can be set to get or not get a null/empty option
195           added to a select box.  AsForm attempts to call
196           "$class->column_nullable" to set this and it defaults to true if
197           there is no shuch method.
198
199             $beer->to_field('brewery', { column_nullable => 1 });
200
201       r or request  -- the Mapyole request object
202       uri -- uri for a link , used in methods such as _to_link_hidden
203            $beer->to_field('brewery', 'link_hidden',
204                     {r => $r, uri => 'www.maypole.perl.org/brewery/view/'.$beer->brewery});
205            # an html link that is also a hidden input to the object. R is required to
206            # make the uri  unless you  pass a  uri
207
208       order_by, constraint, join
209           These are used in making select boxes. order_by is a simple order
210           by clause and constraint and join are hashes used to limit the rows
211           selected. The difference is that join uses methods of the object
212           and constraint uses static values. You can also specify these in
213           the relationship definitions.  See the relationships documentation
214           of how to set arbitrayr meta info.
215
216             BeerDB::LondonBeer->has_a('brewery', 'BeerDB::Brewery',
217                              order_by     => 'brewery_name ASC',
218                      constraint   => {location  => 'London'},
219                      'join'       => {'brewery_tablecolumn  => 'beer_obj_column'},
220                     );
221
222       no_hidden_constraints --
223           Tell AsForm not to make hidden inputs for relationship constraints.
224           It does this  sometimes when making foreign inputs. However, i
225           think it should not do this and that the FromCGI 's _create_related
226           method should do it.
227
228   to_cgi
229         $self->to_cgi([@columns, $args]);
230
231       This returns a hash mapping all the column names to HTML::Element
232       objects representing form widgets.  It takes two opitonal arguments --
233       a list of columns and a hashref of hashes of arguments for each column.
234       If called with an object like for editing, the inputs will have the
235       object's values.
236
237         $self->to_cgi(); # uses $self->columns;  # most used
238         $self->to_cgi(qw/brewery style rating/); # sometimes
239         # and on rare occassions this is desireable if you have a lot of fields
240         # and dont want to call to_field a bunch of times just to tweak one or
241         # two of them.
242         $self->to_cgi(@cols, {brewery => {
243                                                                                how => 'textfield' # too big for select
244                                                                          },
245                                                       style   => {
246                                                                                column_nullable => 0,
247                                                                                how => 'select',
248                                                                                items => ['Ale', 'Lager']
249                                                                          }
250                                                       });
251
252   to_field($field [, $how][, $args])
253       This maps an individual column to a form element. The "how" argument
254       can be used to force the field type into any you want. All that you
255       need is a method named "_to_$how" in your class. Your class inherits
256       many from AsForm  already.
257
258       If "how" is specified but the class cannot call the method it maps to,
259       then AsForm will issue a warning and the default input will be made.
260       You can write your own "_to_$how" methods and AsForm comes with many.
261       See "HOW Methods". You can also pass this argument in $args->{how}.
262
263   search_inputs
264         my $cgi = $class->search_inputs ([$args]); # optional $args
265
266       Returns hash or hashref of search inputs elements for a class making
267       sure the inputs are empty of any initial values.  You can specify what
268       columns you want inputs for in $args->{columns} or by the method
269       "search_columns". The default is  "display_columns".  If you want to te
270       search on columns in related classes you can do that by specifying a
271       one element hashref in place of the column name where the key is the
272       related "column" (has_a or has_many method for example) and the value
273       is a list ref of columns to search on in the related class.
274
275       Example:
276         sub  BeerDB::Beer::search_columns {       return ( 'name' , 'rating',
277       { brewery => [ 'name', 'location'] } );
278         }
279
280         # Now foreign inputs are made for Brewery name and location and the
281         # there will be no name clashing and processing can be automated.
282
283   unselect_element
284         unselect any selected elements in a HTML::Element select list widget
285
286   _field_from_how($field, $how,$args)
287       Returns an input element based the "how" parameter or nothing at all.
288       Override at will.
289
290   _field_from_relationship($field, $args)
291       Returns an input based on the relationship associated with the field or
292       nothing.  Override at will.
293
294       For has_a it will give select box
295
296   _field_from_column($field, $args)
297       Returns an input based on the column's characteristics, namely type, or
298       nothing.  Override at will.
299
300   recognized arguments
301         selected => $object|$id,
302         name     => $name,
303         value    => $value,
304         where    => SQL 'WHERE' clause,
305         order_by => SQL 'ORDER BY' clause,
306         constraint => hash of constraints to search
307         limit    => SQL 'LIMIT' clause,
308         items    => [ @items_of_same_type_to_select_from ],
309         class => $class_we_are_selecting_from
310         stringify => $stringify_coderef|$method_name
311
312   1. a select box out of a has_a or has_many related class. # For has_a the
313       default behavior is to make a select box of every element in # related
314       class and you choose one. #Or explicitly you can create one and pass
315       options like where and order BeerDB::Beer->to_field('brewery','select',
316       {where => "location = 'Germany'");
317         # For has_many the default is to get a multiple select box with all objects.
318         # If called as an object method, the objects existing ones will be selected.
319         Brewery::BeerDB->to_field('beers','select', {where => "rating > 5"});
320
321   2. a select box for objects of arbitrary class -- say BeerDB::Beer for fun.
322       # general BeerDB::Beer->to_field('', 'select', $options)
323         BeerDB::Beer->to_field('', 'select'); # Select box of all the rows in class
324                                                                         # with PK as ID, $Class->to_field() same.
325         BeerDB::Beer->to_field('','select',{ where => "rating > 3 AND class like 'Ale'", order_by => 'rating DESC, beer_id ASC' , limit => 10});
326         # specify exact where clause
327
328   3. If you already have a list of objects to select from  --
329         BeerDB:;Beer->to_field($col, 'select' , {items => $objects});
330
331       # 3. a select box for arbitrary set of objects
332        # Pass array ref of objects as first arg rather than field
333        $any_class_or_obj->to_field([BeerDB::Beer->search(favorite => 1)],
334       'select',);
335
336   _to_enum_select
337       Returns a select box for the an enum column type.
338
339   _to_bool_select
340       Returns a "No/Yes"  select box for a boolean column type.
341
342   _to_hidden($field, $args)
343       This makes a hidden html element input. It uses the "name" and "value"
344       arguments. If one or both are not there, it will look for an object in
345       "items->[0]" or the caller. Then it will use $field or the primary key
346       for name  and the value of the column by the derived name.
347
348   _to_link_hidden($col, $args)
349       Makes a link with a hidden input with the id of $obj as the value and
350       name.  Name defaults to the objects primary key. The object defaults to
351       self.
352
353   _to_foreign_inputs
354       Creates inputs for a foreign class, usually related to the calling
355       class or object. In names them so they do not clash with other names
356       and so they can be processed generically.  See _rename_foreign_inputs
357       below  and Maypole::Model::CDBI::FromCGI::classify_foreign_inputs.
358
359       Arguments this recognizes are :
360
361               related_meta -- if you have this, great, othervise it will determine or die
362               columns  -- list of columns to make inputs for
363               request (r) -- TODO the Maypole request so we can see what action
364
365   _hash_selected
366       *Function* to make sense out of the "selected" argument which has
367       values of the options that should be selected by default when making a
368       select box.  It can be in a number formats.  This method returns a map
369       of which options to select with the values being the keys in the map (
370       {val1 => 1, val2 = 1} ).
371
372       Currently this method  handles the following formats for the "selected"
373       argument and in the following ways
374
375         Object                                -- uses the id method  to get the value
376         Scalar                                -- assumes it *is* the value
377         Array ref of objects  -- same as Object
378         Arrays of data                -- uses the 0th element in each
379         Hashes of data                -- uses key named 'id'
380
381   _select_guts
382       Internal api  method to make the actual select box form elements.  the
383       data.
384
385       Items to make options out of can be
386         Hash, Array,
387         Array of CDBI objects.
388         Array of scalars ,
389         Array or  Array refs with cols from class,
390         Array of hashes
391
392   _options_from_objects ( $objects, $args);
393       Private method to makes a options out of  objects. It attempts to call
394       each objects stringify method specified in $args->{stringify} as the
395       content. Otherwise the default stringification prevails.
396
397       *Note only  single primary keys supported
398
399   _to_checkbox
400       Makes a checkbox element -- TODO
401
402   _to_radio
403       Makes a radio button element -- TODO
404
405   _rename_foreign_input
406       _rename_foreign_input($html_el_or_hash_of_them); # changes made by
407       reference
408
409       Recursively renames the foreign inputs made by _to_foreign_inputs so
410       they can be processed generically.  It uses foreign_input_delimiter.
411
412       So if an Employee is a Person who has_many  Addresses and you call and
413       the method 'foreign_input_delimiter' returns '__AF__' then
414
415         Employee->to_field("person");
416
417       will get inputs for the Person as well as their Address (by default,
418       override _field_from_relationship to change logic) named like this:
419
420         person__AF__address__AF__street
421         person__AF__address__AF__city
422         person__AF__address__AF__state
423         person__AF__address__AF__zip
424
425       And the processor would know to create this address, put the address id
426       in person->{address} data slot, insert the person and put the person id
427       in the employee->{person} data slot and then insert the employee with
428       that data.
429
430   foreign_input_delimiter
431       This tells AsForm what to use to delmit forieign input names. This is
432       important to avoid name clashes as well as automating processing of
433       forms.
434
435   _box($value)
436       This functions computes the dimensions of a textarea based on the value
437       or the defaults.
438

CHANGES

440       1.0 15-07-2004 -- Initial version =head1 MAINTAINER
441
442       Maypole Developers
443

AUTHORS

445       Peter Speltz, Aaron Trevena
446

AUTHORS EMERITUS

448       Simon Cozens, Tony Bowden
449

TODO

451         Testing - lots
452         checkbox generalization
453         radio generalization
454         Make link_hidden use standard make_url stuff when it gets in Maypole
455         How do you tell AF --" I want a has_many select box for this every time so,
456            when you call "to_field($this_hasmany)" you get a select box
457

BUGS and QUERIES

459       Please direct all correspondence regarding this module to:
460        Maypole list.
461
463       Copyright 2003-2004 by Simon Cozens / Tony Bowden
464
465       This library is free software; you can redistribute it and/or modify it
466       under the same terms as Perl itself.
467

SEE ALSO

469       Class::DBI, Class::DBI::FromCGI, HTML::Element.
470
471
472
473perl v5.34.0                      2022-01-21   Maypole::Model::CDBI::AsForm(3)
Impressum