form_input 0.9.0.pre1

data/Rakefile

@@ -0,0 +1,19 @@
+# Rake makefile.
+
+require 'rake/testtask'
+
+task :default => :test
+
+desc 'Run tests'
+task :test do
+  sh "bacon --automatic --quiet"
+end
+
+desc 'Run tests with coverage'
+task :cov do
+  sh "rm -rf coverage"
+  ENV['COVERAGE'] = 'on'
+  Rake::Task[:test].execute
+end
+
+# EOF #

data/example/controllers/ramaze/press_release.rb

@@ -0,0 +1,104 @@
+# The press release controller - example of a complex multistep form handling in Ramaze.
+
+class PRController < Controller
+
+  # Create press release.
+  def create
+
+    # Start with fresh form.
+
+    unless request.post?
+      @form = PressReleaseForm.new(
+        user.active_plan,
+        date: Time.now,
+        city: user.profile.city,
+        state: user.profile.state,
+        country: user.profile.country,
+        contact_name: user.full_name,
+        contact_organization: user.profile.company,
+        contact_phone: user.profile.phone,
+        contact_email: user.email,
+      )
+      return
+    end
+
+    # Process the data from the post.
+
+    @form = PressReleaseForm.new( user.active_plan, request )
+    return unless process_form( @form )
+
+    # Save the press release.
+
+    unless user.create_press_release( @form )
+      @form.step = :summary
+      @state = :create_failed
+      return
+    end
+
+    redirect r
+  end
+
+  # Edit press release.
+  def edit( hid )
+
+    # Fetch the existing press release.
+    # Note that it can be edited by admins in addition to its owner.
+
+    not_found unless pr = PressRelease.from_hid( hid )
+
+    owner = ( pr.user_id == user.id )
+    forbidden unless owner or user.admin?
+
+    # Start by filling the form from the press release.
+
+    unless request.post?
+      @form = PressReleaseForm.new( pr.user.active_plan, pr.form_hash ).unlock_steps
+      return
+    end
+
+    # Process the data from the post.
+
+    pr = get_press_release( hid )
+    @form = PressReleaseForm.new( pr.user.active_plan, request )
+    return unless process_form( @form )
+
+    # Update the press release.
+
+    unless pr.user.update_press_release( pr, @form, user )
+      @form.step = :summary
+      @state = :update_failed
+      return
+    end
+
+    redirect owner ? r : AdminController.r( :press_releases )
+  end
+
+  alias_view :edit, :create
+
+  # Common logic for processing the form steps.
+  def process_form( form )
+
+    # Report errors whenever there are some in the currently finished step.
+
+    @state = :report if form.incomplete_step?
+
+    # That's all until the last steps are reached.
+
+    return if form.step_before?( :summary )
+
+    # In case the form is still invalid, return to the appropriate step.
+
+    unless form.valid?
+      form.step = form.incorrect_step
+      @state = :report
+      return
+    end
+
+    # That's all until the last step is reached.
+
+    return form.last_step?
+  end
+
+end
+
+# EOF #

data/example/controllers/ramaze/profile.rb

@@ -0,0 +1,38 @@
+# Example of simple form handling in Ramaze.
+
+class HomeController < Controller
+
+  # Profile.
+  def profile
+
+    # Prefill the form with current user profile.
+
+    unless request.post?
+      @form = ProfileForm.new( user.profile_hash )
+      return
+    end
+
+    # Check new data when the form is posted.
+
+    @form = ProfileForm.new( request )
+    unless @form.valid?
+      @state = :report
+      return
+    end
+
+    # Attempt to update the profile.
+
+    unless user.update_profile( @form )
+      @state = :update_failed
+      return
+    end
+
+    # Refetch the profile just in case the model changed something, and report success.
+
+    @form = ProfileForm.new( user.profile_hash )
+    @state = :done
+  end
+
+end
+
+# EOF #

data/example/controllers/sinatra/press_release.rb

@@ -0,0 +1,114 @@
+# The press release controller - example of a complex multistep form handling in Sinatra.
+
+class App < Sinatra::Base
+
+  # Create press release - start.
+  get '/pr/create' do
+
+    # Start with fresh form, prefilled with some user info.
+
+    @form = PressReleaseForm.new(
+      user.active_plan,
+      date: Time.now,
+      city: user.profile.city,
+      state: user.profile.state,
+      country: user.profile.country,
+      contact_name: user.full_name,
+      contact_organization: user.profile.company,
+      contact_phone: user.profile.phone,
+      contact_email: user.email,
+    )
+    slim :press_release
+  end
+
+  # Create press release - creation.
+  post '/pr/create' do
+
+    # Process the data from the post.
+
+    @form = PressReleaseForm.new( user.active_plan, request )
+    unless process_form( @form )
+      return slim :press_release
+    end
+
+    # Save the press release.
+
+    unless user.create_press_release( @form )
+      @form.step = :summary
+      @state = :create_failed
+      return slim :press_release
+    end
+
+    redirect '/'
+  end
+
+  # Edit press release - start.
+  get '/pr/edit/:hid' do |hid|
+
+    # Fetch the existing press release.
+    # Note that it can be edited by admins in addition to its owner.
+
+    pr = get_press_release( hid )
+    @form = PressReleaseForm.new( pr.user.active_plan, pr.form_hash ).unlock_steps
+    slim :press_release
+  end
+
+  # Edit press release - update.
+  post '/pr/edit/:hid' do |hid|
+
+    # Process the data from the post.
+
+    pr = get_press_release( hid )
+    @form = PressReleaseForm.new( pr.user.active_plan, request )
+    unless process_form( @form )
+      return slim :press_release
+    end
+
+    # Update the press release.
+
+    unless pr.user.update_press_release( pr, @form, user )
+      @form.step = :summary
+      @state = :update_failed
+      return slim :press_release
+    end
+
+    redirect '/'
+  end
+
+  # Get the press release for given hashed id.
+  def get_press_release( hid )
+    not_found unless pr = PressRelease.from_hid( hid )
+
+    owner = ( pr.user_id == user.id )
+    forbidden unless owner or user.admin?
+
+    pr
+  end
+
+  # Common logic for processing the form steps.
+  def process_form( form )
+
+    # Report errors whenever there are some in the currently finished step.
+
+    @state = :report if form.incomplete_step?
+
+    # That's all until the last steps are reached.
+
+    return if form.step_before?( :summary )
+
+    # In case the form is still invalid, return to the appropriate step.
+
+    unless form.valid?
+      form.step = form.incorrect_step
+      @state = :report
+      return
+    end
+
+    # That's all until the last step is reached.
+
+    return form.last_step?
+  end
+
+end
+
+# EOF #

data/example/controllers/sinatra/profile.rb

@@ -0,0 +1,39 @@
+# Example of simple form handling in Sinatra.
+
+class App < Sinatra::Application
+
+  get '/profile' do
+
+    # Prefill the form with current user profile.
+
+    @form = ProfileForm.new( user.profile_hash )
+    slim :profile
+  end
+
+  post '/profile' do
+
+    # Validate the posted data.
+
+    @form = ProfileForm.new( request )
+    unless @form.valid?
+      @state = :report
+      return slim :profile
+    end
+
+    # Attempt to update the profile.
+
+    unless user.update_profile( @form )
+      @state = :update_failed
+      return slim :profile
+    end
+
+    # Refetch the profile just in case the model changed something, and report success.
+
+    @form = ProfileForm.new( user.profile_hash )
+    @state = :done
+    slim :profile
+  end
+
+end
+
+# EOF #

data/example/forms/change_password_form.rb

@@ -0,0 +1,17 @@
+# Change password form.
+
+require_relative 'new_password_form'
+
+class ChangePasswordForm < FormInput
+
+  # Note that we intentionally don't impose any format on this,
+  # as we don't want to assume what they have registered with.
+  # Only strip the password newline in case they cut&paste it from somewhere.
+
+  param! :old_password, "Old password", type: :password, filter: ->{ chomp }
+
+  copy NewPasswordForm
+
+end
+
+# EOF #

data/example/forms/login_form.rb

@@ -0,0 +1,14 @@
+# Login form.
+
+class LoginForm < FormInput
+
+  # Note that we intentionally don't impose any format of these,
+  # as we don't want to assume what they have registered with.
+  # Only strip the password newline in case they cut&paste it from somewhere.
+
+  param! :login, :email, "Email"
+  param! :password, "Password", type: :password, filter: ->{ chomp }
+
+end
+
+# EOF #

data/example/forms/lost_password_form.rb

@@ -0,0 +1,14 @@
+# Lost password form.
+
+class LostPasswordForm < FormInput
+
+  # Note that we intentionally don't impose any format of the email,
+  # as we don't want to assume what they have registered with.
+  # We will let them know in case we don't find it anyway.
+  # We merely check if it looks like an email at all.
+
+  param! :email, "Email", match: /@/
+
+end
+
+# EOF #

data/example/forms/new_password_form.rb

@@ -0,0 +1,15 @@
+# New password form.
+
+require_relative 'password_form'
+
+class NewPasswordForm < FormInput
+
+  copy PasswordForm, title: "New password"
+
+  param! :password_check, "Repeated password", type: :password,
+    filter: self[ :password ].filter,
+    check: ->{ report( "%p must match password" ) unless value == form.password }
+
+end
+
+# EOF #

data/example/forms/password_form.rb

@@ -0,0 +1,18 @@
+# Password form.
+
+# Separate form with only the password parameter to make it easy to include it wherever necessary.
+class PasswordForm < FormInput
+
+  # Enforce size and format of the password.
+  # Note that we strip the password newline in case they cut&paste it from somewhere.
+
+  param! :password, "Password", type: :password, min_size: 6,
+    reject: /\P{ASCII}|[\t\r\n]/u,
+    reject_msg: "%p may contain only ASCII characters and spaces",
+    match: [ /[a-z]/i, /\d/ ],
+    msg: "%p must contain at least one digit and one letter",
+    filter: ->{ chomp }
+
+end
+
+# EOF #

data/example/forms/press_release_form.rb

@@ -0,0 +1,153 @@
+# Press Release Form - example of a complex multistep form.
+
+class PressReleaseForm < FormInput
+
+  ### Parameters ###
+
+  # Pricing plan we use for evaluating things.
+
+  attr_reader :plan
+
+  # Creation process steps.
+
+  define_steps(
+    content: "Content",
+    date: "Date",
+    location: "Location",
+    contact: "Contact",
+    keywords: "Keywords",
+    quote: "Quote",
+    images: "Images",
+    videos: "Videos",
+    website: "Web Site",
+    release: "Release Date",
+    channels: "Channels",
+    summary: "Summary",
+    post: nil,
+  )
+
+  # Press release itself.
+
+  param! :title, "Title", 120, tag: :content,
+    subtitle: "(Maximum 120 characters, recommended max 80 characters)",
+    help: "The main title of your press release. It should be brief, clear and to the point."
+  param :subtitle, "Subtitle", 160, tag: :content,
+    subtitle: "(Maximum 160 characters)",
+    help: "Optional but recommended. If used, make sure it's descriptive and builds on the headline."
+  param! :text, "Text", 65000, max_bytesize: 65535, type: :textarea, size: 16, tag: :content,
+    subtitle: ->{ "(Maximum #{plural( form.limit( :words ), 'word' )})" },
+    filter: ->{ strip },
+    check: ->{
+      count = form.feature_count( :words, value )
+      limit = form.limit( :words )
+      report "Your text has #{plural( count, 'word' )}, but the limit is #{delimited( limit )}." if count > limit
+    }
+
+  # Date.
+
+  param! :date, "Date", DATE_ARGS, tag: :date
+
+  # Location.
+
+  param! :city, "City", 100, tag: :location
+  param :state, "State", STATE_ARGS, tag: :location
+  param! :country, "Country", COUNTRY_ARGS, tag: :location
+
+  # Contact info.
+
+  param! :contact_name, "Full Name", 60, tag: :contact
+  param! :contact_organization, "Organization Name", 60, tag: :contact
+  param! :contact_phone, "Phone", 30, PHONE_ARGS, tag: :contact
+  param! :contact_email, "Email Address", 60, EMAIL_ARGS, tag: :contact
+
+  # Keywords.
+
+  array :keywords, "Keywords", 35, PRUNED_ARGS, tag: :keywords,
+    row: :keywords, cols: 5,
+    max_count: ->{ form.limit( :keywords ) }
+  array :keywords_urls, "Keywords URL", PRUNED_ARGS, WEB_URL_ARGS, max_count: 30, tag: :keywords,
+    row: :keywords, cols: 7,
+    max_count: ->{ form.limit( :keywords ) }
+
+  def balance_keywords
+    self.keywords ||= []
+    self.keywords_urls ||= []
+
+    report( :keywords, "Keywords must match the keyword URLs" ) if keywords.count < keywords_urls.count
+    report( :keywords_urls, "Keyword URLs must match the keywords" ) if keywords.count > keywords_urls.count
+
+    self.keywords << "" while keywords.count < keywords_urls.count
+    self.keywords_urls << "" while keywords.count > keywords_urls.count
+  end
+
+  # Quote.
+
+  param :quote, "Quote", 200, tag: :quote,
+    subtitle: "(Maximum 200 characters)",
+    disabled: ->{ form.disabled?( :quote ) }
+  param :quote_author, "Quote Author", 100, tag: :quote,
+    subtitle: "(Maximum 100 characters)",
+    disabled: ->{ form.disabled?( :quote ) }
+
+  # Images.
+
+  array :images, "Images", PRUNED_ARGS, tag: :images,
+    max_count: ->{ form.limit( :images ) }
+
+  # Video.
+
+  array :videos, "Videos", PRUNED_ARGS, tag: :videos,
+    max_count: ->{ form.limit( :videos ) }
+
+  # Website.
+
+  param :website_url, "URL", WEB_URL_ARGS, tag: :website,
+    disabled: ->{ form.disabled?( :website ) }
+
+  # Release date.
+
+  param :release_date, "Release Date", US_DATE_ARGS, tag: :release,
+    disabled: ->{ form.disabled?( :scheduling ) }
+  param :release_time, "Release Time", HOURS_ARGS, tag: :release,
+    disabled: ->{ form.disabled?( :scheduling ) }
+
+  # Distribution.
+
+  array! :channels, "Channels", type: :select, tag: :channels,
+    size: 25,
+    max_count: ->{ form.limit( :channels ) },
+    data: ->{ Channel.all.map{ |x| [ x.code, x.name ] } },
+    filter: ->{ self if Channel[ self ] }
+
+  ### Methods ###
+
+  # Initialize new instance.
+  def initialize( plan, *args )
+    @plan = plan
+    super( *args )
+    balance_keywords
+  end
+
+  # Get the items to show in the sidebar.
+  def sidebar_items
+    { base: 'Base Price' }.merge( step_names )
+  end
+
+  # Get limit for given feature.
+  def limit( feature )
+    plan.extra_limit( feature )
+  end
+
+  # Get count for given feature and value.
+  def feature_count( feature, value )
+    plan.feature_count( feature, value )
+  end
+
+  # Test if given feature is disabled for current plan.
+  def disabled?( feature )
+    not plan.has_feature?( feature )
+  end
+
+end
+
+# EOF #

data/example/forms/profile_form.rb

@@ -0,0 +1,21 @@
+# Profile form.
+
+require_relative 'signup_form'
+
+class ProfileForm < FormInput
+
+  copy SignupForm[ :first_name, :last_name ]
+
+  param :company, "Company"
+  param :street, "Street"
+  param :city, "City"
+  param :state, "State", STATE_ARGS
+  param :country, "Country", COUNTRY_ARGS
+  param :zip, "ZIP code", ZIP_ARGS
+  param :phone, "Phone number", PHONE_ARGS
+  param :fax, "Fax number", PHONE_ARGS
+  param :url, "URL", WEB_URL_ARGS
+
+end
+
+# EOF #

data/example/forms/signup_form.rb

@@ -0,0 +1,25 @@
+# Signup form.
+
+require_relative 'password_form'
+
+class SignupForm < FormInput
+
+  # Currently we restrict names to latin based alphabets.
+
+  param! :first_name, "First name", match: LATIN_NAMES_RE,
+    msg: "Sorry, only names using latin alphabet are allowed"
+  param! :last_name, "Last name", match: LATIN_NAMES_RE,
+    msg: "Sorry, only surnames using latin alphabet are allowed"
+
+  # Note that we only enforce relaxed format of the emails.
+  # Real problems will be found out by verification anyway.
+
+  param! :login, :email, "Email", EMAIL_ARGS
+
+  # Enforce size and format of the password the same way the standard password form does.
+
+  copy PasswordForm
+
+end
+
+# EOF #

data/example/views/press_release.slim

@@ -0,0 +1,65 @@
+// Press Release editing form - example of a complex multi-step form.
+
+- @title = "Press Release: #{@form.step_name}"
+
+- edit_mode = ( page_action == 'edit' )
+
+form *form_attrs
+
+  // Invisible first submit button to send users to the next page
+  // when they press enter in the text field.
+  button.invisible type='submit' name='next' tabindex='-1' value=@form.next_step
+
+  .row
+    .col-md-3 role='navigation'
+
+      == snippet :sidebar,
+        title: "#{edit_mode ? 'Edit' : 'Create'} Press Release",
+        items: @form.sidebar_items,
+        accessible: @form.accessible_steps,
+        valid: @form.good_steps,
+        invalid: @form.bad_steps,
+        current: @form.step
+
+    .col-md-9 role='main'
+
+      .panel.panel-default
+        .panel-heading
+          = @title
+        .panel-body
+
+          // Additional info derived from @state or @form.step will usually go here.
+
+          fieldset
+            == snippet :form_hidden,
+              params: @form.other_params
+            == snippet :form_chunked,
+              params: @form.chunked_params( @form.current_params ),
+              report: @state == :report,
+              focus: true
+
+            - unless @form.extra_step?
+              .btn-toolbar.pull-left
+                button.btn.btn-default type='submit'
+                  Update
+
+            .btn-toolbar.pull-right
+              a.btn.btn-default href=r
+                Cancel
+              - if @form.step == :summary
+                button.btn.btn-primary type='submit' name='next' value='post'
+                  Save
+              - else
+                button.btn.btn-default type='submit' name='next' value='summary'
+                  Finish
+                - unless edit_mode
+                  button.btn.btn-primary.pull-right type='submit' name='next' value=@form.next_step
+                    Next
+
+// These make it easy to debug the form if needed:
+//
+//      pre = @form.params.map{|x| [ x.name, x.value ] }.inspect
+//      pre = @form.errors.inspect
+//      pre = @state
+
+// EOF //

data/example/views/profile.slim

@@ -0,0 +1,28 @@
+// Update user profile - example of rendering simple form page.
+
+- @title = "Profile"
+
+.panel.panel-default
+  .panel-heading
+    = @title
+  .panel-body
+    form *form_attrs
+
+      - case @state
+      - when :done
+        .alert.alert-success.alert-block
+          Your profile was successfully updated.
+      - when :update_failed
+        .alert.alert-danger.alert-block
+          strong Profile update failed!
+          br
+          We apologize for such inconvenience. Please try again later.
+
+      fieldset
+        == snippet :form_panel,
+          params: @form.params,
+          report: @state == :report
+          focus: @state == :report
+        button.btn.btn-default type='submit' Update Profile
+
+// EOF //