sinatra-formkeeper 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Sinatra::FormKeeper
2
2
 
3
- TODO: Write a gem description
3
+ This module provides you a easy way for form-validation and fill-in-form on your sinatra application
4
4
 
5
5
  ## Installation
6
6
 
@@ -18,22 +18,279 @@ Or install it yourself as:
18
18
 
19
19
  ## Usage
20
20
 
21
- ### Getting Started
21
+ ### Synopsis
22
22
 
23
- require 'sinatra/formkeeper'
23
+ require 'sinatra/formkeeper'
24
24
 
25
- get '/login' do
26
- form do
27
- filters :strip, :my_filter
28
- field :username, :present => true, :length => 4..8
29
- field :password, :present => true, :length => 4..8
25
+ get '/login' do
26
+ form do
27
+ filters :strip, :my_filter
28
+ field :username, :present => true, :length => 4..8
29
+ field :password, :present => true, :length => 4..8
30
+ end
31
+ if form.failed?
32
+ "login failed"
33
+ else
34
+ "login success " + form[:username] + ":" + form[:password]
35
+ end
30
36
  end
31
- if form.failed?
32
- "login failed"
33
- else
34
- "login success " + form[:username] + ":" + form[:password]
37
+
38
+ ### 0: Preparation
39
+
40
+ At your application file's header, add 'require' line for this library.
41
+
42
+ require 'sinatra/formkeeper'
43
+
44
+ And if your application is Sinatra::Base inheritance type, register Sinatra::FormKeeper
45
+
46
+ class MyApp < Sinatra::Base
47
+ register Sinatra::FormKeeper
48
+ ...
49
+ end
50
+
51
+ ### 1: Building rules
52
+
53
+ In your routing block, you should build a form-rule at first,
54
+ like following
55
+
56
+ post '/entry' do
57
+ form do
58
+ filters :strip
59
+ field :title, :present => true, :length => 4..20
60
+ field :message, :present => true, :length => 0..200
61
+ end
62
+ ...
63
+ end
64
+
65
+ Calling 'form' with block which includes rule-setting,
66
+ you can build a form-rule.
67
+ There are some DSL-method to build rules. In this example, 'filters' and 'field' are written.
68
+
69
+ ### 2: Check if user's input is valid or not
70
+
71
+ 'form.failed?' can be used to judge if user's input is valid for the rule you build.
72
+
73
+ post '/entry' do
74
+ form do
75
+ ...
76
+ end
77
+ if form.failed?
78
+ # user's input is invalid
79
+ else
80
+ # user's input is valid!
81
+ end
82
+ end
83
+
84
+ ### 3: Pick up valid data
85
+
86
+ After validation is proccessed without any failure,
87
+ you can implement your domain logic with valid parameters.
88
+
89
+ 'form[:field_name]' can be used to pick up a valid data.
90
+ This data you can obtain through this method is a filtered data
91
+ according to the rule you build (if you set a 'filters' rule).
92
+
93
+ post '/entry' do
94
+ form do
95
+ ...
96
+ end
97
+ if form.failed?
98
+ ...
99
+ else
100
+ # do something with valid data
101
+ Database.insert( :title => form[:field], :message => form[:message] )
102
+ end
103
+ end
104
+
105
+ ### 4: Check if what field has failed?
106
+
107
+ When validation is failed, you might want to provide user
108
+ same form again, with error message that describes what fields was invalid.
109
+ For this purpose, use 'failed_on?' method.
110
+
111
+ post '/entry' do
112
+ form do
113
+ ...
114
+ end
115
+ if form.failed?
116
+ erb :entry
117
+ else
118
+ ...
119
+ end
120
+ end
121
+ __END__
122
+ @@ entry
123
+ <html>
124
+ <head><title>Entry</title></head>
125
+ <body>
126
+ <% if form.failed? %>
127
+ <% if form.failed_on?(:title) %>
128
+ <p>Title is invalid</p>
129
+ <% end %>
130
+ <% if form.failed_on?(:message) %>
131
+ <p>Message is invalid</p>
132
+ <% end %>
133
+ <% end %>
134
+ <form action="/entry" method="post">
135
+ <label>Title</label><input type="text" name="title"><br />
136
+ <label>Message</label><textarea name="message"></textarea>
137
+ <input type="submit" value="Post this entry">
138
+ </form>
139
+ </body>
140
+ </html>
141
+
142
+ ### 5: Check if what field and constraint has failed?
143
+
144
+ You can pass constraint-type to 'failed_on?' as a second argument.
145
+ This provides you a way to show detailed error-messages.
146
+
147
+ post '/entry' do
148
+ form do
149
+ ...
150
+ end
151
+ if form.failed?
152
+ erb :entry
153
+ else
154
+ ...
155
+ end
35
156
  end
36
- end
157
+ __END__
158
+ @@ entry
159
+ <html>
160
+ <head><title>Entry</title></head>
161
+ <body>
162
+ <% if form.failed? %>
163
+ <% if form.failed_on?(:title, :present) %>
164
+ <p>Title not found</p>
165
+ <% end %>
166
+ <% if form.failed_on?(:title, :length) %>
167
+ <p>Title's length is invalid </p>
168
+ <% end %>
169
+ <% if form.failed_on?(:message, :present) %>
170
+ <p>Message not found</p>
171
+ <% end %>
172
+ <% end %>
173
+ <form action="/entry" method="post">
174
+ <label>Title</label><input type="text" name="title"><br />
175
+ <label>Message</label><textarea name="message"></textarea>
176
+ <input type="submit" value="Post this entry">
177
+ </form>
178
+ </body>
179
+ </html>
180
+
181
+ ### 6: Fill in form
182
+
183
+ In many case you might want to fill in form with user's last input.
184
+ Do like following. 'fill_in_form' automatically fill the fields with 'params'
185
+
186
+ post '/entry' do
187
+ form do
188
+ ...
189
+ end
190
+ if form.failed?
191
+ output = erb :entry
192
+ fill_in_form(output)
193
+ else
194
+ ...
195
+ end
196
+ end
197
+
198
+ ### 7: Message Handling
199
+
200
+ You can aggregate a error messages into external yaml file.
201
+
202
+ --- messages.yaml
203
+ login:
204
+ username:
205
+ present: input name!
206
+ length: intput name (length should be between 0 and 10)
207
+ email:
208
+ DEFAULT: input correct email address
209
+ post_entry:
210
+ title:
211
+ present: Title not found
212
+ DEFAULT:
213
+ username:
214
+ present: username not found
215
+ ...
216
+
217
+ DEFAULT is a special type. If it can't find setting for indicated validation-type, it uses message set for DEFAULT.
218
+ After you prepare a yaml file, load it.
219
+
220
+ form_messages File.expand_path(File.join(File.dirname(__FILE__), 'config', 'form_messages.yaml'))
221
+ post '/entry' do
222
+ ...
223
+ end
224
+
225
+ You can show messages bound to indicated action-name you set in yaml.
226
+
227
+ <html>
228
+ <head><title>Entry</title></head>
229
+ <body>
230
+ <% if form.failed? %>
231
+ <ul>
232
+ <% form.messages(:post_entry).each do |message| %>
233
+ <li><%= message %></li>
234
+ <% end %>
235
+ </ul>
236
+ <% end %>
237
+ </body>
238
+ </html>
239
+
240
+ If you want to show messages for each field, separately, of course you can.
241
+
242
+ <html>
243
+ <head><title>Entry</title></head>
244
+ <body>
245
+ <form>
246
+ <% if form.failed? %>
247
+ <ul>
248
+ <% form.messages(:login, :username).each do |message| %>
249
+ <li><%= message %></li>
250
+ <% end %>
251
+ </ul>
252
+ <% end %>
253
+ <label>username</label><input type="text" name="username">
254
+ <% if form.failed? %>
255
+ <ul>
256
+ <% form.messages(:login, :password).each do |message| %>
257
+ <li><%= message %></li>
258
+ <% end %>
259
+ </ul>
260
+ <% end %>
261
+ <label>password</label><input type="text" name="password">
262
+ </body>
263
+ </html>
264
+
265
+ ### 8: Utilize Plugins
266
+
267
+ require 'formkeeper/japanese'
268
+
269
+ post '/entry' do
270
+ form do
271
+ filters :zenkaku2hankaku
272
+ end
273
+ end
274
+
275
+ ### 9: Custom Filter
276
+
277
+ form_filter :my_capitalize_filter do |value|
278
+ value.capitalize
279
+ end
280
+
281
+ post '/entry' do
282
+ form do
283
+ filters :my_capitalize_filter
284
+ end
285
+ end
286
+
287
+
288
+ ### 10: Custom Constraint
289
+
290
+ ## See Also
291
+
292
+ https://github.com/lyokato/formkeeper/
293
+ https://github.com/lyokato/formkeeper-japanese/
37
294
 
38
295
  ## Contributing
39
296
 
@@ -1,5 +1,5 @@
1
1
  module Sinatra
2
2
  module FormKeeper
3
- VERSION = "0.0.1"
3
+ VERSION = "0.0.2"
4
4
  end
5
5
  end
@@ -10,7 +10,7 @@ Gem::Specification.new do |gem|
10
10
  gem.email = ["lyo.kato@gmail.com"]
11
11
  gem.description = %q{Sinatra extension which handles stuff around HTML forms}
12
12
  gem.summary = %q{This module provides you a easy way for form-validation and fill-in-form}
13
- gem.homepage = ""
13
+ gem.homepage = "https://github.com/lyokato/sinatra-formkeeper/"
14
14
 
15
15
  gem.files = `git ls-files`.split($/)
16
16
  gem.executables = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: sinatra-formkeeper
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.1
4
+ version: 0.0.2
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -31,7 +31,7 @@ files:
31
31
  - spec/app_spec.rb
32
32
  - spec/messages.yaml
33
33
  - spec/spec_helper.rb
34
- homepage: ''
34
+ homepage: https://github.com/lyokato/sinatra-formkeeper/
35
35
  licenses: []
36
36
  post_install_message:
37
37
  rdoc_options: []