1Maypole::Model::CDBI::AUssFeorrmC(o3n)tributed Perl DocuMmaeynptoaltei:o:nModel::CDBI::AsForm(3)
2
6 Maypole::Model:CDBI::AsForm - Produce HTML form elements for database
7 columns
8
10 package Music::CD;
11 use Maypole::Model::CDBI::AsForm;
12 use base 'Class::DBI';
13 use CGI;
14 ...
15 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 . . .
27 # Somewhere else in a Maypole application about beer...
29 $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 # Rate a beer
39 $beer->to_field(rating => select => {
40 items => [1 , 2, 3, 4, 5],
41 });
42 # Select a Brewery to visit in the UK
44 Brewery->to_field(brewery_id => {
45 items => [ Brewery->search_like(location => 'UK') ],
46 });
47 # Make a select for a boolean field
49 $Pub->to_field('open' , { items => [ {'Open' => 1, 'Closed' => 0 } ] });
50 $beer->to_field('brewery', {
52 selected => $beer->brewery, # again not necessary since caller is obj.
53 });
54 $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 #####################################################
63 # Templates Usage
64 <form ..>
66 ...
68 <label>
70 <span class="field"> [% classmetadata.colnames.$col %] : </span>
72 [% object.to_field(col).as_XML %]
74 </label>
76 . . .
78 <label>
80 <span class="field"> Brewery : </span>
82 [% object.to_field('brewery', { selected => 23} ).as_XML %]
84 </label>
86 . . .
88 </form>
90 #####################################################
93 # Advanced Usage
94 # has_many select
96 package Job;
97 __PACKAGE__->has_a('job_employer' => 'Employer');
98 __PACKAGE__->has_a('contact' => 'Contact')
99 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 package Employer;
110 __PACKAGE__->has_many('jobs' => 'Job',);
111 __PACKAGE__->has_many('contacts' => 'Contact',
112 order_by => 'name DESC',
113 );
114 # 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 # Choose a job from $contact->jobs
121 my $job_sel = $contact->to_field('jobs');
122 1;
124
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
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 $beer->to_field($col, $how, $args);
139 $beer->to_field($col, $args);
140 Not all _to_* methods pay attention to all arguments. For example,
142 '_to_textfield' does not look in $args->{'items'} at all.
143 name -- the name the element will have , this trumps the derived name.
145 $beer->to_field('brewery', 'readonly', {
146 name => 'brewery_id'
147 });
148 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 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 # Rate a beer
160 $beer->to_field(rating => select => {
161 items => [1 , 2, 3, 4, 5],
162 });
163 # Select a Brewery to visit in the UK
165 Brewery->to_field(brewery_id => {
166 items => [ Brewery->search_like(location => 'UK') ],
167 });
168 # Make a select for a boolean field
170 $Pub->to_field('open' , { items => [ {'Open' => 1, 'Closed' => 0 } ] });
171 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 Can be an simple scalar id, an object, or an array of either
179 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 column_type -- a string representing column type
189 $pub->to_field('open', 'bool_select', {
190 column_type => "bool('Closed', 'Open'),
191 });
192 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 $beer->to_field('brewery', { column_nullable => 1 });
200 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 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 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 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 to_cgi
229 $self->to_cgi([@columns, $args]);
230 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 $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 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 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 search_inputs
264 my $cgi = $class->search_inputs ([$args]); # optional $args
265 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 Example:
276 sub BeerDB::Beer::search_columns { return ( 'name' , 'rating',
277 { brewery => [ 'name', 'location'] } );
278 }
279 # 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 unselect_element
284 unselect any selected elements in a HTML::Element select list widget
285 _field_from_how($field, $how,$args)
287 Returns an input element based the "how" parameter or nothing at all.
288 Override at will.
289 _field_from_relationship($field, $args)
291 Returns an input based on the relationship associated with the field or
292 nothing. Override at will.
293 For has_a it will give select box
295 _field_from_column($field, $args)
297 Returns an input based on the column's characteristics, namely type, or
298 nothing. Override at will.
299 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 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 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 3. If you already have a list of objects to select from --
329 BeerDB:;Beer->to_field($col, 'select' , {items => $objects});
330 # 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 _to_enum_select
337 Returns a select box for the an enum column type.
338 _to_bool_select
340 Returns a "No/Yes" select box for a boolean column type.
341 _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 _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 _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 Arguments this recognizes are :
360 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 _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 Currently this method handles the following formats for the "selected"
373 argument and in the following ways
374 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 _select_guts
382 Internal api method to make the actual select box form elements. the
383 data.
384 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 _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 *Note only single primary keys supported
398 _to_checkbox
400 Makes a checkbox element -- TODO
401 _to_radio
403 Makes a radio button element -- TODO
404 _rename_foreign_input
406 _rename_foreign_input($html_el_or_hash_of_them); # changes made by
407 reference
408 Recursively renames the foreign inputs made by _to_foreign_inputs so
410 they can be processed generically. It uses foreign_input_delimiter.
411 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 Employee->to_field("person");
416 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 person__AF__address__AF__street
421 person__AF__address__AF__city
422 person__AF__address__AF__state
423 person__AF__address__AF__zip
424 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 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 _box($value)
436 This functions computes the dimensions of a textarea based on the value
437 or the defaults.
438
440 1.0 15-07-2004 -- Initial version =head1 MAINTAINER
441 Maypole Developers
443
445 Peter Speltz, Aaron Trevena
446
448 Simon Cozens, Tony Bowden
449
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
459 Please direct all correspondence regarding this module to:
460 Maypole list.
461
463 Copyright 2003-2004 by Simon Cozens / Tony Bowden
464 This library is free software; you can redistribute it and/or modify it
466 under the same terms as Perl itself.
467
469 Class::DBI, Class::DBI::FromCGI, HTML::Element.
470perl v5.38.0 2023-07-20 Maypole::Model::CDBI::AsForm(3)