Class: Kiss::Form

Inherits:
Object show all
Defined in:
lib/kiss/form.rb,
lib/kiss/form/field.rb

Defined Under Namespace

Classes: BooleanField, CheckboxField, Column, Field, FileField, HiddenField, MultiChoiceField, MultiSelectField, MultiValueField, PasswordField, RadioField, RangeField, Section, SelectField, SubmitField, TextAreaField, TextField

Constant Summary collapse

COMPONENT_TYPES =

Component type symbols used to create form definition DSL

{
  :text => TextField,
  :hidden => HiddenField,
  :textarea => TextAreaField,
  :password => PasswordField,
  :boolean => BooleanField,
  :range => RangeField,
  :file => FileField,
  :select => SelectField,
  :radio => RadioField,
  :checkbox => CheckboxField,
  :multiselect => MultiSelectField,
  :submit => SubmitField
}

Instance Method Summary collapse

Constructor Details

#initialize(*args, &block) ⇒ Form

Creates a new form object with specified attributes.



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/kiss/form.rb', line 163

def initialize(*args, &block)
  @_attrs = args.to_attrs
  _instance_variables_set_from_attrs(@_attrs)

  @_method ||= 'post'
  
  @_sections = [Section.new(self)]
  @_current_section = @_sections.first
  @_current_column = @_current_section.columns.first
  
  @_components = []
  @_fields = Hashay.new
  @_attach_field_errors = false
  @_has_field_errors = false
  @_object_fields = {}
  @_default_values ||= {}
  @_params = {}
  @_with = nil
  @_field_name_prefix = ''
  @_objects_add_order = []
  @_objects_save_order = []
  @_new_object_index = -1
  @_object_fields = {}
  @_unique = []
  
  @_prepend_html = ''
  @_append_html = ''
  
  (@_attrs[:fields] || []).each do |field|
    # create field here
    add_field(field)
  end
  
	@_errors = []
	@_field_errors = {}
	
  import_instance_variables(@_delegate) if @_delegate
  
  instance_eval(&block) if block_given?
  
  raise "form name required" unless @_name
  raise "form delegate required" unless @_delegate
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) ⇒ Object 



150
151
152
 
# File 'lib/kiss/form.rb', line 150

def method_missing(method, *args, &block)
  delegate.send method, *args, &block
end

Instance Method Details

#accepted? ⇒ Boolean Also known as: accepted

Returns true if user submitted form with non-cancel submit button (non-nil submit param, not equal to cancel submit button value).

Returns:

  • (Boolean) 


535
536
537
538
 
# File 'lib/kiss/form.rb', line 535

def accepted?
  raise 'form missing submit field' unless @_submit
  return params[@_submit.name] != @_submit.cancel
end

#add_component(type, name, *args, &block) ⇒ Object 



137
138
139
140
141
142
143
144
 
# File 'lib/kiss/form.rb', line 137

def add_component(type, name, *args, &block)
  attrs = args.to_attrs
  add_field({
    :type => type,
    :name => name,
    :attach_errors => @_attach_field_errors
  }.merge(attrs), &block)
end

#add_error(*args) ⇒ Object

Add error message to be rendered with form. If multiple args given, first arg is field name, and second arg (error message) will render next to specified field.



315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/kiss/form.rb', line 315

def add_error(*args)
  case args.size
  when 0
    raise 'at least one argument required'
  when 1
    arg = args.first
    if arg.is_a?(Hash)
      field = arg.field || arg.field_name
      message = arg.message
    else
      @_errors << arg
      return
    end
  when 2
    field, message = args
  else
    raise 'too many arguments'
  end
  
  field = @_fields[field] if field.is_a?(String)
  field.add_error(message)
end

#add_field(attrs = {}, &block) ⇒ Object Also known as: create_field

Creates and adds a field to the form, according to specified attributes.



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/kiss/form.rb', line 229

def add_field(attrs = {}, &block)
  attrs = @_with.merge(attrs) if @_with
  name = attrs[:name].to_s
  key = (attrs[:key] || name).to_sym
  
  name = @_field_name_prefix + name unless @_field_name_prefix.empty?
  
  type = attrs[:type] ? attrs[:type].to_sym : :text
  raise "invalid field type '#{type}'" unless COMPONENT_TYPES.has_key?(type)
  
  field = COMPONENT_TYPES[type].new(self, attrs.merge(
    :name => name,
    :key => key
  ), &block)
  
  field.object = @_object if @_object && !field.object
  obj = field.object
  # must hash @_object_fields by Ruby object id; if by object, weird lookup errors result,
  # even when lookup object has same Ruby object id as the hash key object!
  ruby_obj_id = obj.object_id
  unless @_object_fields[ruby_obj_id]
    @_object_fields[ruby_obj_id] = {}
    @_objects_add_order << object
  end
  if @_object_fields[ruby_obj_id][field.name]
    raise "duplicate form field name '#{attrs[:name]}'#{" on #{obj.class.name} object" if obj}"
  end
  @_object_fields[ruby_obj_id][field.name] = field
  
  @_fields[name] = field
  @_components << field
  @_current_column.components << field
  
  @_enctype = 'multipart/form-data' if field.is_a?(FileField)
  
  field
end

#closing_html ⇒ Object Also known as: html_close

Renders end of form (form close tag).



783
784
785
 
# File 'lib/kiss/form.rb', line 783

def closing_html
  '</div></form>' + @_append_html
end

#column_break ⇒ Object 



217
218
219
220
 
# File 'lib/kiss/form.rb', line 217

def column_break
  @_current_column = Column.new(self)
  @_current_section.columns << @_current_column
end

#context ⇒ Object 



207
208
209
210
211
212
213
214
215
 
# File 'lib/kiss/form.rb', line 207

def context
  @_context ||= begin
    @_timezone ||= (fields['timezone'] && (params['timezone'] || (object && object[:timezone]))) || nil
    {
      :timezone => @_timezone,
      :year => @_year
    }
  end
end

#debug(*args) ⇒ Object 



146
147
148
 
# File 'lib/kiss/form.rb', line 146

def debug(*args)
  @_delegate.request.debug(args.first, Kernel.caller[0])
end

#errors_html ⇒ Object

Renders error HTML block for top of form, and returns as string.



547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
 
# File 'lib/kiss/form.rb', line 547

def errors_html
  return nil unless has_errors?
  
  @_errors << "Please correct the #{@_errors.empty? ? '' : 'other '}errors highlighted below." if @_has_field_errors
  
  if @_errors.size == 1
    content = @_errors[0]
  else
    content = "<ul>" + @_errors.map {|e| "<li>#{e}</li>"}.join + "</ul>"
  end
  
  @_errors.pop if @_has_field_errors
  
  plural = @_errors.size > 1 || @_has_field_errors ? 's' : nil
  %Q(<table class="kiss_form_errors"><tr><td>#{content}</td></tr></table>)
end

#field(name) ⇒ Object 



294
295
296
 
# File 'lib/kiss/form.rb', line 294

def field(name)
  @_fields[name]
end

#form_name_hidden_tag_html ⇒ Object 



564
565
566
 
# File 'lib/kiss/form.rb', line 564

def form_name_hidden_tag_html
  %Q(<input type=hidden name="form" value="#{@_name}">)
end

#has_errors? ⇒ Boolean

Returns true if form has errors.

Returns:

  • (Boolean) 


524
525
526
 
# File 'lib/kiss/form.rb', line 524

def has_errors?
  (@_errors.size > 0 || @_has_field_errors)
end

#html ⇒ Object

Renders complete form HTML.



789
790
791
 
# File 'lib/kiss/form.rb', line 789

def html
  [opening_html, table_html, closing_html].join
end

#object(obj = nil, options = {}, &block) ⇒ Object 



488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
 
# File 'lib/kiss/form.rb', line 488

def object(obj = nil, options = {}, &block)
  if block_given?
    raise 'missing object arg' unless obj
    
    if obj.is_a?(Symbol)
      parent = @_object
      raise 'missing parent object for object symbol reference' unless parent
      obj = parent.send(obj) #||
        #parent.set_associated_object(parent.class.association_reflection(object).associated_class.new)
    end
    raise 'object parameter must reference a model object' unless obj.is_a?(Kiss::Model)
    
    # if new, save early to give object a primary key, needed to save assoc children
    @_objects_save_order << obj if obj.new?
    prefix = options[:prefix]
    
    old_obj = @_object
    old_prefix = @_field_name_prefix
    
    @_object = obj
    @_field_name_prefix = (@_field_name_prefix + prefix.to_s + '.') if prefix
    instance_eval(&block)
    @_object = old_obj
    @_field_name_prefix = old_prefix
    
    # save again to pick up any assoc ids from children
    @_objects_save_order << obj
    obj
  elsif obj
    @_object = obj
  else
    @_object
  end
end

#object_field(obj, name) ⇒ Object 



298
299
300
 
# File 'lib/kiss/form.rb', line 298

def object_field(obj, name)
  @_object_fields[obj.object_id][name.to_s]
end

#opening_html ⇒ Object Also known as: html_open

Renders beginning of form (form open tag and form/field/error styles).



755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
 
# File 'lib/kiss/form.rb', line 755

def opening_html
  @_error_class ||= 'kiss_form_error_message'
  @_field_error_class ||= @_error_class
  
  # form tag
  form_attrs = ['id', 'method', 'enctype', 'class', 'style'].map do |attr|
    next if (value = send attr).blank?
    "#{attr}=\"#{send attr}\""
  end
  if @_html
    @_html.each_pair do |k, v|
      form_attrs.push("#{k}=\"#{v}\"")
    end
  end
  form_tag = %Q(<form action="#{@_action}" #{form_attrs.join(' ')}>#{form_name_hidden_tag_html})
  
  # combine
  [
    style_html,
    @_prepend_html,
    form_tag,
    '<div class="kiss_form">',
    errors_html
  ].join
end

#process(*objs) ⇒ Object

Checks whether form was submitted and accepted by user and, if so, whether form validates. If form validates, saves form values to form’s Sequel::Model object and returns true. Otherwise, returns false.



411
412
413
414
415
416
417
418
419
420
421
422
 
# File 'lib/kiss/form.rb', line 411

def process(*objs)
  return false unless submitted
  
  if accepted
    validate
    return false if has_errors?
  
    save(*objs)
  end
 
	return true
end

#process_or_render ⇒ Object 



424
425
426
 
# File 'lib/kiss/form.rb', line 424

def process_or_render
  self.render unless self.process
end

#render(options = {}) ⇒ Object

Renders current action using form’s HTML as action render content.



542
543
544
 
# File 'lib/kiss/form.rb', line 542

def render(options = {})
  @_delegate.render options.merge(:content => html)
end

#require_values(*names) ⇒ Object 



472
473
474
 
# File 'lib/kiss/form.rb', line 472

def require_values(*names)
  names.each {|name| fields[name.to_s].require_value }
end

#required_legend_html ⇒ Object 



577
578
579
580
 
# File 'lib/kiss/form.rb', line 577

def required_legend_html
  (@_has_required_fields && @_mark_required) ?
    %Q( <tr><td class="kiss_form_help">Required fields marked by <span class="kiss_form_required">*</span></td></tr> ) : ''
end

#reset ⇒ Object 



289
290
291
292
 
# File 'lib/kiss/form.rb', line 289

def reset
  @_params = {}
	@_fields.each {|field| field.reset }
end

#save(*args) ⇒ Object

Saves form input data associated with specified objects, or all form objects if objects are not specified here.



463
464
465
466
467
468
469
470
 
# File 'lib/kiss/form.rb', line 463

def save(*args)
  db.transaction do
    extract_objects_from_args(args).each do |obj|
      set_object_data(obj)
      obj.save
    end
  end
end

#section_break ⇒ Object 



222
223
224
225
226
 
# File 'lib/kiss/form.rb', line 222

def section_break
  @_current_section = Section.new(self)
  @_current_column = @_current_section.columns.first
  @_sections << @_current_section
end

#sections_html ⇒ Object Also known as: components_html, fields_html

Renders HTML for form sections.



569
570
571
572
573
 
# File 'lib/kiss/form.rb', line 569

def sections_html
  sections.map do |section|
    section.html
  end.join
end

#set_object_data(obj = @_object) ⇒ Object 



441
442
443
444
445
446
447
448
449
450
451
452
 
# File 'lib/kiss/form.rb', line 441

def set_object_data(obj = @_object)
  @_object_fields[obj.object_id].values.each do |field|
		# skip fields whose name starts with underscore
    next if field.name =~ /\A\_/
		# skip fields with save == false
    next unless field.save
    # skip file fields
    next if field.is_a?(FileField)
    
    field.set_value_to_object(obj)
  end
end

#set_objects_data(*args) ⇒ Object 



454
455
456
457
458
459
 
# File 'lib/kiss/form.rb', line 454

def set_objects_data(*args)
  extract_objects_from_args(args).each do |obj|
    next unless obj
    set_object_data(obj)
  end
end

#style_html ⇒ Object 



619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
 
# File 'lib/kiss/form.rb', line 619

def style_html
  styles = []
  styles << <<-EOT
table.kiss_form {
  border: 0;
  border-collapse: collapse;
  margin-right: -12px;
}
table.kiss_form > tbody > tr > td {
  padding: 0;
}

table.kiss_form_section {
  border: 0;
  border-collapse: collapse;
}
table.kiss_form_section > tbody > tr > td {
  padding: 0 12px 0 0;
}

td.kiss_form_column {
  vertical-align: top;
}
table.kiss_form_column {
  margin-bottom: 6px;
}
table.kiss_form_column > tbody > tr > td {
  padding: 2px 6px 2px 0;
  vertical-align: middle;
}
.kiss_form_errors {
  margin-bottom: 4px;
}
.kiss_form_errors td {
  background-color: #ff8;
  padding: 2px 4px;
  line-height: 135%;
  color: #900;
  border: 1px solid #db4;
}
.kiss_form_errors td ul {
  padding-left: 16px;
  margin: 0;
}
.kiss_form .kiss_form_help {
  padding-bottom: 4px;
  font-size: 90%;
  color: #555;
}
.kiss_form_required {
  color: #a21;
  font-size: 150%;
  line-height: 50%;
  position: relative;
  top: 4px;
}
.kiss_form_column td.kiss_form_label {
  text-align: right;
  white-space: nowrap;
}
.kiss_form_column td.kiss_form_label.error {
  color: #b10;
}
.kiss_form_column tr.kiss_form_prompt td {
  padding: 8px 3px 0px 4px;
}
.kiss_form_column input[type="text"],
.kiss_form_column input[type=password],
.kiss_form_column textarea {
  width: 250px;
  margin-left: 0;
  margin-right: 0;
}
.kiss_form_column table.kiss_form_field_columns {
  border-spacing: 0;
  border-collapse: collapse;
  width: 100%;
}
.kiss_form_column table.kiss_form_field_columns td {
  padding: 0 16px 2px 0;
  vertical-align: top;
}
.kiss_form_column .kiss_form_checkbox .kiss_form_label {
  vertical-align: top;
  padding-top: 3px;
}
.kiss_form_column .kiss_form_radio .kiss_form_label {
  vertical-align: top;
  padding-top: 4px;
}
.kiss_form_column .kiss_form_textarea .kiss_form_label {
  vertical-align: top;
  padding-top: 3px;
}
.kiss_form tr.kiss_form_submit td {
  padding: 0 6px 0 0;
  text-align: center;
}
EOT
  
  if @_error_class == 'kiss_form_error_message'
    styles << <<-EOT
.kiss_form_error_message {
  padding: 1px 4px;
  border: 1px solid #db4;
  background-color: #ff8;
  color: #900;
  font-size: 90%;
  line-height: 135%;
  display: block;
  float: left;
  width: 246px;
  margin-bottom: 2px;
}
.kiss_form_error_message div {
  color: #c00;
  font-weight: bold;
}
.kiss_form_error_message ul {
  padding-left: 16px;
  margin: 0;
}
tr.kiss_form_error_row td {
  padding-top: 0;
}
tr.kiss_form_error_row .kiss_form_error_message {
  position: relative;
  top: -2px;
  margin-bottom: 0;
}
EOT
  end
  styles.empty? ? '' : ["<style>", styles, "</style>"].flatten.join
end

#submit(*args, &block) ⇒ Object Also known as: add_submit

Creates and adds set of submit buttons to the form, per specified attributes.



269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/kiss/form.rb', line 269

def submit(*args, &block)
  if args.size > 0
    raise 'submit already defined' if @_submit
    
    attrs = {
      :type => :submit,
      :name => 'submit',
      :save => false,
      :cancel => 'Cancel'
    }
    attrs.merge!(args.pop) if args.last.is_a?(Hash)
    attrs[:options] = args if args.size > 0
    attrs = @_with.merge(attrs) if @_with
    @_submit = COMPONENT_TYPES[:submit].new(self, attrs, &block)
  else
    @_submit
  end
end

#submit_html ⇒ Object

Renders form submit buttons.



583
584
585
586
587
588
589
590
591
592
593
594
595
 
# File 'lib/kiss/form.rb', line 583

def submit_html
  if @_submit
    prompt = @_submit.prompt ? (@_submit.prompt + '<br/>') : ''
    [
      '<tr class="kiss_form_submit"><td>',
      prompt,
      @_submit.element_html,
      '<br/></td></tr>'
    ].join
  else
    ''
  end
end

#submitted? ⇒ Boolean

Returns true if user submitted form in this request.

Returns:

  • (Boolean) 


529
530
531
 
# File 'lib/kiss/form.rb', line 529

def submitted?
  @_submitted
end

#table_closing_html ⇒ Object Also known as: table_html_close

Renders close of form table.



604
605
606
 
# File 'lib/kiss/form.rb', line 604

def table_closing_html
  '</tbody></table>'
end

#table_html ⇒ Object 



609
610
611
612
613
614
615
616
617
 
# File 'lib/kiss/form.rb', line 609

def table_html
  [
    table_opening_html,
    required_legend_html,
    sections_html,
    submit_html,
    table_closing_html
  ].flatten.join
end

#table_opening_html ⇒ Object Also known as: table_html_open

Renders open of form table.



598
599
600
 
# File 'lib/kiss/form.rb', line 598

def table_opening_html
  %Q(<table class="kiss_form" border=0 cellspacing=0><tbody>)
end

#unique(*val) ⇒ Object 



154
155
156
157
158
159
160
 
# File 'lib/kiss/form.rb', line 154

def unique(*val)
  if val.empty?
    @_unique
  else
    @_unique << val
  end
end

#validate ⇒ Object

Validates form values against fields’ format and required attributes, and returns values unless form has errors.



340
341
342
343
344
345
346
347
 
# File 'lib/kiss/form.rb', line 340

def validate
  return nil unless submitted
  
	@_fields.each {|field| field.validate }
	@_unique.each {|field_set| validate_uniqueness_of(field_set) }
 
 has_errors? ? nil : values
end

#validate_uniqueness_of(column_set) ⇒ Object 



349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/kiss/form.rb', line 349

def validate_uniqueness_of(column_set)
  conditions = column_set.last.is_a?(Hash) ? column_set.pop : {}
  
  nouns = []
  true_adjectives = []
  false_adjectives = []
  
  column_set.each do |column_name|
    key = column_name.to_sym
    column_name = column_name.to_s
    
    field = fields[column_name]
    label, value = field ?
      [field.label.downcase, field.value] : 
      [column_name.sub(/_id\Z/, '').downcase, object[column_name.to_sym]]
    conditions[key] = value
    
    if column_name =~ /\Ais_/ || column_name =~ /_at\Z/
      if value.zero? || value.nil?
        false_adjectives
      else
        true_adjectives
      end
    else
      nouns
    end << label
  end
  
  dataset = @_object.model.filter(conditions)
  dataset = dataset.exclude(@_object.pk_hash) unless @_object.new?
  return nil if dataset.empty?
  
  true_adjective_string = true_adjectives.empty? ? '' :
    (true_adjectives.join(', ') + ' ')
  humanized_object_class_name = @_object.model.name.singularize.gsub('_', ' ')
  false_adjective_string = false_adjectives.empty? ? '' : 
    ", not #{false_adjectives.conjoin('or')},"
  with_clause = nouns.empty? ? '' : " with the same #{nouns.conjoin}"
  message = [
    'There is already another ',
    true_adjective_string,
    humanized_object_class_name,
    false_adjective_string,
    with_clause,
    '.'
  ].join
  
  # Add error to a single field if appropriate.
  if column_set.length == 1
    field_name = column_set[0].to_str
    if field_name && fields[field_name]
      return add_error(field_name, message)
    end
  end
  # Else add to top of form.
  return add_error(message)
end

#values ⇒ Object

Gets hash of form values.



303
304
305
306
307
308
309
310
 
# File 'lib/kiss/form.rb', line 303

def values
  @_values ||= begin
    hash = {}
    @_fields.each {|field| field.set_value_to_hash(hash) }
    hash['submit'] = @_submit.value = params[@_submit.name]
    hash
  end
end

#with(*args, &block) ⇒ Object 



476
477
478
479
480
481
482
483
484
485
486
 
# File 'lib/kiss/form.rb', line 476

def with(*args, &block)
  if block_given?
    attrs = args.to_attrs
    old_with = @_with
    @_with = (@_with || {}).merge(attrs)
  
    instance_eval(&block)
    
    @_with = old_with
  end
end