padrino-helpers 0.10.2 → 0.10.3

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.
Files changed (34) hide show
  1. data/.document +3 -3
  2. data/.yardopts +1 -0
  3. data/{LICENSE → LICENSE.txt} +0 -0
  4. data/README.rdoc +3 -3
  5. data/lib/padrino-helpers.rb +21 -14
  6. data/lib/padrino-helpers/asset_tag_helpers.rb +163 -34
  7. data/lib/padrino-helpers/form_builder/abstract_form_builder.rb +1 -1
  8. data/lib/padrino-helpers/form_helpers.rb +287 -134
  9. data/lib/padrino-helpers/format_helpers.rb +135 -17
  10. data/lib/padrino-helpers/locale/lv.yml +103 -0
  11. data/lib/padrino-helpers/locale/zh_cn.yml +1 -1
  12. data/lib/padrino-helpers/number_helpers.rb +73 -59
  13. data/lib/padrino-helpers/output_helpers.rb +59 -15
  14. data/lib/padrino-helpers/output_helpers/abstract_handler.rb +15 -20
  15. data/lib/padrino-helpers/output_helpers/erb_handler.rb +12 -15
  16. data/lib/padrino-helpers/output_helpers/haml_handler.rb +10 -14
  17. data/lib/padrino-helpers/output_helpers/slim_handler.rb +10 -14
  18. data/lib/padrino-helpers/render_helpers.rb +23 -7
  19. data/lib/padrino-helpers/tag_helpers.rb +41 -16
  20. data/lib/padrino-helpers/translation_helpers.rb +14 -0
  21. data/test/fixtures/markup_app/views/content_for.erb +3 -0
  22. data/test/fixtures/markup_app/views/content_for.haml +3 -0
  23. data/test/fixtures/markup_app/views/content_for.slim +3 -0
  24. data/test/helper.rb +3 -15
  25. data/test/test_asset_tag_helpers.rb +1 -1
  26. data/test/test_form_builder.rb +3 -5
  27. data/test/test_form_helpers.rb +1 -1
  28. data/test/test_format_helpers.rb +1 -1
  29. data/test/test_locale.rb +1 -1
  30. data/test/test_number_helpers.rb +1 -1
  31. data/test/test_output_helpers.rb +22 -2
  32. data/test/test_render_helpers.rb +1 -1
  33. data/test/test_tag_helpers.rb +1 -1
  34. metadata +10 -8
data/.document CHANGED
@@ -1,5 +1,5 @@
1
- README.rdoc
2
1
  lib/**/*.rb
3
2
  bin/*
4
- features/**/*.feature
5
- LICENSE
3
+ -
4
+ README.rdoc
5
+ LICENSE.txt
@@ -0,0 +1 @@
1
+ --title 'Padrino Helpers Documentation' --protected
File without changes
@@ -34,7 +34,8 @@ Added to a template, this will capture the includes from the block and allow the
34
34
  ...
35
35
 
36
36
  This will automatically insert the contents of the block (in this case a stylesheet include) into the
37
- location the content is yielded within the layout.
37
+ location the content is yielded within the layout. You can also check if content exists for a block using
38
+ <tt>content_for?(true)</tt> which returns true if content exists.
38
39
 
39
40
  The capture_html and the concat_content methods allow content to be manipulated and stored for use in building
40
41
  additional helpers accepting blocks or displaying information in a template. One example is the use of
@@ -183,8 +184,7 @@ For more information on using the Padrino form builders, check out the guide for
183
184
  === Format Helpers
184
185
 
185
186
  Format helpers are several useful utilities for manipulating the format of text to achieve a goal.
186
- The four format helpers are <tt>escape_html</tt>, <tt>relative_time_ago</tt>, <tt>time_in_words</tt>,
187
- and <tt>js_escape_html</tt>.
187
+ The four format helpers are <tt>escape_html</tt>, <tt>time_ago_in_words</tt>, and <tt>js_escape_html</tt>.
188
188
 
189
189
  The escape_html and js_escape_html function are for taking an html string and escaping certain characters.
190
190
  <tt>escape_html</tt> will escape ampersands, brackets and quotes to their HTML/XML entities. This is useful
@@ -15,25 +15,32 @@ I18n.load_path += Dir["#{File.dirname(__FILE__)}/padrino-helpers/locale/*.yml"]
15
15
 
16
16
  module Padrino
17
17
  ##
18
- # This component provides a great deal of view helpers related to html markup generation.
18
+ # This component provides a variety of view helpers related to html markup generation.
19
19
  # There are helpers for generating tags, forms, links, images, and more.
20
20
  # Most of the basic methods should be very familiar to anyone who has used rails view helpers.
21
21
  #
22
22
  module Helpers
23
- ##
24
- # Register these helpers:
25
- #
26
- # Padrino::Helpers::OutputHelpers
27
- # Padrino::Helpers::TagHelpers
28
- # Padrino::Helpers::AssetTagHelpers
29
- # Padrino::Helpers::FormHelpers
30
- # Padrino::Helpers::FormatHelpers
31
- # Padrino::Helpers::RenderHelpers
32
- # Padrino::Helpers::NumberHelpers
33
- #
34
- # for Padrino::Application
35
- #
36
23
  class << self
24
+ ##
25
+ # Registers these helpers into your application:
26
+ #
27
+ # Padrino::Helpers::OutputHelpers
28
+ # Padrino::Helpers::TagHelpers
29
+ # Padrino::Helpers::AssetTagHelpers
30
+ # Padrino::Helpers::FormHelpers
31
+ # Padrino::Helpers::FormatHelpers
32
+ # Padrino::Helpers::RenderHelpers
33
+ # Padrino::Helpers::NumberHelpers
34
+ #
35
+ # @param [Sinatra::Application] app
36
+ # The specified padrino application
37
+ #
38
+ # @example Register the helper module
39
+ # require 'padrino-helpers'
40
+ # class Padrino::Appliocation
41
+ # register Padrino::Helpers
42
+ # end
43
+ #
37
44
  def registered(app)
38
45
  app.set :default_builder, 'StandardFormBuilder'
39
46
  app.helpers Padrino::Helpers::OutputHelpers
@@ -4,10 +4,18 @@ module Padrino
4
4
  ##
5
5
  # Creates a div to display the flash of given type if it exists
6
6
  #
7
- # ==== Examples
8
- # # Generates: <div class="notice">flash-notice</div>
7
+ # @param [Symbol] kind
8
+ # The type of flash to display in the tag.
9
+ # @param [Hash] options
10
+ # The html options for this section.
11
+ #
12
+ # @return [String] Flash tag html with specified +options+.
13
+ #
14
+ # @example
9
15
  # flash_tag(:notice, :id => 'flash-notice')
16
+ # # Generates: <div class="notice">flash-notice</div>
10
17
  #
18
+ # @api public
11
19
  def flash_tag(kind, options={})
12
20
  flash_text = flash[kind]
13
21
  return '' if flash_text.blank?
@@ -18,16 +26,40 @@ module Padrino
18
26
  ##
19
27
  # Creates a link element with given name, url and options
20
28
  #
21
- # ==== Examples
22
- #
29
+ # @overload link_to(caption, url, options={})
30
+ # @param [String] caption The text caption.
31
+ # @param [String] url The url href.
32
+ # @param [Hash] options The html options.
33
+ # @overload link_to(url, options={}, &block)
34
+ # @param [String] url The url href.
35
+ # @param [Hash] options The html options.
36
+ # @param [Proc] block The link content.
37
+ #
38
+ # @option options [String] :anchor
39
+ # The anchor for the link (i.e #something)
40
+ # @option options [Boolean] :if
41
+ # If true, the link will appear, otherwise not;
42
+ # @option options [Boolean] :unless
43
+ # If false, the link will appear, otherwise not;
44
+ # @option options [Boolean] :remote
45
+ # If true, this link should be handled by a ajax ujs handler.
46
+ # @option options [String] :confirm
47
+ # Instructs ujs handler to alert confirm message.
48
+ # @option options [Symbol] :method
49
+ # Instructs ujs handler to use different http method (i.e :post, :delete).
50
+ #
51
+ # @return [String] Link tag html with specified +options+.
52
+ #
53
+ # @example
23
54
  # link_to('click me', '/dashboard', :class => 'linky')
24
55
  # link_to('click me', '/dashboard', :remote => true)
25
56
  # link_to('click me', '/dashboard', :method => :delete)
26
- # link_to('click me', :class => 'blocky') do ... end
57
+ # link_to('click me', :class => 'blocky') do; end
27
58
  #
28
59
  # Note that you can pass :+if+ or :+unless+ conditions, but if you provide :current as
29
60
  # condition padrino return true/false if the request.path_info match the given url
30
61
  #
62
+ # @api public
31
63
  def link_to(*args, &block)
32
64
  options = args.extract_options!
33
65
  options = parse_js_attributes(options) # parses remote, method and confirm options
@@ -51,15 +83,33 @@ module Padrino
51
83
  ##
52
84
  # Creates a form containing a single button that submits to the url.
53
85
  #
54
- # ==== Examples
55
- #
86
+ # @overload button_to(name, url, options={})
87
+ # @param [String] caption The text caption.
88
+ # @param [String] url The url href.
89
+ # @param [Hash] options The html options.
90
+ # @overload button_to(name, options={}, &block)
91
+ # @param [String] url The url href.
92
+ # @param [Hash] options The html options.
93
+ # @param [Proc] block The button content.
94
+ #
95
+ # @option options [Boolean] :multipart
96
+ # If true, this form will support multipart encoding.
97
+ # @option options [String] :remote
98
+ # Instructs ujs handler to handle the submit as ajax.
99
+ # @option options [Symbol] :method
100
+ # Instructs ujs handler to use different http method (i.e :post, :delete).
101
+ #
102
+ # @return [String] Form and button html with specified +options+.
103
+ #
104
+ # @example
105
+ # button_to 'Delete', url(:accounts_destroy, :id => account), :method => :delete, :class => :form
56
106
  # # Generates:
57
107
  # # <form class="form" action="/admin/accounts/destroy/2" method="post">
58
108
  # # <input type="hidden" value="delete" name="_method" />
59
109
  # # <input type="submit" value="Delete" />
60
110
  # # </form>
61
- # button_to 'Delete', url(:accounts_destroy, :id => account), :method => :delete, :class => :form
62
111
  #
112
+ # @api public
63
113
  def button_to(*args, &block)
64
114
  name, url = args[0], args[1]
65
115
  options = args.extract_options!
@@ -76,34 +126,56 @@ module Padrino
76
126
  ##
77
127
  # Creates a link tag that browsers and news readers can use to auto-detect an RSS or ATOM feed.
78
128
  #
79
- # === Options
80
- #
81
- # :rel:: Specify the relation of this link, defaults to "alternate"
82
- # :type:: Override the auto-generated mime type
83
- # :title:: Specify the title of the link, defaults to the type
84
- #
85
- # === Examples
86
- #
87
- # # Generates: <link type="application/atom+xml" rel="alternate" href="/blog/posts.atom" title="ATOM" />
129
+ # @param [Symbol] mime
130
+ # The mime type of the feed (i.e :atom or :rss).
131
+ # @param [String] url
132
+ # The url for the feed tag to reference.
133
+ # @param[Hash] options
134
+ # The options for the feed tag.
135
+ # @option options [String] :rel ("alternate")
136
+ # Specify the relation of this link
137
+ # @option options [String] :type
138
+ # Override the auto-generated mime type
139
+ # @option options [String] :title
140
+ # Specify the title of the link, defaults to the type
141
+ #
142
+ # @return [String] Feed link html tag with specified +options+.
143
+ #
144
+ # @example
88
145
  # feed_tag :atom, url(:blog, :posts, :format => :atom), :title => "ATOM"
89
- # # Generates: <link type="application/rss+xml" rel="alternate" href="/blog/posts.rss" title="rss" />
146
+ # # Generates: <link type="application/atom+xml" rel="alternate" href="/blog/posts.atom" title="ATOM" />
90
147
  # feed_tag :rss, url(:blog, :posts, :format => :rss)
148
+ # # Generates: <link type="application/rss+xml" rel="alternate" href="/blog/posts.rss" title="rss" />
91
149
  #
150
+ # @api public
92
151
  def feed_tag(mime, url, options={})
93
152
  full_mime = (mime == :atom) ? 'application/atom+xml' : 'application/rss+xml'
94
153
  content_tag(:link, options.reverse_merge(:rel => 'alternate', :type => full_mime, :title => mime, :href => url))
95
154
  end
96
155
 
97
156
  ##
98
- # Creates a mail link element with given name and caption
99
- #
100
- # ==== Examples
101
- #
157
+ # Creates a mail link element with given name and caption.
158
+ #
159
+ # @param [String] email
160
+ # The email address for the link.
161
+ # @param [String] caption
162
+ # The caption for the link.
163
+ # @param [Hash] mail_options
164
+ # The options for the mail link. Accepts html options.
165
+ # @option mail_options [String] cc The cc recipients.
166
+ # @option mail_options [String] bcc The bcc recipients.
167
+ # @option mail_options [String] subject The subject line.
168
+ # @option mail_options [String] body The email body.
169
+ #
170
+ # @return [String] Mail link html tag with specified +options+.
171
+ #
172
+ # @example
102
173
  # # Generates: <a href="mailto:me@demo.com">me@demo.com</a>
103
174
  # mail_to "me@demo.com"
104
175
  # # Generates: <a href="mailto:me@demo.com">My Email</a>
105
176
  # mail_to "me@demo.com", "My Email"
106
177
  #
178
+ # @api public
107
179
  def mail_to(email, caption=nil, mail_options={})
108
180
  html_options = mail_options.slice!(:cc, :bcc, :subject, :body)
109
181
  mail_query = Rack::Utils.build_query(mail_options).gsub(/\+/, '%20').gsub('%40', '@')
@@ -112,16 +184,23 @@ module Padrino
112
184
  end
113
185
 
114
186
  ##
115
- # Creates a meta element with the content and given options
187
+ # Creates a meta element with the content and given options.
188
+ #
189
+ # @param [String] content
190
+ # The content for the meta tag.
191
+ # @param [Hash] options
192
+ # The html options for the meta tag.
116
193
  #
117
- # ==== Examples
194
+ # @return [String] Meta html tag with specified +options+.
118
195
  #
196
+ # @example
119
197
  # # Generates: <meta name="keywords" content="weblog,news">
120
198
  # meta_tag "weblog,news", :name => "keywords"
121
199
  #
122
200
  # # Generates: <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
123
201
  # meta_tag "text/html; charset=UTF-8", 'http-equiv' => "Content-Type"
124
202
  #
203
+ # @api public
125
204
  def meta_tag(content, options={})
126
205
  options.reverse_merge!("content" => content)
127
206
  tag(:meta, options)
@@ -130,14 +209,21 @@ module Padrino
130
209
  ##
131
210
  # Generates a favicon link. looks inside images folder
132
211
  #
133
- # ==== Examples
212
+ # @param [String] source
213
+ # The source image path for the favicon link tag.
214
+ # @param [Hash] options
215
+ # The html options for the favicon link tag.
134
216
  #
217
+ # @return [String] The favicon link html tag with specified +options+.
218
+ #
219
+ # @example
135
220
  # favicon_tag 'favicon.png'
136
221
  # favicon_tag 'icons/favicon.png'
137
222
  # # or override some options
138
223
  # favicon_tag 'favicon.png', :type => 'image/ico'
139
224
  #
140
- def favicon_tag(source,options={})
225
+ # @api public
226
+ def favicon_tag(source, options={})
141
227
  type = File.extname(source).gsub('.','')
142
228
  options = options.dup.reverse_merge!(:href => image_path(source), :rel => 'icon', :type => "image/#{type}")
143
229
  tag(:link, options)
@@ -146,10 +232,17 @@ module Padrino
146
232
  ##
147
233
  # Creates an image element with given url and options
148
234
  #
149
- # ==== Examples
235
+ # @param [String] url
236
+ # The source path for the image tag.
237
+ # @param [Hash] options
238
+ # The html options for the image tag.
239
+ #
240
+ # @return [String] Image html tag with +url+ and specified +options+.
150
241
  #
242
+ # @example
151
243
  # image_tag('icons/avatar.png')
152
244
  #
245
+ # @api public
153
246
  def image_tag(url, options={})
154
247
  options.reverse_merge!(:src => image_path(url))
155
248
  tag(:img, options)
@@ -157,13 +250,19 @@ module Padrino
157
250
 
158
251
  ##
159
252
  # Returns an html script tag for each of the sources provided.
160
- # You can pass in the filename without extension or a symbol and we search it in your +appname.public+
253
+ # You can pass in the filename without extension or a symbol and we search it in your +appname.public_folder+
161
254
  # like app/public/stylesheets for inclusion. You can provide also a full path.
162
255
  #
163
- # ==== Examples
256
+ # @overload stylesheet_link_tag(*sources, options={})
257
+ # @param [Array<String>] sources Splat of css source paths
258
+ # @param [Hash] options The html options for the link tag
259
+ #
260
+ # @return [String] Stylesheet link html tag for +sources+ with specified +options+.
164
261
  #
262
+ # @example
165
263
  # stylesheet_link_tag 'style', 'application', 'layout'
166
264
  #
265
+ # @api public
167
266
  def stylesheet_link_tag(*sources)
168
267
  options = sources.extract_options!.symbolize_keys
169
268
  options.reverse_merge!(:media => 'screen', :rel => 'stylesheet', :type => 'text/css')
@@ -174,13 +273,19 @@ module Padrino
174
273
 
175
274
  ##
176
275
  # Returns an html script tag for each of the sources provided.
177
- # You can pass in the filename without extension or a symbol and we search it in your +appname.public+
276
+ # You can pass in the filename without extension or a symbol and we search it in your +appname.public_folder+
178
277
  # like app/public/javascript for inclusion. You can provide also a full path.
179
278
  #
180
- # ==== Examples
279
+ # @overload javascript_include_tag(*sources, options={})
280
+ # @param [Array<String>] sources Splat of js source paths
281
+ # @param [Hash] options The html options for the script tag
181
282
  #
283
+ # @return [String] Script tag for +sources+ with specified +options+.
284
+ #
285
+ # @example
182
286
  # javascript_include_tag 'application', :extjs
183
287
  #
288
+ # @api public
184
289
  def javascript_include_tag(*sources)
185
290
  options = sources.extract_options!.symbolize_keys
186
291
  options.reverse_merge!(:type => 'text/javascript', :content => "")
@@ -190,14 +295,19 @@ module Padrino
190
295
  end
191
296
 
192
297
  ##
193
- # Returns the path to the image, either relative or absolute. We search it in your +appname.public+
298
+ # Returns the path to the image, either relative or absolute. We search it in your +appname.public_folder+
194
299
  # like app/public/images for inclusion. You can provide also a full path.
195
300
  #
196
- # ==== Examples
301
+ # @param [String] src
302
+ # The path to the image file (relative or absolute)
303
+ #
304
+ # @return [String] Path to an image given the +kind+ and +source+.
197
305
  #
306
+ # @example
198
307
  # # Generates: /images/foo.jpg?1269008689
199
308
  # image_path("foo.jpg")
200
309
  #
310
+ # @api public
201
311
  def image_path(src)
202
312
  asset_path(:images, src)
203
313
  end
@@ -205,8 +315,14 @@ module Padrino
205
315
  ##
206
316
  # Returns the path to the specified asset (css or javascript)
207
317
  #
208
- # ==== Examples
318
+ # @param [String] kind
319
+ # The kind of asset (i.e :images, :js, :css)
320
+ # @param [String] source
321
+ # The path to the asset (relative or absolute).
209
322
  #
323
+ # @return [String] Path for the asset given the +kind+ and +source+.
324
+ #
325
+ # @example
210
326
  # # Generates: /javascripts/application.js?1269008689
211
327
  # asset_path :js, :application
212
328
  #
@@ -216,6 +332,7 @@ module Padrino
216
332
  # # Generates: /images/example.jpg?1269008689
217
333
  # asset_path :images, 'example.jpg'
218
334
  #
335
+ # @api semipublic
219
336
  def asset_path(kind, source)
220
337
  return source if source =~ /^http/
221
338
  asset_folder = case kind
@@ -237,6 +354,9 @@ module Padrino
237
354
  ##
238
355
  # Returns the uri root of the application.
239
356
  #
357
+ # @example
358
+ # uri_root_path("/some/path") => "/base/some/path"
359
+ #
240
360
  def uri_root_path(*paths)
241
361
  root_uri = self.class.uri_root if self.class.respond_to?(:uri_root)
242
362
  File.join(ENV['RACK_BASE_URI'].to_s, root_uri || '/', *paths)
@@ -245,6 +365,9 @@ module Padrino
245
365
  ##
246
366
  # Returns the timestamp mtime for an asset
247
367
  #
368
+ # @example
369
+ # asset_timestamp("some/path/to/file.png") => "?154543678"
370
+ #
248
371
  def asset_timestamp(file_path)
249
372
  return nil if file_path =~ /\?/ || (self.class.respond_to?(:asset_stamp) && !self.class.asset_stamp)
250
373
  public_path = Padrino.root("public", file_path) if Padrino.respond_to?(:root)
@@ -256,6 +379,9 @@ module Padrino
256
379
  ##
257
380
  # Parses link_to options for given correct conditions
258
381
  #
382
+ # @example
383
+ # parse_conditions("/some/url", :if => false) => true
384
+ #
259
385
  def parse_conditions(url, options)
260
386
  if options.has_key?(:if)
261
387
  condition = options.delete(:if)
@@ -271,6 +397,9 @@ module Padrino
271
397
  # Parses link_to options for given js declarations (remote, method, confirm)
272
398
  # Not destructive on options; returns updated options
273
399
  #
400
+ # parse_js_attributes(:remote => true, :confirm => "test", :method => :delete)
401
+ # => { "data-remote" => true, "data-method" => "delete", "data-confirm" => "test" }
402
+ #
274
403
  def parse_js_attributes(options)
275
404
  options = options.dup
276
405
  options["data-remote"] = "true" if options.delete(:remote)
@@ -9,7 +9,7 @@ module Padrino
9
9
  @object = build_object(object)
10
10
  @options = options
11
11
  raise "FormBuilder template must be initialized!" unless template
12
- raise "FormBuilder object must be not be nil value. If there's no object, use a symbol instead! (i.e :user)" unless object
12
+ raise "FormBuilder object must not be a nil value. If there's no object, use a symbol instead! (i.e :user)" unless object
13
13
  end
14
14
 
15
15
  # f.error_messages