Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 723 lines (512 sloc) 31.026 kb
408aefd @nesquena Cleaning up preface and introduction in the README
nesquena authored
1 = Padrino
469974f @nesquena Initial commit after merging padrino subgems into single repo
nesquena authored
2
3 Padrino is the godfather of Sinatra.
4
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
5 == Preface
6
408aefd @nesquena Cleaning up preface and introduction in the README
nesquena authored
7 This gem has been designed to enhance and build upon Sinatra (http://www.sinatrarb.com).
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
8 Sinatra is a DSL for quickly creating web applications in Ruby with minimal effort.
9 The canonical example of how to create an entire simple web application with Sinatra is something like:
10
11 # myapp.rb
12 require 'rubygems'
13 require 'sinatra'
14 get '/' do
15 'Hello world!'
16 end
17
18 and then to run the application:
19
20 $ ruby myapp.rb
21
408aefd @nesquena Cleaning up preface and introduction in the README
nesquena authored
22 The extreme simplicity of this framework is quite refreshing. We have been using Sinatra a great deal
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
23 for recent projects. First for small and simple json and xml web services and then even
24 for more complex full-featured applications. This gem represents an attempt to make it as fun and easy
408aefd @nesquena Cleaning up preface and introduction in the README
nesquena authored
25 as possible to code increasingly advanced web applications in Sinatra.
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
26
27 == Introduction
28
408aefd @nesquena Cleaning up preface and introduction in the README
nesquena authored
29 Many people love Sinatra's simplicity and lightweight but often quickly come to miss a great deal
30 of functionality provided by other web frameworks such as Rails when building non-trivial applications.
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
31
408aefd @nesquena Cleaning up preface and introduction in the README
nesquena authored
32 The obvious question in these cases might be "Why not just use rails then?". This can often be a viable option
33 but still Rails is quite a large framework with a 'take it or leave it' attitude.
34 Personally, we have come to love the philosophy of Sinatra which acts as a thin layer on top of rack
35 often allowing middleware to do most of the work and pulling in additional complexity only when required.
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
36
408aefd @nesquena Cleaning up preface and introduction in the README
nesquena authored
37 My goal with this extension is to match the essence of Sinatra and at the same time create a standard library
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
38 of tools, helpers and components that will make Sinatra suitable for more complex applications.
39
408aefd @nesquena Cleaning up preface and introduction in the README
nesquena authored
40 Here is a small list of what Padrino provides:
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
41
14ca289 Little improvements (?) to the readme.
Davide D'Agostino authored
42 Generators:: for creating new padrino applications i.e.: <tt>padrino-gen app</tt> or <tt>padrino start</tt> on command line
fb249fb @nesquena Minor rewording on readme
nesquena authored
43 MultiApp:: unlike other ruby frameworks Padrino is principally designed for mounting multiple apps at the same time.
14ca289 Little improvements (?) to the readme.
Davide D'Agostino authored
44 Routing:: Full url named route support to avoid hardcoding route url paths (<tt>map</tt>, <tt>url_for</tt>)
fb249fb @nesquena Minor rewording on readme
nesquena authored
45 Tag Helpers:: helpers such as: <tt>tag</tt>, <tt>content_tag</tt>, <tt>input_tag</tt>, ...
46 Asset Helpers:: helpers such as: <tt>link_to</tt>, <tt>image_tag</tt>, <tt>javascript_include_tag</tt>, ...
47 Form Helpers:: with builder support such as: <tt>form_tag</tt>, <tt>form_for</tt>, <tt>field_set_tag</tt>, <tt>text_field</tt>, ...
14ca289 Little improvements (?) to the readme.
Davide D'Agostino authored
48 Text Helpers:: useful formatting extensions like: <tt>relative_time_ago</tt>, <tt>js_escape_html</tt>, <tt>sanitize_html</tt>
49 Mailer:: fast, tiny, delivery support for send templating emails (like ActionMailer do)
fb249fb @nesquena Minor rewording on readme
nesquena authored
50 Admin:: an ajax admin that displays your records in sortable grids, tree, windows ... as a desktop app can do.
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
51
52 Keep in mind, the user will be able to pull in these components seperately and leave out those that are not required
53 or use them altogether for a comprehensive upgrade to Sinatra (a full-stack Padrino application).
54
408aefd @nesquena Cleaning up preface and introduction in the README
nesquena authored
55 Note that all work has been created to be compatible with haml, erb, and erubis and that this gem is intended to be
56 template-agnostic in providing helpers wherever possible.
57
0b6a601 @nesquena Migrated existing README's from sinatra_more over to padrino gems
nesquena authored
58 Please help me brainstorm and fork the project if you have any ideas to contribute.
59
60 == Installation
61
62 To install the padrino framework, simply grab the latest version from gemcutter:
63
64 $ sudo gem install padrino --source http://gemcutter.org
65
66 This will install the necessary padrino gems to get you started.
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
67 Now you are ready to use this gem to enhance your sinatra projects or to create new Padrino applications.
68
69 == Usage
70
71 Padrino is a framework which builds on the existing functionality and Sinatra and provides a variety of
72 additional tools and helpers to extend the foundation. This README and Padrino documentation in general will focus
73 on the enhancements to the core Sinatra functionality. To use Padrino, one should be familiar with the basic
74 usage of Sinatra itself. Resources for Sinatra are listed below:
75
76 * README (http://www.sinatrarb.com/intro.html)
77 * Book (http://www.sinatrarb.com/book.html)
78 * Repo (http://github.com/sinatra/sinatra)
79
80 Below is a guide to how this gem enhances the Sinatra framework as part of a 'full-stack' padrino application.
81 For information on how to use a specific gem in isolation within an existing Sinatra project, checkout the README for that
82 individual gem or gems.
83
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
84 == Enhanced Base Application (padrino-core)
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
85
ab24abd @nesquena Add todo note consider not force boot.rb to be in config folder or force...
nesquena authored
86 Sinatra has support for classes which can be extended to create an application: <tt>Sinatra::Base</tt> and <tt>Sinatra::Application</tt>
87 These classes can be extended in order to create a Sinatra web application. These classes provide support for all the basic
88 functionality afforded by Sinatra.
89
90 Padrino has support for an enhanced base application class <tt>Padrino::Application</tt>. <tt>Padrino::Application</tt>
91 expands the capabilities of Sinatra::Application and automatically provides the resulting application access to all of
92 the padrino framework's functionalities.
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
93
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
94 Similar in spirit to Sinatra itself, Padrino application layout is extremely flexible and can be as small as a single file.
95 However, Padrino provides many extensions which improve upon the ability to construct more complex applications.
96
cdf2ade @nesquena Fix rdoc header formatting to remove suffix marks
nesquena authored
97 === Simple Application Definition
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
98
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
99 Let us first take a look at the simplest possible Padrino application:
100
101 # app.rb
102 PADRINO_ROOT = File.dirname(__FILE__) unless defined? PADRINO_ROOT
103 require 'padrino'
104 Padrino.load!
105
106 class SimpleApp < Padrino::Application
107 set :app_file, __FILE__
108
109 get '/ do
110 'Hello world'
111 end
112 end
113
cdf2ade @nesquena Fix rdoc header formatting to remove suffix marks
nesquena authored
114 === Gemfile Dependency Resolution
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
115
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
116 While this is a fully operational Padrino application in itself, let us take a look at Padrino's expanded capabilites. First,
117 we can create Gemfile within the application root. This will contain a list of all the dependencies for our application.
118
119 # /Gemfile
120 clear_sources
121 source 'http://gemcutter.org'
122 gem 'sinatra', :require_as => 'sinatra/base'
123 gem 'rack-flash'
124
125 This file uses the standard <tt>bundler</tt> syntax which can be found here: http://github.com/wycats/bundler
126 This allows us to place all our dependencies into a single file. Padrino will then automatically require
127 all necessary files (if they exist on the system).
128
129 If the dependencies are not on the system, you can automatically vendor all necessary gems
130 using the <tt>gem bundle</tt> command within the application root. Note that this is all possible without
131 any further effort than adding the Gemfile (or having this generated automatically with generators explained later).
132
452cb68 @nesquena Further README cleanups for formatting
nesquena authored
133 === Auto Load Paths
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
134
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
135 Padrino also intelligently supports requiring useful files within your application automatically and provides
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
136 functionality for easily splitting up your application into separate files. Padrino automatically requires <tt>config/database.rb</tt>
137 as a convention for establishing database connection. Also, any files within the <tt>lib</tt> folder will be required
138 automatically by Padrino.
139
140 This is powered by the fact that Padrino will automatically load (and reload) any directory patterns within the 'load path'.
141 Additional directory patterns can be added to the load path as needed by simply appending to the <tt>load_paths</tt>
142 within your application:
143
144 # app.rb
145 class SimpleApp < Padrino::Application
146 load_paths << ["app/special/*.rb", "some_file.rb"]
147 end
148
149 This will instruct Padrino to autoload these files (and reload them when changes are detected). By default, the load path
150 contains certain paths known to contain important files such as controllers, mailers, models, urls, and helpers.
151
cdf2ade @nesquena Fix rdoc header formatting to remove suffix marks
nesquena authored
152 === Initializers
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
153
154 Padrino also has support for 'initializers' which are important setup steps or configuration within an application
155 that should occur during the bootup process. To construct initializers, simply add a file to the <tt>config/initializers<tt>
156 directory following this convention:
157
158 # config/initializers/example.rb
159 module ExampleInitializer
160 def self.registered(app)
161 # Manipulate 'app' here to register components or adjust configuration
162 app.set :environment, :production # just an example configuration change
163 app.use Hassle # or even enable middleware
164 end
165 end
166
167 Initializers are automatically required and 'registered' during the application startup process. Note that
168 the name of the module must be the name of the file appended with 'Initializer' (i.e sample.rb => SampleInitializer)
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
169
cdf2ade @nesquena Fix rdoc header formatting to remove suffix marks
nesquena authored
170 === Controllers
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
171
172 Suppose we wanted to add additional routes to our Padrino application, and we want to organize the routes
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
173 within a more structured layout. Simply add a <tt>controllers</tt> or <tt>app/controllers</tt> folder and create a file as such:
174
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
175 # controllers/example.rb
17766cc @nesquena Change all ::controllers, ::urls, ::helpers to invoke directly (i.e Blog...
nesquena authored
176 SimpleApp.controllers do
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
177 get "/test" do
178 "Text to return"
179 end
180 end
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
181
cdf2ade @nesquena Fix rdoc header formatting to remove suffix marks
nesquena authored
182 === Application Logging
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
183
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
184 Padrino also supports robust logging capabilities. By default, logging information will
185 go to the STDOUT in development (for use in a console) and in an environment-specific log file <tt>log/development.log</tt>
186 in test and production environments.
187
188 You can modify the logging behavior or disable logging altogether:
189
190 # app.rb
191 class SimpleApp < Padrino::Application
192 disable :logging # Turns off logging
193 enable :log_to_file # Forces logging to be written to a file
194 end
195
196 To use the logger within a Padrino application, simply refer to the <tt>logger</tt> method accessible
197 within your app and any controller or views:
198
199 # controllers/example.rb
17766cc @nesquena Change all ::controllers, ::urls, ::helpers to invoke directly (i.e Blog...
nesquena authored
200 SimpleApp.controllers do
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
201 get("/test") { logger.info "This is a test" }
202 end
203
204 The logger automatically supports severity through the use of <tt>logger.info</tt>, <tt>logger.warn</tt>, <tt>logger.error</tt>, et al.
205 For more information about the logger, check out the logger rdoc (http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/)
206
cdf2ade @nesquena Fix rdoc header formatting to remove suffix marks
nesquena authored
207 === Mounting Applications
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
208
209 Padrino applications are all automatically mountable into other Padrino projects. This means that a given Padrino
210 project directory can easily mount multiple applications. This allows for better organization of complex applications,
211 re-usable applications that can be applied (i.e admin, auth, blog) and even more flexibility.
212
213 You can think of mountable applications as a 'full-featured' merb slice or rails engine. Instead of a separate construct,
214 any application can simply be packaged and mounted into another project.
215
216 Padrino stores application mounting information by default within <tt>config/apps.rb</tt>. This file is intended
217 to keep all information regarding what applications are mounted to which uri's. An <tt>apps.rb</tt> file has
218 the following structure:
219
220 Padrino.mount("blog").to("/blog")
221 Padrino.mount("website").to("/website")
222
223 This would mount two applications onto the Padrino project, one served from the '/blog' uri namespace and the other
224 served from the '/website' uri namespace. Often a Padrino project directory requires a single 'core' application
225 which is served from the uri root. This can be easily applied with:
226
227 Padrino.mount_core(:app_class => "AppName", :app_file => "app.rb")
228
229 This will mount a 'core' application with class AppName from the file 'app.rb' to the uri root and will act as a primary
230 application.
231
cdf2ade @nesquena Fix rdoc header formatting to remove suffix marks
nesquena authored
232 === Development Reloader
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
233
234 Padrino applications also have the enabled ability to automatically reload all changing application files without
235 the need to restart the server. Through the use of a customized Rack middleware, all files on the 'load path'
236 are monitored and reloaded whenever changes are applied.
237
238 This makes rapid development much easier and provides a better alternative to 'shotgun' or 'rerun'
239 which require the application server to be restarted which makes requests take much longer to complete.
240
241 An application can explicitly enable / disable reloading through the use of options:
242
243 # app.rb
244 class SimpleApp < Padrino::Application
245 disable :reload # reload is disabled in all environments
246 enable :reload # enabled in all environments
247 end
248
249 By default, reloading is enabled in development and disabled in the test and production environments.
250
cdf2ade @nesquena Fix rdoc header formatting to remove suffix marks
nesquena authored
251 === Terminal Commands
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
252
253 Padrino also comes equipped with multiple useful terminal commands which can be activated to perform
254 common tasks such as starting / stopping the application, executing the unit tests or activating an irb session.
255
256 The following commands are available:
257
258 # starts the app server (non-daemonized)
259 $ padrino start
260 # starts the app server (daemonized) with given port, environment and adapter
261 $ padrino start -d -p 3000 -e development -a thin
262
263 # Stops a daemonized app server
264 $ padrino stop
265
266 # Run all the unit tests
267 $ padrino test
268
269 # Bootup the Padrino console (irb)
270 $ padrino console
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
271
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
272 Using these commands can simplify common tasks making development that much smoother.
cf07323 @nesquena Added First piece of README overview to padrino
nesquena authored
273
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
274 == Application Extensions and Helpers (padrino-helpers)
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
275
924843b @nesquena Added padrino-helpers overview to parent README
nesquena authored
276 Padrino provides a large number of 'standard' helpers to make development faster and easier. For a
277 detailed look at all of the padrino helpers, check out the documentation within the
278 {padrino-helpers README}[http://github.com/padrino/padrino-framework/tree/master/padrino-helpers/].
279 The following is a whirlwind guide through useful helpers provided by this gem.
280
281 === Output Helpers
282
283 Output helpers are a collection of important methods for managing, capturing and displaying output
284 in various ways and is used frequently to support higher-level helper functions. There are
285 three output helpers worth mentioning: <tt>content_for</tt>, <tt>capture_html</tt>, and <tt>concat_content</tt>
286
287 The content_for functionality supports capturing content and then rendering this into a different place
288 such as within a layout. One such popular example is including assets onto the layout from a template:
289
290 # app/views/site/index.erb
291 ...
292 <% content_for :assets do %>
293 <%= stylesheet_link_tag 'index', 'custom' %>
294 <% end %>
295 ...
296
297 Added to a template, this will capture the includes from the block and allow them to be yielded into the layout:
298
299 # app/views/layout.erb
300 ...
301 <head>
302 <title>Example</title>
303 <%= stylesheet_link_tag 'style' %>
304 <%= yield_content :assets %>
305 </head>
306 ...
307
308 This will automatically insert the contents of the block (in this case a stylesheet include) into the
309 location the content is yielded within the layout.
310
311 The capture_html and the concat_content methods allow content to be manipulated and stored for use in building
312 additional helpers accepting blocks or displaying information in a template. One example is the use of
313 these in constructing a simplified 'form_tag' helper which accepts a block.
314
315 # form_tag '/register' do ... end
316 def form_tag(url, options={}, &block)
317 # ... truncated ...
318 inner_form_html = capture_html(&block)
319 concat_content '<form>' + inner_form_html + '</form>'
320 end
321
322 This will capture the template body passed into the form_tag block and then append the content
323 to the template through the use of <tt>concat_content</tt>. Note have been built to work for both haml and erb
324 templates using the same syntax.
325
326 === Tag Helpers
327
328 Tag helpers are the basic building blocks used to construct html 'tags' within a view template. There
329 are three major functions for this category: <tt>tag</tt>, <tt>content_tag</tt> and <tt>input_tag</tt>.
330
331 The tag and content_tag are for building arbitrary html tags with a name and specified options. If
332 the tag contains 'content' within then <tt>content_tag</tt> is used. For example:
333
334 tag(:br, :style => ‘clear:both’) => <br style="clear:both" />
335 content_tag(:p, "demo", :class => ‘light’) => <p class="light">demo</p>
336
337 The input_tag is used to build tags that are related to accepting input from the user:
338
339 input_tag :text, :class => "demo" => <input type='text' class='demo' />
340 input_tag :password, :value => "secret", :class => "demo"
341
342 Note that all of these accept html options and result in returning a string containing html tags.
343
344 === Asset Helpers
345
346 Asset helpers are intended to help insert useful html onto a view template such as 'flash' notices,
347 hyperlinks, mail_to links, images, stylesheets and javascript. An example of their uses would be on a
348 simple view template:
349
350 # app/views/example.haml
351 ...
352 %head
353 = stylesheet_link_tag 'layout'
354 = javascript_include_tag 'application'
355 %body
356 ...
357 = flash_tag :notice
358 %p= link_to 'Blog', '/blog', :class => 'example'
359 %p Mail me at #{mail_to 'fake@faker.com', "Fake Email Link", :cc => "test@demo.com"}
360 %p= image_tag 'padrino.png', :width => '35', :class => 'logo'
361
362 For more detailed documentation, check out the <tt>padrino-helpers</tt> gem README
363
364 === Form Helpers
365
366 Form helpers are the 'standard' form tag helpers you would come to expect when building forms. A simple
367 example of constructing a non-object form would be:
368
369 - form_tag '/destroy', :class => 'destroy-form', :method => 'delete' do
370 = flash_tag(:notice)
371 - field_set_tag do
372 %p
373 = label_tag :username, :class => 'first'
374 = text_field_tag :username, :value => params[:username]
375 %p
376 = label_tag :password, :class => 'first'
377 = password_field_tag :password, :value => params[:password]
378 %p
379 = label_tag :strategy
380 = select_tag :strategy, :options => ['delete', 'destroy'], :selected => 'delete'
381 %p
382 = check_box_tag :confirm_delete
383 - field_set_tag(:class => 'buttons') do
384 = submit_tag "Remove"
385
386 For more detailed documentation, check out the <tt>padrino-helpers</tt> gem README
387
388 === Form Builders
389
390 Form builders are full-featured objects allowing the construction of complex object-based forms
391 using a simple, intuitive syntax. Building a form is as follows:
392
393 - form_for @user, '/register', :id => 'register' do |f|
394 = f.error_messages
395 %p
396 = f.label :username, :caption => "Nickname"
397 = f.text_field :username
398 %p
399 = f.label :email
400 = f.text_field :email
401 %p
402 = f.label :password
403 = f.password_field :password
404 %p
405 = f.label :is_admin, :caption => "Admin User?"
406 = f.check_box :is_admin
407 %p
408 = f.label :color, :caption => "Favorite Color?"
409 = f.select :color, :options => ['red', 'black']
410 %p
411 - fields_for @user.location do |location|
412 = location.text_field :street
413 = location.text_field :city
414 %p
415 = f.submit "Create", :class => 'button'
416
417 There is also support for using more advanced form builders or even creating your own to make
418 form building even easier. For more detailed documentation, check out the <tt>padrino-helpers</tt> gem README.
419
420 === Format Helpers
421
422 Format helpers are several useful utilities for manipulating the format of text to achieve a goal.
423 The four format helpers are <tt>escape_html</tt>, <tt>relative_time_ago</tt>, <tt>time_in_words</tt>,
424 and <tt>js_escape_html</tt>.
425
426 The escape_html and js_escape_html function are for taking an html string and escaping certain characters.
427 <tt>escape_html</tt> will escape ampersands, brackets and quotes to their HTML/XML entities. This is useful
428 to sanitize user content before displaying this on a template. <tt>js_escape_html</tt> is used for
429 passing javascript information from a js template to a javascript function.
430
431 escape_html('<hello>&<goodbye>') # => &lt;hello&gt;&amp;&lt;goodbye&gt;
432
433 There is also an alias for escape_html called <tt>h</tt> for even easier usage within templates
434
435 === Render Helpers
436
437 Render helpers are a series of helpers intended to make certain rendering template tasks easier to perform.
438 This section also includes partial support to allow rendering mini-templates.
439
440 The <tt>haml_template</tt> and <tt>erb_template</tt> functions simply make rendering view templates easier
441 when working with templates inside the views directory. Sinatra provides helpers for this but they work
442 in a way which can be slightly counterintuitive:
443
444 haml :index # OK, renders the ./views/index.haml
445 haml 'site/index' # This renders the literal string 'site/index'
446 haml :'site/index' # AH, this renders the ./views/site/index.haml
447
448 For this reason, additional helpers for erb and haml have been provided which always renders a given file path:
449
450 haml_template :index # OK, renders the ./views/index.haml
451 haml_template 'site/index' # This renders ./views/index.haml
452 haml_template :'site/index' # This also renders ./views/index.haml
453
454 This helper also supports template partials which make rendering small bits of view template
455 within a view much easier. Quick example would be:
456
457 # app/views/index.haml
458 ...
459 = partial 'photo/_item', :object => @photo, :locals => { :foo => 'bar' }
460
461 and then the partial would be:
462
463 # app/views/photo/_item.haml
464 # Access to collection counter with <partial_name>_counter i.e item_counter
465 # Access the object with the partial_name i.e item
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
466
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
467 == Advanced Routing Support (padrino-routing)
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
468
35c2a2a @nesquena Added routing details to README (padrino-core, padrino-routing)
nesquena authored
469 Padrino provides support for advanced routing functionality not available within Sinatra. This routing
470 supports named route aliases and easy access to url paths. The benefits of this is that instead of having to
471 hard-code route urls into every area of your application, now we can just define the urls in a
472 single spot and then attach an alias which can be used to refer to the url throughout the application.
473
474 For a detailed look at all of padrino routing functionality, check out the documentation within the
475 {padrino-routing README}[http://github.com/padrino/padrino-framework/tree/master/padrino-routing/].
93c87d2 @nesquena Added section in README about generators (padrino-core, padrino-gen)
nesquena authored
476 The following is a whirlwind guide through useful route extensions provided by this gem.
35c2a2a @nesquena Added routing details to README (padrino-core, padrino-routing)
nesquena authored
477
ca23a6c @nesquena Split up parent README routing section with logical titles for easy refe...
nesquena authored
478 === Simple Route Aliases
35c2a2a @nesquena Added routing details to README (padrino-core, padrino-routing)
nesquena authored
479
480 The simplest example of route aliases is to construct named aliases representing a url, and then use
481 the alias to reference the url within the application:
482
483 class SimpleApp < Padrino::Application
484 set :app_file, __FILE__
485
486 # Define the named route mappings
487 map(:account).to("/the/accounts/:name/and/:id")
488 map(:accounts).to("/the/accounts/index")
489
490 # Configure the routes using the named alias
491 get :account do
492 "name: params[:name] - id: params[:id]"
493 end
494 get :accounts do
495 "I am the body for the url /the/accounts/index"
496 end
497 end
498
ca23a6c @nesquena Split up parent README routing section with logical titles for easy refe...
nesquena authored
499 === Padrino Routing Conventions
500
35c2a2a @nesquena Added routing details to README (padrino-core, padrino-routing)
nesquena authored
501 The convention within a Padrino application is to store 'external' route alias mappings within a special
502 urls file located at <tt>urls.rb</tt> or <tt>config/urls.rb</tt>. A url routing file might look like:
503
504 # config/urls.rb
505 SimpleApp.urls do
506 map(:index).to("/index")
507 map(:account).to("/the/accounts/:name/and/:id")
508 end
509
510 Urls mapped here can then be defined within a controller:
511
512 # app/controllers/example.rb
513 SimpleApp.controllers do
514 get :index do
515 ...
516 end
517
518 get :account do
519 # access params[:name] and params[:index]
520 end
521 end
522
523 and finally referenced anywhere in the application:
524
525 # app/views/example.haml
526 = link_to "Index", url_for(:index)
527 = link_to "Account", url_for(:account, :id => 1, :name => 'first')
ca23a6c @nesquena Split up parent README routing section with logical titles for easy refe...
nesquena authored
528
529 === Inline Route Alias Definitions
35c2a2a @nesquena Added routing details to README (padrino-core, padrino-routing)
nesquena authored
530
531 The routing plugin also supports inline route definitions in which the url and the named alias
532 are defined together within the controller:
533
534 # app/controllers/example.rb
535 SimpleApp.controllers do
536 get :index, :map => '/index' do
537 ...
538 end
539
540 get :account, :map => '/the/accounts/:name/and/:id' do
541 # access params[:name] and params[:index]
542 end
543 end
544
545 Routes defined inline this way can be accessed and treated the same way as traditional named aliases.
546
ca23a6c @nesquena Split up parent README routing section with logical titles for easy refe...
nesquena authored
547 === Namespaced Route Aliases
548
35c2a2a @nesquena Added routing details to README (padrino-core, padrino-routing)
nesquena authored
549 There is also support for namespaced routes which are organized into a larger grouping:
550
551 # /app/routes/example.rb
552 SimpleApp.controllers do
553 map :admin do |namespace|
554 namespace.map(:show).to("/admin/:id/show")
555 end
556
557 namespace :admin do
558 get :show do
559 "admin show for #{params[:id]}"
560 end
561
562 get :index, :map => "/admin/:id/index" do
563 "admin destroy for #{params[:id]}"
564 end
565 end
566 end
567
568 You can then reference the urls using the same url_for method:
569
570 <%= link_to 'admin show page', url_for(:admin, :show, :id => 25) %>
571 <%= link_to 'admin index page', url_for(:admin, :index, :id => 25) %>
ca23a6c @nesquena Split up parent README routing section with logical titles for easy refe...
nesquena authored
572
573 === Controller Namespaces
35c2a2a @nesquena Added routing details to README (padrino-core, padrino-routing)
nesquena authored
574
575 In addition to regular namespacing, as a shortcut you can have a controller serve as a namespace as well:
576
577 # /app/routes/admin.rb
578 SimpleApp.controllers :admin do
579 get :index, :map => "/admin/:id/index" do
580 "admin destroy for #{params[:id]}"
581 end
582 end
583
584 This will put all named routes within this controller block into the 'admin' namespace and then can be referenced:
585
586 <%= link_to 'admin index page', url_for(:admin, :index, :id => 25) %>
587
588 Note that controller namespaces are simply a shortcut for standard namespaces and do not differ in any other way.
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
589
93c87d2 @nesquena Added section in README about generators (padrino-core, padrino-gen)
nesquena authored
590 == Simple Mailer Support (padrino-mailer)
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
591
592 ...
593
93c87d2 @nesquena Added section in README about generators (padrino-core, padrino-gen)
nesquena authored
594 == Agnostic Application Generators (padrino-gen)
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
595
93c87d2 @nesquena Added section in README about generators (padrino-core, padrino-gen)
nesquena authored
596 Padrino provides support for advanced routing functionality not available within Sinatra. This routing
597 supports named route aliases and easy access to url paths. The benefits of this is that instead of having to
598 hard-code route urls into every area of your application, now we can just define the urls in a
599 single spot and then attach an alias which can be used to refer to the url throughout the application.
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
600
93c87d2 @nesquena Added section in README about generators (padrino-core, padrino-gen)
nesquena authored
601 For a detailed look at all of padrino generator functionality, check out the documentation within the
602 {padrino-generator README}[http://github.com/padrino/padrino-framework/tree/master/padrino-gen/].
603 The following is a whirlwind guide through useful generators provided by this gem.
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
604
93c87d2 @nesquena Added section in README about generators (padrino-core, padrino-gen)
nesquena authored
605
606 === Application Generator ===
607
608 Padrino provides generator support for quickly creating new Padrino applications. This provides many benefits
609 such as constructing the recommended Padrino application structure, auto-generating a Gemfile listing
610 all starting dependencies and guidelines provided within the generated files to help orient a new user
611 to using Padrino.
612
613 One important feature of the generators is that they were built from the ground up to support a wide variety
614 of tools, libraries and gems for use within your padrino application.
615
616 This means that Padrino generators do *not* lock you into using any particular database, ORM, testing framework,
617 templating engine or javascript library. In fact, when generating an application you can actually tell
618 Padrino which components you would like to use!
619
620 Generating a brand new Padrino project is as simple as a single command on the terminal:
621
622 $ padrino-gen app demo_blog . --test=shoulda --renderer=haml --mock=rr --script=jquery --orm datamapper
623
624 This will automatically create a new folder called 'demo_blog' containing a starting point for the
625 'DemoBlog' Padrino application using all the components specified during construction.
626
627 For information on generating appications, check out the
628 {padrino-generator README}[http://github.com/padrino/padrino-framework/tree/master/padrino-gen/].
629
630 === Model Generator ===
631
632 Padrino provides generator support for quickly creating new models within your Padrino application. Note that
633 the models (and migrations) generated are specifically tailored towards the ORM component and testing framework
634 chosen during application generation.
635
636 Very important to note that model generators are intended primarily to work within applications
637 created through the Padrino application generator and that follow Padrino conventions. Using model generators
638 within an existing application not generated by Padrino will likely not work as expected.
639
640 Using the model generator is as simple as:
641
642 $ padrino-gen model User
643
644 You can also specify desired fields to be contained within your User model:
645
646 $ padrino-gen model User name:string age:integer email:string
647
648 The model generator will create multiple files within your application and based on your ORM component.
649 Usually the model file will generate files similar to the following:
650
651 * model definition file [app/models/user.rb]
652 * migration declaration [db/migrate/xxx_create_users.rb]
653 * model unit test file [test/models/user_test.rb]
654
655 You can define as many models as you would like in a Padrino application using this generator.
656
657 === Migration Generator ===
658
659 Padrino provides generator for quickly generating new migrations to change or manipulate the database schema.
660 These migrations generated will be tailored towards the ORM chosen when generating the application.
661
662 Very important to note that migration generators are intended primarily to work within applications
663 created through the Padrino application generator and that follow Padrino conventions. Using migration generators
664 within an existing application not generated by Padrino will likely not work as expected.
665
666 Using the migration generator is as simple as:
667
668 $ padrino-gen migration AddFieldsToUsers
669 $ padrino-gen migration RemoveFieldsFromUsers
670
671 You can also specify desired columns to be added to the migration file:
672
673 $ padrino-gen migration AddFieldsToUsers last_login:datetime crypted_password:string
674 $ padrino-gen migration RemoveFieldsFromUsers password:string ip_address:string
675
676 The migration generator will then construct the migration file according to your ORM component chosen
677 within <tt>db/migrate/xxx_add_fields_to_users.rb</tt> including the columns specified in the command.
678
679 === Controller Generator ===
680
681 Padrino provides generator support for quickly creating new controllers within your Padrino application. Note that
682 the controller tests are generated specifically tailored towards the testing framework chosen
683 during application generation.
684
685 Very important to note that controller generators are intended primarily to work within applications
686 created through the Padrino application generator and that follow Padrino conventions.
687
688 Using the controller generator is as simple as:
689
690 $ padrino-gen controller Admin
691
692 You can also specify desired actions to be added to your controller:
693
694 $ padrino-gen controller Admin :index [:admin, :index]
695
696 The controller generator will then construct the controller file within <tt>app/controllers/admin.rb</tt>
697 and also a controller test file at <tt>test/controllers/admin_controller_test.rb</tt> according to the
698 test framework chosen during app generation.
699
700 === Mailer Generator ===
701
702 Padrino provides generator support for quickly creating new mailers within your Padrino application.
703 Very important to note that mailer generators are intended primarily to work within applications
704 created through the Padrino application generator and that follow Padrino conventions.
705
706 Using the mailer generator is as simple as:
707
708 $ padrino-gen mailer UserNotifier
709
710 You can also specify desired delivery actions to be added to the mailer:
711
712 $ padrino-gen mailer UserNotifier confirm_account welcome inactive_account
713
714 The mailer generator will then construct the mailer file within <tt>app/mailers/user_notifier.rb</tt>
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
715
f654a2e @nesquena Fleshed out even more of the 'Enhanced Base Application' README
nesquena authored
716 == Admin Dashboard and Authentication (padrino-admin)
886c46a @nesquena Added skeleton for explaining padrino enhancements in parent README
nesquena authored
717
93c87d2 @nesquena Added section in README about generators (padrino-core, padrino-gen)
nesquena authored
718 ...COMING SOON...
719
720 == Painless Page and Fragment Caching (padrino-cache)
721
722 ...COMING SOON...
Something went wrong with that request. Please try again.