diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/4_0_release_notes.md | 8 | ||||
| -rw-r--r-- | guides/source/active_support_core_extensions.md | 4 | ||||
| -rw-r--r-- | guides/source/documents.yaml | 63 | ||||
| -rw-r--r-- | guides/source/form_helpers.md | 2 | ||||
| -rw-r--r-- | guides/source/working_with_javascript_in_rails.md (renamed from guides/source/working_with_javascript.md) | 106 |
5 files changed, 90 insertions, 93 deletions
diff --git a/guides/source/4_0_release_notes.md b/guides/source/4_0_release_notes.md index 6b3680aa2d..f24a981c6e 100644 --- a/guides/source/4_0_release_notes.md +++ b/guides/source/4_0_release_notes.md @@ -642,14 +642,6 @@ Active Record * Connections *must* be closed at the end of a thread. If not, your connection pool can fill and an exception will be raised. -* Added the `ActiveRecord::Model` module which can be included in a class as an alternative to inheriting from `ActiveRecord::Base`: - - ```ruby - class Post - include ActiveRecord::Model - end - ``` - * PostgreSQL hstore records can be created. * PostgreSQL hstore types are automatically deserialized from the database. diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index e7ed62ef47..4b2cc947b5 100644 --- a/guides/source/active_support_core_extensions.md +++ b/guides/source/active_support_core_extensions.md @@ -3716,7 +3716,9 @@ File.atomic_write(joined_asset_path) do |cache| end ``` -To accomplish this `atomic_write` creates a temporary file. That's the file the code in the block actually writes to. On completion, the temporary file is renamed, which is an atomic operation on POSIX systems. If the target file exists `atomic_write` overwrites it and keeps owners and permissions. +To accomplish this `atomic_write` creates a temporary file. That's the file the code in the block actually writes to. On completion, the temporary file is renamed, which is an atomic operation on POSIX systems. If the target file exists `atomic_write` overwrites it and keeps owners and permissions. However there are a few cases where `atomic_write` cannot change the file ownership or permissions, this error is caught and skipped over trusting in the user/filesystem to ensure the file is accessible to the processes that need it. + +NOTE. Due to the chmod operation `atomic_write` performs, if the target file has an ACL set on it this ACL will be recalculated/modified. WARNING. Note you can't append with `atomic_write`. diff --git a/guides/source/documents.yaml b/guides/source/documents.yaml index 0b22423798..19425765b8 100644 --- a/guides/source/documents.yaml +++ b/guides/source/documents.yaml @@ -1,4 +1,4 @@ -- +- name: Start Here documents: - @@ -26,82 +26,87 @@ description: This guide covers the database query interface provided by Active Record. - name: Views - documents: - - + documents: + - name: Layouts and Rendering in Rails url: layouts_and_rendering.html description: This guide covers the basic layout features of Action Controller and Action View, including rendering and redirecting, using content_for blocks, and working with partials. - - + - name: Action View Form Helpers url: form_helpers.html description: Guide to using built-in Form helpers. - name: Controllers documents: - - + - name: Action Controller Overview url: action_controller_overview.html description: This guide covers how controllers work and how they fit into the request cycle in your application. It includes sessions, filters, and cookies, data streaming, and dealing with exceptions raised by a request, among other topics. - - + - name: Rails Routing from the Outside In url: routing.html description: This guide covers the user-facing features of Rails routing. If you want to understand how to use routing in your own Rails applications, start here. - name: Digging Deeper documents: - - + - name: Active Support Core Extensions url: active_support_core_extensions.html description: This guide documents the Ruby core extensions defined in Active Support. - - + - name: Rails Internationalization API url: i18n.html description: This guide covers how to add internationalization to your applications. Your application will be able to translate content to different languages, change pluralization rules, use correct date formats for each country and so on. - - + - name: Action Mailer Basics url: action_mailer_basics.html work_in_progress: true description: This guide describes how to use Action Mailer to send and receive emails. - - + - name: Testing Rails Applications url: testing.html work_in_progress: true description: This is a rather comprehensive guide to doing both unit and functional tests in Rails. It covers everything from 'What is a test?' to the testing APIs. Enjoy. - - + - name: Securing Rails Applications url: security.html description: This guide describes common security problems in web applications and how to avoid them with Rails. - - + - name: Debugging Rails Applications url: debugging_rails_applications.html description: This guide describes how to debug Rails applications. It covers the different ways of achieving this and how to understand what is happening "behind the scenes" of your code. - - + - name: Performance Testing Rails Applications url: performance_testing.html description: This guide covers the various ways of performance testing a Ruby on Rails application. - - + - name: Configuring Rails Applications url: configuring.html description: This guide covers the basic configuration settings for a Rails application. - - + - name: Rails Command Line Tools and Rake Tasks url: command_line.html description: This guide covers the command line tools and rake tasks provided by Rails. - - + - name: Caching with Rails work_in_progress: true url: caching_with_rails.html description: Various caching techniques provided by Rails. - - + - name: Asset Pipeline url: asset_pipeline.html description: This guide documents the asset pipeline. - - + - + name: Working with JavaScript in Rails + work_in_progress: true + url: working_with_javascript_in_rails.html + description: This guide covers the built-in Ajax/JavaScript functionality of Rails. + - name: Getting Started with Engines url: engines.html description: This guide explains how to write a mountable engine. work_in_progress: true - - + - name: The Rails Initialization Process work_in_progress: true url: initialization.html @@ -109,38 +114,38 @@ - name: Extending Rails documents: - - + - name: The Basics of Creating Rails Plugins work_in_progress: true url: plugins.html description: This guide covers how to build a plugin to extend the functionality of Rails. - - + - name: Rails on Rack url: rails_on_rack.html description: This guide covers Rails integration with Rack and interfacing with other Rack components. - - + - name: Creating and Customizing Rails Generators url: generators.html description: This guide covers the process of adding a brand new generator to your extension or providing an alternative to an element of a built-in Rails generator (such as providing alternative test stubs for the scaffold generator). - name: Contributing to Ruby on Rails documents: - - + - name: Contributing to Ruby on Rails url: contributing_to_ruby_on_rails.html description: Rails is not 'somebody else's framework.' This guide covers a variety of ways that you can get involved in the ongoing development of Rails. - - + - name: API Documentation Guidelines url: api_documentation_guidelines.html description: This guide documents the Ruby on Rails API documentation guidelines. - - + - name: Ruby on Rails Guides Guidelines url: ruby_on_rails_guides_guidelines.html description: This guide documents the Ruby on Rails guides guidelines. - name: Release Notes documents: - - + - name: Upgrading Ruby on Rails url: upgrading_ruby_on_rails.html work_in_progress: true @@ -157,15 +162,15 @@ name: Ruby on Rails 3.1 Release Notes url: 3_1_release_notes.html description: Release notes for Rails 3.1. - - + - name: Ruby on Rails 3.0 Release Notes url: 3_0_release_notes.html description: Release notes for Rails 3.0. - - + - name: Ruby on Rails 2.3 Release Notes url: 2_3_release_notes.html description: Release notes for Rails 2.3. - - + - name: Ruby on Rails 2.2 Release Notes url: 2_2_release_notes.html description: Release notes for Rails 2.2. diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md index ec1f1d4df1..f5db76f217 100644 --- a/guides/source/form_helpers.md +++ b/guides/source/form_helpers.md @@ -900,7 +900,7 @@ end } ``` -The keys of the `:addresses_attributes` hash are unimportant, they need merely be different for each address. +The keys of the `:addresses_attributes` hash are unimportant, they need merely be different for each address. If the associated object is already saved, `fields_for` autogenerates a hidden input with the `id` of the saved record. You can disable this by passing `:include_id => false` to `fields_for`. You may wish to do this if the autogenerated input is placed in a location where an input tag is not valid HTML or when using an ORM where children do not have an id. diff --git a/guides/source/working_with_javascript.md b/guides/source/working_with_javascript_in_rails.md index 106744d605..011303c311 100644 --- a/guides/source/working_with_javascript.md +++ b/guides/source/working_with_javascript_in_rails.md @@ -1,22 +1,22 @@ -Working With JavaScript -======================= +Working with JavaScript in Rails +================================ This guide covers the built-in Ajax/JavaScript functionality of Rails (and -more); it will enable you to create rich and dynamic AJAX applications with +more); it will enable you to create rich and dynamic Ajax applications with ease! We will cover the following topics: -* Quick introduction to AJAX +* Quick introduction to Ajax * Unobtrusive JavaScript * How Rails' built-in helpers assist you -* Handling AJAX on the server side +* Handling Ajax on the server side * The Turbolinks gem ------------------------------------------------------------------------------- -An introduction to AJAX +An Introduction to Ajax ------------------------ -In order to understand AJAX, you must first understand what a web browser does +In order to understand Ajax, you must first understand what a web browser does normally. When you type `http://localhost:3000` into your browser's address bar and hit @@ -30,16 +30,16 @@ JavaScript can also make requests to the server, and parse the response. It also has the ability to update information on the page. Combining these two powers, a JavaScript writer can make a web page that can update just parts of itself, without needing to get the full page data from the server. This is a -powerful technique that we call AJAX. +powerful technique that we call Ajax. Rails ships with CoffeeScript by default, and so the rest of the examples in this guide will be in CoffeeScript. All of these lessons, of course, apply to vanilla JavaScript as well. -As an example, here's some CoffeeScript code that makes an AJAX request using +As an example, here's some CoffeeScript code that makes an Ajax request using the jQuery library: -``` +```coffeescript $.ajax(url: "/test").done (html) -> $("#results").append html ``` @@ -63,35 +63,35 @@ demonstrate other ways. Here's the simplest way to write JavaScript. You may see it referred to as 'inline JavaScript': -``` +```html <a href="#" onclick="alert('Hello, world.')">Here</a> ``` When clicked, the alert will trigger. Here's the problem: what happens when we have lots of JavaScript we want to execute on a click? -``` +```html <a href="#" onclick="function fib(n){return n<2?n:fib(n-1)+fib(n-2);};alert('fib of 15 is: ' + fib(15) + '.');">Calculate</a> ``` Awkward, right? We could pull the function definition out of the click handler, and turn it into CoffeeScript: -``` +```coffeescript fib = (n) -> (if n < 2 then n else fib(n - 1) + fib(n - 2)) ``` And then on our page: -``` +```html <a href="#" onclick="alert('fib of 15 is: ' + fib(15) + '.');">Calculate</a> ``` That's a little bit better, but what about multiple links that have the same effect? -``` +```html <a href="#" onclick="alert('fib of 16 is: ' + fib(16) + '.');">Calculate</a> <a href="#" onclick="alert('fib of 17 is: ' + fib(17) + '.');">Calculate</a> <a href="#" onclick="alert('fib of 18 is: ' + fib(18) + '.');">Calculate</a> @@ -101,7 +101,7 @@ Not very DRY, eh? We can fix this by using events instead. We'll add a `data-*` attribute to our link, and then bind a handler to the click event of every link that has that attribute: -``` +```coffeescript fib = (n) -> (if n < 2 then n else fib(n - 1) + fib(n - 2)) @@ -133,11 +133,12 @@ Built-in Helpers ---------------------- Rails provides a bunch of view helper methods written in Ruby to assist you -in generating HTML. Sometimes, you want to add a little AJAX to those elements, +in generating HTML. Sometimes, you want to add a little Ajax to those elements, and Rails has got your back in those cases. -Because of Unobtrusive JavaScript, the Rails AJAX helpers actually consist of two -parts: the JavaScript part and the Ruby part. +Because of Unobtrusive JavaScript, the Rails "Ajax helpers" are actually in two +parts: the JavaScript half and the Ruby half. + [rails.js](https://github.com/rails/jquery-ujs/blob/master/src/rails.js) provides the JavaScript half, and the regular Ruby view helpers add appropriate tags to your DOM. The CoffeeScript in rails.js then listens for these @@ -149,7 +150,7 @@ attributes, and attaches appropriate handlers. is a helper that assists with writing forms. `form_for` takes a `:remote` option. It works like this: -``` +```erb <%= form_for(@post, remote: true) do |f| %> ... <% end %> @@ -157,27 +158,25 @@ option. It works like this: This will generate the following HTML: -``` +```html <form accept-charset="UTF-8" action="/posts" class="new_post" data-remote="true" id="new_post" method="post"> ... </form> ``` -Note the `data-remote='true'`. Now, the form will be submitted by AJAX rather +Note the `data-remote='true'`. Now, the form will be submitted by Ajax rather than by the browser's normal submit mechanism. You probably don't want to just sit there with a filled out `<form>`, though. You probably want to do something upon a successful submission. To do that, bind to the `ajax:success` event. On failure, use `ajax:error`. Check it out: -``` -<script> +```coffeescript $(document).ready -> $("#new_post").on("ajax:success", (e, data, status, xhr) -> $("#new_post").append xhr.responseText ).bind "ajax:error", (e, xhr, status, error) -> $("#new_post").append "<p>ERROR</p>" -</script> ``` Obviously, you'll want to be a bit more sophisticated than that, but it's a @@ -189,7 +188,7 @@ start. is very similar to `form_for`. It has a `:remote` option that you can use like this: -``` +```erb <%= form_tag('/posts', remote: true) %> ``` @@ -199,60 +198,59 @@ details. ### link_to [`link_to`](http://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-link_to) -is a helper that assits with generating links. It has a `:remote` option you +is a helper that assists with generating links. It has a `:remote` option you can use like this: -``` +```erb <%= link_to "first post", @post, remote: true %> ``` which generates -``` +```html <a href="/posts/1" data-remote="true">a post</a> ``` -You can bind to the same AJAX events as `form_for`. Here's an example. Let's +You can bind to the same Ajax events as `form_for`. Here's an example. Let's assume that we have a resource `/fib/:n` that calculates the `n`th Fibonacci number. We would generate some HTML like this: -``` +```erb <%= link_to "Calculate", "/fib/15", remote: true, data: { fib: 15 } %> ``` and write some CoffeeScript like this: -``` +```coffeescript $(document).ready -> $("a[data-fib]").on "ajax:success", (e, data, status, xhr) -> count = $(this).data("fib") alert "fib of #{count} is: #{data}." ``` -Easy! - ### button_to [`button_to`](http://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-button_to) is a helper that helps you create buttons. It has a `:remote` option that you can call like this: -``` +```erb <%= button_to "A post", @post, remote: true %> ``` this generates -``` +```html <form action="/posts/1" class="button_to" data-remote="true" method="post"> + <div><input type="submit" value="A post"></div> </form> ``` Since it's just a `<form>`, all of the information on `form_for` also applies. -Server side concerns +Server-Side Concerns -------------------- -AJAX isn't just client-side, you also need to do some work on the server -side to support it. Often, people like their AJAX requests to return JSON +Ajax isn't just client-side, you also need to do some work on the server +side to support it. Often, people like their Ajax requests to return JSON rather than HTML. Let's discuss what it takes to make that happen. ### A Simple Example @@ -261,7 +259,7 @@ Imagine you have a series of users that you would like to display and provide a form on that same page to create a new user. The index action of your controller looks like this: -``` +```ruby class UsersController < ApplicationController def index @users = User.all @@ -272,7 +270,7 @@ class UsersController < ApplicationController The index view (`app/views/users/index.html.erb`) contains: -``` +```erb <b>Users</b> <ul id="users"> @@ -292,7 +290,7 @@ The index view (`app/views/users/index.html.erb`) contains: The `app/views/users/_user.html.erb` partial contains the following: -``` +```erb <li><%= user.name %></li> ``` @@ -301,11 +299,11 @@ provides a form to create a new user. The bottom form will call the create action on the Users controller. Because the form's remote option is set to true, the request will be posted to the -users controller as an AJAX request, looking for JavaScript. In order to +users controller as an Ajax request, looking for JavaScript. In order to service that request, the create action of your controller would look like this: -``` +```ruby # app/controllers/users_controller.rb # ...... def create @@ -325,11 +323,11 @@ this: ``` Notice the format.js in the respond_to block; that allows the controller to -respond to your AJAX request. You then have a corresponding +respond to your Ajax request. You then have a corresponding `app/views/users/create.js.erb` view file that generates the actual JavaScript code that will be sent and executed on the client side. -``` +```erb $("<%= escape_javascript(render @user) %>").appendTo("#users"); ``` @@ -337,14 +335,14 @@ Turbolinks ---------- Rails 4 ships with the [Turbolinks gem](https://github.com/rails/turbolinks). -This gem uses AJAX to speed up page rendering in most applications. +This gem uses Ajax to speed up page rendering in most applications. -### How Turbolinks works +### How Turbolinks Works Turbolinks attaches a click handler to all `<a>` on the page. If your browser supports [PushState](https://developer.mozilla.org/en-US/docs/DOM/Manipulating_the_browser_history#The_pushState(\).C2.A0method), -Turbolinks will make an AJAX request for the page, parse the response, and +Turbolinks will make an Ajax request for the page, parse the response, and replace the entire `<body>` of the page with the `<body>` of the response. It will then use PushState to change the URL to the correct one, preserving refresh semantics and giving you pretty URLs. @@ -356,16 +354,16 @@ and put `//= require turbolinks` in your CoffeeScript manifest, which is usually If you want to disable Turbolinks for certain links, add a `data-no-turbolink` attribute to the tag: -``` +```html <a href="..." data-no-turbolink>No turbolinks here</a>. ``` -### Page Change events +### Page Change Events When writing CoffeeScript, you'll often want to do some sort of processing upon page load. With jQuery, you'd write something like this: -``` +```coffeescript $(document).ready -> alert "page has loaded!" ``` @@ -374,7 +372,7 @@ However, because Turbolinks overrides the normal page loading process, the event that this relies on will not be fired. If you have code that looks like this, you must change your code to do this instead: -``` +```coffeescript $(document).on "page:change", -> alert "page has loaded!" ``` @@ -383,7 +381,7 @@ For more details, including other events you can bind to, check out [the Turbolinks README](https://github.com/rails/turbolinks/blob/ec9ca4d6cf9626e03a672f3b9e7968c816aff94e/README.md). -Other resources +Other Resources --------------- Here are some helpful links to help you learn even more: |