Permalink
Browse files

Rearrange guides

  • Loading branch information...
1 parent fa09de3 commit 5265a8cd40a59ae792da3ed3f2a9648f15ecbd4e @lifo lifo committed Oct 21, 2008
Showing with 19,086 additions and 287 deletions.
  1. +0 −1 .gitignore
  2. +32 −49 railties/Rakefile
  3. +0 −91 railties/doc/guides/actionview/helpers.markdown
  4. +0 −90 railties/doc/guides/actionview/partials.markdown
  5. +0 −56 railties/doc/guides/activerecord/basics.markdown
  6. +1,125 −0 railties/doc/guides/html/actioncontroller_basics.html.html
  7. +2,577 −0 railties/doc/guides/html/association_basics.html
  8. +227 −0 railties/doc/guides/html/authors.html
  9. +1,015 −0 railties/doc/guides/html/benchmarking_and_profiling.html.html
  10. +577 −0 railties/doc/guides/html/caching_with_rails.html
  11. +1,402 −0 railties/doc/guides/html/creating_plugins.html.html
  12. +1,051 −0 railties/doc/guides/html/debugging_rails_applications.html
  13. +901 −0 railties/doc/guides/html/finders.html
  14. +570 −0 railties/doc/guides/html/form_helpers.html
  15. +1,895 −0 railties/doc/guides/html/getting_started_with_rails.html
  16. +380 −0 railties/doc/guides/html/index.html
  17. +1,199 −0 railties/doc/guides/html/layouts_and_rendering.html
  18. +921 −0 railties/doc/guides/html/migrations.html.html
  19. +2,183 −0 railties/doc/guides/html/routing_outside_in.html
  20. +1,280 −0 railties/doc/guides/html/security.html
  21. +1,751 −0 railties/doc/guides/html/testing_rails_applications.html
  22. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/cookies.txt
  23. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/filters.txt
  24. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/http_auth.txt
  25. 0 ...ies/doc/guides/{actioncontroller/actioncontroller.txt → source/actioncontroller_basics/index.txt}
  26. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/introduction.txt
  27. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/methods.txt
  28. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/parameter_filtering.txt
  29. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/params.txt
  30. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/request_response_objects.txt
  31. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/rescue.txt
  32. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/session.txt
  33. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/streaming.txt
  34. 0 railties/doc/guides/{actioncontroller → source/actioncontroller_basics}/verification.txt
  35. 0 railties/doc/guides/{activerecord → source}/active_record_basics.txt
  36. 0 railties/doc/guides/{activerecord → source}/association_basics.txt
  37. 0 railties/doc/guides/{ → source}/authors.txt
  38. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/appendix.txt
  39. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/digging_deeper.txt
  40. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/edge_rails_features.txt
  41. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/examples/graph.html
  42. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/gameplan.txt
  43. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/images/kgraph.png.html
  44. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/images/klist.png.html
  45. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/index.txt
  46. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/rubyprof.txt
  47. 0 railties/doc/guides/{ → source}/benchmarking_and_profiling/statistics.txt
  48. 0 railties/doc/guides/{caching → source}/caching_with_rails.txt
  49. 0 railties/doc/guides/{ → source}/creating_plugins/acts_as_yaffle.txt
  50. 0 railties/doc/guides/{ → source}/creating_plugins/appendix.txt
  51. 0 railties/doc/guides/{ → source}/creating_plugins/basics.markdown
  52. 0 railties/doc/guides/{ → source}/creating_plugins/custom_generator.txt
  53. 0 railties/doc/guides/{ → source}/creating_plugins/custom_route.txt
  54. 0 railties/doc/guides/{creating_plugins/creating_plugins.txt → source/creating_plugins/index.txt}
  55. 0 railties/doc/guides/{ → source}/creating_plugins/migration_generator.txt
  56. 0 railties/doc/guides/{ → source}/creating_plugins/odds_and_ends.txt
  57. 0 railties/doc/guides/{ → source}/creating_plugins/preparation.txt
  58. 0 railties/doc/guides/{ → source}/creating_plugins/string_to_squawk.txt
  59. 0 railties/doc/guides/{ → source}/creating_plugins/view_helper.txt
  60. 0 railties/doc/guides/{debugging → source}/debugging_rails_applications.txt
  61. 0 railties/doc/guides/{activerecord → source}/finders.txt
  62. 0 railties/doc/guides/{forms → source}/form_helpers.txt
  63. 0 railties/doc/guides/{getting_started_with_rails → source}/getting_started_with_rails.txt
  64. 0 railties/doc/guides/{ → source}/icons/README
  65. BIN railties/doc/guides/{ → source}/icons/callouts/1.png
  66. BIN railties/doc/guides/{ → source}/icons/callouts/10.png
  67. BIN railties/doc/guides/{ → source}/icons/callouts/11.png
  68. BIN railties/doc/guides/{ → source}/icons/callouts/12.png
  69. BIN railties/doc/guides/{ → source}/icons/callouts/13.png
  70. BIN railties/doc/guides/{ → source}/icons/callouts/14.png
  71. BIN railties/doc/guides/{ → source}/icons/callouts/15.png
  72. BIN railties/doc/guides/{ → source}/icons/callouts/2.png
  73. BIN railties/doc/guides/{ → source}/icons/callouts/3.png
  74. BIN railties/doc/guides/{ → source}/icons/callouts/4.png
  75. BIN railties/doc/guides/{ → source}/icons/callouts/5.png
  76. BIN railties/doc/guides/{ → source}/icons/callouts/6.png
  77. BIN railties/doc/guides/{ → source}/icons/callouts/7.png
  78. BIN railties/doc/guides/{ → source}/icons/callouts/8.png
  79. BIN railties/doc/guides/{ → source}/icons/callouts/9.png
  80. BIN railties/doc/guides/{ → source}/icons/caution.png
  81. BIN railties/doc/guides/{ → source}/icons/example.png
  82. BIN railties/doc/guides/{ → source}/icons/home.png
  83. BIN railties/doc/guides/{ → source}/icons/important.png
  84. BIN railties/doc/guides/{ → source}/icons/next.png
  85. BIN railties/doc/guides/{ → source}/icons/note.png
  86. BIN railties/doc/guides/{ → source}/icons/prev.png
  87. BIN railties/doc/guides/{ → source}/icons/tip.png
  88. BIN railties/doc/guides/{ → source}/icons/up.png
  89. BIN railties/doc/guides/{ → source}/icons/warning.png
  90. BIN railties/doc/guides/{activerecord → source}/images/belongs_to.png
  91. BIN railties/doc/guides/{securing_rails_applications → source}/images/csrf.png
  92. BIN railties/doc/guides/{activerecord → source}/images/habtm.png
  93. BIN railties/doc/guides/{activerecord → source}/images/has_many.png
  94. BIN railties/doc/guides/{activerecord → source}/images/has_many_through.png
  95. BIN railties/doc/guides/{activerecord → source}/images/has_one.png
  96. BIN railties/doc/guides/{activerecord → source}/images/has_one_through.png
  97. BIN railties/doc/guides/{activerecord → source}/images/polymorphic.png
  98. BIN railties/doc/guides/{securing_rails_applications → source}/images/session_fixation.png
  99. 0 railties/doc/guides/{ → source}/index.txt
  100. 0 railties/doc/guides/{actionview → source}/layouts_and_rendering.txt
  101. 0 railties/doc/guides/{ → source}/migrations/anatomy_of_a_migration.txt
  102. 0 railties/doc/guides/{ → source}/migrations/changelog.txt
  103. 0 railties/doc/guides/{ → source}/migrations/creating_a_migration.txt
  104. 0 railties/doc/guides/{ → source}/migrations/foreign_keys.txt
  105. 0 railties/doc/guides/{migrations/migrations.txt → source/migrations/index.txt}
  106. 0 railties/doc/guides/{ → source}/migrations/rakeing_around.txt
  107. 0 railties/doc/guides/{ → source}/migrations/scheming.txt
  108. 0 railties/doc/guides/{ → source}/migrations/using_models_in_migrations.txt
  109. 0 railties/doc/guides/{ → source}/migrations/writing_a_migration.txt
  110. 0 railties/doc/guides/{routing → source}/routing_outside_in.txt
  111. 0 railties/doc/guides/{securing_rails_applications → source}/security.txt
  112. 0 railties/doc/guides/{testing_rails_applications → source}/testing_rails_applications.txt
View
@@ -5,7 +5,6 @@ activerecord/doc
actionpack/doc
actionmailer/doc
activesupport/doc
-railties/doc
activeresource/pkg
activerecord/pkg
actionpack/pkg
View
@@ -272,58 +272,41 @@ Rake::RDocTask.new { |rdoc|
rdoc.rdoc_files.include('lib/commands/**/*.rb')
}
-# In this array, one defines the guides for which HTML output should be
-# generated. Specify the folder names of the guides. If the .txt filename
-# doesn't equal its folder name, then specify a hash: { 'folder_name' => 'basename' }
-guides = [
- 'getting_started_with_rails',
- # 'testing_rails_applications',
- 'creating_plugins',
- 'actioncontroller',
- 'migrations',
- { 'securing_rails_applications' => 'security' },
- { 'routing' => 'routing_outside_in' },
- { 'forms' =>'form_helpers' },
- { 'activerecord' => 'association_basics' },
- { 'activerecord' => 'finders' },
- { 'debugging' => 'debugging_rails_applications' },
- { 'caching' => 'caching_with_rails' },
- { 'benchmarking_and_profiling' => 'index' },
- { 'actionview' => 'layouts_and_rendering' }
-]
-
-guides_html_files = [] # autogenerated from the 'guides' variable.
-guides.each do |entry|
- if entry.is_a?(Hash)
- guide_folder = entry.keys.first
- guide_name = entry.values.first
- else
- guide_folder = entry
- guide_name = entry
- end
- input = "doc/guides/#{guide_folder}/#{guide_name}.txt"
- output = "doc/guides/#{guide_folder}/#{guide_name}.html"
- guides_html_files << output
- task output => Dir["doc/guides/#{guide_folder}/*.txt"] do
- ENV['MANUALSONRAILS_INDEX_URL'] = '../index.html'
- ENV.delete('MANUALSONRAILS_TOC')
- sh "mizuho", input, "--template", "manualsonrails", "--icons-dir", "../icons"
- end
-end
-
-['index', 'authors'].each do |guide|
- task "doc/guides/#{guide}.html" => "doc/guides/#{guide}.txt" do
- ENV.delete('MANUALSONRAILS_INDEX_URL')
- ENV['MANUALSONRAILS_TOC'] = 'no'
- sh "mizuho", "doc/guides/#{guide}.txt", "--template", "manualsonrails", "--icons-dir", "icons"
+desc "Generate guides for the framework"
+task :guides do
+ require 'mizuho/generator'
+
+ source = "doc/guides/source/"
+ html = "doc/guides/html/"
+ ignore = ['icons', 'images']
+ ignore << 'active_record_basics.txt'
+
+ indexless = ['index.txt', 'authors.txt']
+
+ Dir.entries(source)[2..-1].each do |entry|
+ next if ignore.include?(entry)
+
+ if File.directory?(File.join(source, entry))
+ input = File.join(source, entry, 'index.txt')
+ output = File.join(html, "#{entry}.html")
+ else
+ input = File.join(source, entry)
+ output = File.join(html, entry).sub(/\.txt$/, '')
+ end
+
+ begin
+ puts "GENERATING => #{output}"
+ ENV['MANUALSONRAILS_TOC'] = 'no' if indexless.include?(entry)
+ Mizuho::Generator.new(input, output, 'manualsonrails', nil, File.expand_path(File.join(source, 'icons'))).start
+ rescue Mizuho::GenerationError
+ STDERR.puts "*** ERROR"
+ exit 2
+ ensure
+ ENV.delete('MANUALSONRAILS_TOC')
+ end
end
end
-desc "Generate HTML output for the guides"
-task :generate_guides => guides_html_files
-task :generate_guides => 'doc/guides/index.html'
-task :generate_guides => 'doc/guides/authors.html'
-
# Generate GEM ----------------------------------------------------------------------------
task :copy_gem_environment do
@@ -1,91 +0,0 @@
-Helpers
-====================
-
-Helper Basics
-------------------------
-
-Helpers allow you to encapsulate rendering tasks as reusable functions. Helpers are modules, not classes, so their methods execute in the context in which they are called. They get included in a controller (typically the ApplicationController) using the helper function, like so
-
- Class ApplicationController < ActionController::Base
- …
- helper :menu
-
- def …
- end
- end
-
-In this way, methods in the menu helper are made available to any view or partial in your application. These methods can accept parameters, for example controller instance variables (eg; records or record collections gathered by you current controller), items from the view or partial’s locals[] hash or items from the params[] hash. You may wish to pass your controller instance variables and items from the params[] hash to the locals hash before rendering (See the section on partials). Helper methods can also accept an executable block of code.
-
-It is important to remember, though, that helpers are for rendering, and that they become available once a controller method has returned, while Rails is engaged in rendering the contents generated by a controller method. This means that helper methods are not available from within the methods of your controllers.
-
-Helpers can accomplish a variety of tasks, from formatting a complex tag for embedding content for a browser plugin (eg; Flash), to assembling a menu of options appropriate for the current context of your application, to generating sections of forms that get assembled on-the-fly.
-
-Helpers are organized around rendering tasks, so it is not necessary (nor necessarily desirable) to organize them around your application’s controllers or models. In fact, one of the benefits of helpers is that they are not connected via a rendering pipeline to specific controllers, like views and partials are. They can and should handle more generalized tasks.
-
-Here is a very simple, pseudo-example:
-
- module MenuHelper
- def menu(records, menu_options={})
- item_options = menu_options.merge({<some stuff>})
- items = records.collect |record| do
- menu_item(record, options)
- end
- content_tag(“ul”, items, options)
- end
-
- def menu_item(record, item_options={}))
- action = item_options[:action]
- action ||= “show”
- content_tag(“li”, link_to(record.title, :action => action, item_options)
- end
- end
-
-
-This helper will require that records passed into it have certain fields (notably :title). The helper could be written to use this as a default, allowing the field to be overwritten by an element of item_options.
-
-Look at the Rails API for examples of helpers included in Rails, eg; [`ActionView::Helpers::ActiveRecordHelper`](http://api.rubyonrails.org/classes/ActionView/Helpers/ActiveRecordHelper.html).
-
-Passing Blocks to Helper Methods
-------------------------
-
-We mentioned before that blocks can be passed to helper methods. This allows for an interesting wrinkle: a block passed to a helper method can cause it to render a partial, which can then be wrapped by the helper method’s output. This can make your helper method much more reusable. It doesn’t need to know anything about the internals about what it is rendering, it just contextualizes it for the page. You can also use the helper to modify the locals hash for the partial, based on some configuration information unique to the current controller. You could implement a flexible themes system in this way.
-
-
-Partials vs. Helpers?
-------------------------
-
-In general, the choice between using a partial vs. using a helper depends on the amount of flexibility you need. If the task is more about reacting to conditions than performing actual rendering, you may likely want a helper method. If you want to be able to call it from a variety of views, again, you may want to use a helper method. You can expect to extract helper methods out of code in views and partials during refactoring.
-
-
-Tutorial -- Calling a Helper [UNFINISHED]
-------------------------
-
-1. Create a Rails application using `rails helper_test`
-Notice the code:
-
- class ApplicationController < ActionController::Base
- helper :all # include all helpers, all the time
-For this tutorial, we'll keep this code, but you will likely want to exert more control over loading your helpers.
-
-2. Configure a database of your choice for the app.
-
-3. Inside of the `/app/helpers/` directory, create a new file called, `menu_helper.rb`. Write this in the file:
-
- module MenuHelpers
- def menu(records, item_proc=nil)
- items = records.collect{ |record|
- menu_item(record, item_proc)
- }
- content_tag("ul", items)
- end
-
- def menu_item(record, item_proc=nil)
- item_url = item_proc.call(record)
- item_url ||= { :action => :show }
- content_tag("li", link_to(record.name, item_url))
- end
- end
-
-4. Create a scaffold for some object in your app, using `./script/generate scaffold widgets`.
-5. Create a database table for your widgets, with at least the fields `name` and `id`. Create a few widgets.
-6. Call the menu command twice from `index.html.erb`, once using the default action, and once supplying a Proc to generate urls.
@@ -1,90 +0,0 @@
-A Guide to Using Partials
-===============================
-
-This guide elaborates on the use and function of partials in Ruby on Rails. As your Rails application grows, your view templates can start to contain a lot of duplicate view code. To manage and reduce this complexity, you can by abstract view template code into partials. Partials are reusable snippets of eRB template code stored in separate files with an underscore ('_') prefix.
-
-Partials can be located anywhere in the `app/views` directory. File extensions for partials work just like other template files, they bear an extension that denotes what kind of code they generate. For example, `_animal.html.erb` and `_animal.xml.erb` are valid filenames for partials.
-
-Partials can be inserted in eRB template code by calling the `render` method with the `:partial` option. For example:
-
- <%= render :partial => 'foo' %>
-
-This inserts the result of evaluating the template `_foo.html.erb` into the parent template file at this location. Note that `render` assumes that the partial will be in the same directory as the calling parent template and have the same file extension. Partials can be located anywhere within the `app/views` directory. To use a partial located in a different directory then it the parent, add a '/' before it:
-
- <%= render :partial => '/common/foo' %>
-
-Loads the partial file from the `app/views/common/_foo.html.erb` directory.
-
-Abstracting views into partials can be approached in a number of different ways, depending on the situation. Sometimes, the code that you are abstracting is a specialized view of an object or a collection of objects. Other times, you can look at partials as a reusable subroutine. We'll explore each of these approaches and when to use them as well as the syntax for calling them.
-
-Partials as a View Subroutine
------------------------------
-
-Using the `:locals` option, you can pass a hash of values which will be treated as local variables within the partial template.
-
- <%= render :partial => "person", :locals => { :name => "david" } %>
-
-The variable `name` contains the value `"david"` within the `_person.html.erb` template. Passing variables in this way allows you to create modular, reusable template files. Note that if you want to make local variables that are optional in some use cases, you will have to set them to a sentinel value such as `nil` when they have not been passed. So, in the example above, if the `name` variable is optional in some use cases, you must set:
-
- <% name ||= nil -%>
-
-So that you can later check:
-
- <% if name -%>
- <p>Hello, <%= name %>!</p>
- <% end -%>
-
-Otherwise, the if statement will throw an error at runtime.
-
-Another thing to be aware of is that instance variables that are visible to the parent view template are visible to the partial. So you might be tempted to do this:
-
- <%= render :partial => "person" %>
-
-And then within the partial:
-
- <% if @name -%>
- <p>Hello, <%= @name %>!</p>
- <% end -%>
-
-The potential snag here is that if multiple templates start to rely on this partial, you will need to maintain an instance variable with the same name across all of these templates and controllers. This approach can quickly become brittle if overused.
-
-Partials as a View of an Object
---------------------------------
-
-Another way to look at partials is to view them as mini-views of a particular object or instance variable. Use the `:object` option to pass an object assigns that object to an instance variable named after the partial itself. For example:
-
- # Renders the partial, making @new_person available through
- # the local variable 'person'
- render :partial => "person", :object => @new_person
-
-If the instance variable `name` in the parent template matches the name of the partial, you can use a shortcut:
-
- render :partial => "person"
-
-Now the value that was in `@person` in the parent template is accessible as `person` in the partial.
-
-Partials as a View of a Collection
------------------------------------
-
-Often it is the case that you need to display not just a single object, but a collection of objects. Rather than having to constantly nest the same partial within the same iterator code, Rails provides a syntactical shortcut using the `:collection` option:
-
- # Renders a collection of the same partial by making each element
- # of @winners available through the local variable "person" as it
- # builds the complete response.
- render :partial => "person", :collection => @winners
-
-This calls the `_person.html.erb` partial for each person in the `@winners` collection. This also creates a local variable within the partial called `partial_counter` which contains the index of the current value. So for example:
-
- <%= partial_counter %>) <%= person -%>
-
-Where `@winners` contains three people, produces the following output:
-
- 1) Bill
- 2) Jeff
- 3) Nick
-
-One last detail, you can place an arbitrary snippet of code in between the objects using the `:spacer_template` option.
-
- # Renders the same collection of partials, but also renders the
- # person_divider partial between each person partial.
- render :partial => "person", :collection => @winners, :spacer_template => "person_divider"
@@ -1,56 +0,0 @@
-Active Record Basics
-====================
-
-
-
-The ActiveRecord Pattern
-------------------------
-
-Active Record (the library) conforms to the active record design pattern. The active record pattern is a design pattern often found in applications that use relational database. The name comes from by Martin Fowler's book *Patterns of Enterprise Application Architecture*, in which he describes an active record object as:
-
-> An object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data.
-
-So, an object that follows the active record pattern encapsulates both data and behavior; in other words, they are responsible for saving and loading to the database and also for any domain logic that acts on the data. The data structure of the Active Record should exactly match that of the database: one field in the class for each column in the table.
-
-The Active Record class typically has methods that do the following:
-
-* Construct an instances of an Active Record class from a SQL result
-* Construct a new class instance for insertion into the table
-* Get and set column values
-* Wrap business logic where appropriate
-* Update existing objects and update the related rows in the database
-
-Mapping Your Database
----------------------
-
-### Plural tables, singular classes ###
-
-### Schema lives in the database ###
-
-Creating Records
-----------------
-
-### Using save ###
-
-### Using create ###
-
-Retrieving Existing Rows
-------------------------
-
-### Using find ###
-
-### Using find_by_* ###
-
-Editing and Updating Rows
--------------------------
-
-### Editing an instance
-
-### Using update_all/update_attributes ###
-
-Deleting Data
--------------
-
-### Destroying a record ###
-
-### Deleting a record ###
Oops, something went wrong.

0 comments on commit 5265a8c

Please sign in to comment.