Fix the usage of `*` in Markdown
In Textile `*` would convert to `<strong>`, but in Markdown we have to use `**` instead.
This commit is contained in:
Prem Sichanugrist
parent
721afdcc4b
commit
41dbb58e2d
|
|
@ -60,7 +60,7 @@ $ gem install rack
|
|||
|
||||
Now we'll create a simple "Hello World" application that uses the `titleize` method provided by Active Support.
|
||||
|
||||
*hello_world.rb:*
|
||||
**hello_world.rb:**
|
||||
|
||||
```ruby
|
||||
require 'active_support/core_ext/string/inflections'
|
||||
|
|
@ -94,7 +94,7 @@ $ gem install sinatra
|
|||
|
||||
Now we'll create the same "Hello World" application in Sinatra.
|
||||
|
||||
*hello_world.rb:*
|
||||
**hello_world.rb:**
|
||||
|
||||
```ruby
|
||||
require 'action_view'
|
||||
|
|
@ -344,7 +344,7 @@ Post.create(:body => 'Partial Layouts are cool!')
|
|||
|
||||
In the `show` template, we'll render the `post` partial wrapped in the `box` layout:
|
||||
|
||||
*posts/show.html.erb*
|
||||
**posts/show.html.erb**
|
||||
|
||||
```erb
|
||||
<%= render :partial => 'post', :layout => 'box', :locals => {:post => @post} %>
|
||||
|
|
@ -352,7 +352,7 @@ In the `show` template, we'll render the `post` partial wrapped in the `box` lay
|
|||
|
||||
The `box` layout simply wraps the `post` partial in a `div`:
|
||||
|
||||
*posts/_box.html.erb*
|
||||
**posts/_box.html.erb**
|
||||
|
||||
```html+erb
|
||||
<div class='box'>
|
||||
|
|
@ -362,7 +362,7 @@ The `box` layout simply wraps the `post` partial in a `div`:
|
|||
|
||||
The `post` partial wraps the post's `body` in a `div` with the `id` of the post using the `div_for` helper:
|
||||
|
||||
*posts/_post.html.erb*
|
||||
**posts/_post.html.erb**
|
||||
|
||||
```html+erb
|
||||
<%= div_for(post) do %>
|
||||
|
|
@ -384,7 +384,7 @@ Note that the partial layout has access to the local `post` variable that was pa
|
|||
|
||||
You can also render a block of code within a partial layout instead of calling `yield`. For example, if we didn't have the `post` partial, we could do this instead:
|
||||
|
||||
*posts/show.html.erb*
|
||||
**posts/show.html.erb**
|
||||
|
||||
```html+erb
|
||||
<% render(:layout => 'box', :locals => {:post => @post}) do %>
|
||||
|
|
@ -700,13 +700,13 @@ stylesheet_url "application" # => http://www.example.com/assets/application.css
|
|||
|
||||
This helper makes building an Atom feed easy. Here's a full usage example:
|
||||
|
||||
*config/routes.rb*
|
||||
**config/routes.rb**
|
||||
|
||||
```ruby
|
||||
resources :posts
|
||||
```
|
||||
|
||||
*app/controllers/posts_controller.rb*
|
||||
**app/controllers/posts_controller.rb**
|
||||
|
||||
```ruby
|
||||
def index
|
||||
|
|
@ -719,7 +719,7 @@ def index
|
|||
end
|
||||
```
|
||||
|
||||
*app/views/posts/index.atom.builder*
|
||||
**app/views/posts/index.atom.builder**
|
||||
|
||||
```ruby
|
||||
atom_feed do |feed|
|
||||
|
|
@ -796,7 +796,7 @@ Calling `content_for` stores a block of markup in an identifier for later use. Y
|
|||
|
||||
For example, let's say we have a standard application layout, but also a special page that requires certain JavaScript that the rest of the site doesn't need. We can use `content_for` to include this JavaScript on our special page without fattening up the rest of the site.
|
||||
|
||||
*app/views/layouts/application.html.erb*
|
||||
**app/views/layouts/application.html.erb**
|
||||
|
||||
```html+erb
|
||||
<html>
|
||||
|
|
@ -810,7 +810,7 @@ For example, let's say we have a standard application layout, but also a special
|
|||
</html>
|
||||
```
|
||||
|
||||
*app/views/posts/special.html.erb*
|
||||
**app/views/posts/special.html.erb**
|
||||
|
||||
```html+erb
|
||||
<p>This is a special page.</p>
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ When writing applications using other programming languages or frameworks, it ma
|
|||
|
||||
### Naming Conventions
|
||||
|
||||
By default, Active Record uses some naming conventions to find out how the mapping between models and database tables should be created. Rails will pluralize your class names to find the respective database table. So, for a class `Book`, you should have a database table called *books*. The Rails pluralization mechanisms are very powerful, being capable to pluralize (and singularize) both regular and irregular words. When using class names composed of two or more words, the model class name should follow the Ruby conventions, using the CamelCase form, while the table name must contain the words separated by underscores. Examples:
|
||||
By default, Active Record uses some naming conventions to find out how the mapping between models and database tables should be created. Rails will pluralize your class names to find the respective database table. So, for a class `Book`, you should have a database table called **books**. The Rails pluralization mechanisms are very powerful, being capable to pluralize (and singularize) both regular and irregular words. When using class names composed of two or more words, the model class name should follow the Ruby conventions, using the CamelCase form, while the table name must contain the words separated by underscores. Examples:
|
||||
|
||||
* Database Table - Plural with underscores separating words (e.g., `book_clubs`)
|
||||
* Model Class - Singular with the first letter of each word capitalized (e.g., `BookClub`)
|
||||
|
|
@ -59,8 +59,8 @@ By default, Active Record uses some naming conventions to find out how the mappi
|
|||
|
||||
Active Record uses naming conventions for the columns in database tables, depending on the purpose of these columns.
|
||||
|
||||
* *Foreign keys* - These fields should be named following the pattern `singularized_table_name_id` (e.g., `item_id`, `order_id`). These are the fields that Active Record will look for when you create associations between your models.
|
||||
* *Primary keys* - By default, Active Record will use an integer column named `id` as the table's primary key. When using [Rails Migrations](migrations.html) to create your tables, this column will be automatically created.
|
||||
* **Foreign keys** - These fields should be named following the pattern `singularized_table_name_id` (e.g., `item_id`, `order_id`). These are the fields that Active Record will look for when you create associations between your models.
|
||||
* **Primary keys** - By default, Active Record will use an integer column named `id` as the table's primary key. When using [Rails Migrations](migrations.html) to create your tables, this column will be automatically created.
|
||||
|
||||
There are also some optional column names that will create additional features to Active Record instances:
|
||||
|
||||
|
|
@ -136,7 +136,7 @@ end
|
|||
CRUD: Reading and Writing Data
|
||||
------------------------------
|
||||
|
||||
CRUD is an acronym for the four verbs we use to operate on data: *C*reate, *R*ead, *U*pdate and *D*elete. Active Record automatically creates methods to allow an application to read and manipulate data stored within its tables.
|
||||
CRUD is an acronym for the four verbs we use to operate on data: **C**reate, **R**ead, **U**pdate and **D**elete. Active Record automatically creates methods to allow an application to read and manipulate data stored within its tables.
|
||||
|
||||
### Create
|
||||
|
||||
|
|
|
|||
|
|
@ -352,7 +352,7 @@ The `find_each` method accepts most of the options allowed by the regular `find`
|
|||
|
||||
Two additional options, `:batch_size` and `:start`, are available as well.
|
||||
|
||||
*`:batch_size`*
|
||||
**`:batch_size`**
|
||||
|
||||
The `:batch_size` option allows you to specify the number of records to be retrieved in each batch, before being passed individually to the block. For example, to retrieve records in batches of 5000:
|
||||
|
||||
|
|
@ -362,7 +362,7 @@ User.find_each(:batch_size => 5000) do |user|
|
|||
end
|
||||
```
|
||||
|
||||
*`:start`*
|
||||
**`:start`**
|
||||
|
||||
By default, records are fetched in ascending order of the primary key, which must be an integer. The `:start` option allows you to configure the first ID of the sequence whenever the lowest ID is not the one you need. This would be useful, for example, if you wanted to resume an interrupted batch process, provided you saved the last processed ID as a checkpoint.
|
||||
|
||||
|
|
@ -436,7 +436,7 @@ to this code:
|
|||
Client.where("orders_count = #{params[:orders]}")
|
||||
```
|
||||
|
||||
because of argument safety. Putting the variable directly into the conditions string will pass the variable to the database *as-is*. This means that it will be an unescaped variable directly from a user who may have malicious intent. If you do this, you put your entire database at risk because once a user finds out he or she can exploit your database they can do just about anything to it. Never ever put your arguments directly inside the conditions string.
|
||||
because of argument safety. Putting the variable directly into the conditions string will pass the variable to the database **as-is**. This means that it will be an unescaped variable directly from a user who may have malicious intent. If you do this, you put your entire database at risk because once a user finds out he or she can exploit your database they can do just about anything to it. Never ever put your arguments directly inside the conditions string.
|
||||
|
||||
TIP: For more information on the dangers of SQL injection, see the [Ruby on Rails Security Guide](security.html#sql-injection).
|
||||
|
||||
|
|
@ -747,7 +747,7 @@ The SQL that would be executed:
|
|||
SELECT * FROM clients WHERE orders_count > 10 ORDER BY clients.id DESC
|
||||
```
|
||||
|
||||
This method accepts *no* arguments.
|
||||
This method accepts **no** arguments.
|
||||
|
||||
Null Relation
|
||||
-------------
|
||||
|
|
@ -1085,7 +1085,7 @@ This would generate a query which contains a `LEFT OUTER JOIN` whereas the `join
|
|||
|
||||
If there was no `where` condition, this would generate the normal set of two queries.
|
||||
|
||||
If, in the case of this `includes` query, there were no comments for any posts, all the posts would still be loaded. By using `joins` (an INNER JOIN), the join conditions *must* match, otherwise no records will be returned.
|
||||
If, in the case of this `includes` query, there were no comments for any posts, all the posts would still be loaded. By using `joins` (an INNER JOIN), the join conditions **must** match, otherwise no records will be returned.
|
||||
|
||||
Scopes
|
||||
------
|
||||
|
|
@ -1225,7 +1225,7 @@ You can specify an exclamation point (`!`) on the end of the dynamic finders to
|
|||
|
||||
If you want to find both by name and locked, you can chain these finders together by simply typing "`and`" between the fields. For example, `Client.find_by_first_name_and_locked("Ryan", true)`.
|
||||
|
||||
WARNING: Up to and including Rails 3.1, when the number of arguments passed to a dynamic finder method is lesser than the number of fields, say `Client.find_by_name_and_locked("Ryan")`, the behavior is to pass `nil` as the missing argument. This is *unintentional* and this behavior will be changed in Rails 3.2 to throw an `ArgumentError`.
|
||||
WARNING: Up to and including Rails 3.1, when the number of arguments passed to a dynamic finder method is lesser than the number of fields, say `Client.find_by_name_and_locked("Ryan")`, the behavior is to pass `nil` as the missing argument. This is **unintentional** and this behavior will be changed in Rails 3.2 to throw an `ArgumentError`.
|
||||
|
||||
Find or build a new object
|
||||
--------------------------
|
||||
|
|
|
|||
|
|
@ -551,7 +551,7 @@ Person.new.valid? #=> TokenGenerationException: Token can't be blank
|
|||
Conditional Validation
|
||||
----------------------
|
||||
|
||||
Sometimes it will make sense to validate an object just when a given predicate is satisfied. You can do that by using the `:if` and `:unless` options, which can take a symbol, a string, a `Proc` or an `Array`. You may use the `:if` option when you want to specify when the validation *should* happen. If you want to specify when the validation *should not* happen, then you may use the `:unless` option.
|
||||
Sometimes it will make sense to validate an object just when a given predicate is satisfied. You can do that by using the `:if` and `:unless` options, which can take a symbol, a string, a `Proc` or an `Array`. You may use the `:if` option when you want to specify when the validation **should** happen. If you want to specify when the validation **should not** happen, then you may use the `:unless` option.
|
||||
|
||||
### Using a Symbol with `:if` and `:unless`
|
||||
|
||||
|
|
@ -1152,7 +1152,7 @@ Post destroyed
|
|||
Conditional Callbacks
|
||||
---------------------
|
||||
|
||||
As with validations, we can also make the calling of a callback method conditional on the satisfaction of a given predicate. We can do this using the `:if` and `:unless` options, which can take a symbol, a string, a `Proc` or an `Array`. You may use the `:if` option when you want to specify under which conditions the callback *should* be called. If you want to specify the conditions under which the callback *should not* be called, then you may use the `:unless` option.
|
||||
As with validations, we can also make the calling of a callback method conditional on the satisfaction of a given predicate. We can do this using the `:if` and `:unless` options, which can take a symbol, a string, a `Proc` or an `Array`. You may use the `:if` option when you want to specify under which conditions the callback **should** be called. If you want to specify the conditions under which the callback **should not** be called, then you may use the `:unless` option.
|
||||
|
||||
### Using `:if` and `:unless` with a `Symbol`
|
||||
|
||||
|
|
|
|||
|
|
@ -89,7 +89,7 @@ The following values are considered to be blank in a Rails application:
|
|||
|
||||
INFO: The predicate for strings uses the Unicode-aware character class `[:space:]`, so for example U+2029 (paragraph separator) is considered to be whitespace.
|
||||
|
||||
WARNING: Note that numbers are not mentioned, in particular 0 and 0.0 are *not* blank.
|
||||
WARNING: Note that numbers are not mentioned, in particular 0 and 0.0 are **not** blank.
|
||||
|
||||
For example, this method from `ActionDispatch::Session::AbstractStore` uses `blank?` for checking whether a session key is present:
|
||||
|
||||
|
|
@ -287,7 +287,7 @@ By default `to_param` just calls `to_s`:
|
|||
7.to_param # => "7"
|
||||
```
|
||||
|
||||
The return value of `to_param` should *not* be escaped:
|
||||
The return value of `to_param` should **not** be escaped:
|
||||
|
||||
```ruby
|
||||
"Tom & Jerry".to_param # => "Tom & Jerry"
|
||||
|
|
@ -2007,7 +2007,7 @@ NOTE: Defined in `active_support/core_ext/integer/inflections.rb`.
|
|||
|
||||
### `ordinalize`
|
||||
|
||||
The method `ordinalize` returns the ordinal string corresponding to the receiver integer. In comparison, note that the `ordinal` method returns *only* the suffix string.
|
||||
The method `ordinalize` returns the ordinal string corresponding to the receiver integer. In comparison, note that the `ordinal` method returns **only** the suffix string.
|
||||
|
||||
```ruby
|
||||
1.ordinalize # => "1st"
|
||||
|
|
@ -2110,7 +2110,7 @@ NOTE: Defined in `active_support/core_ext/enumerable.rb`.
|
|||
|
||||
### `exclude?`
|
||||
|
||||
The predicate `exclude?` tests whether a given object does *not* belong to the collection. It is the negation of the built-in `include?`:
|
||||
The predicate `exclude?` tests whether a given object does **not** belong to the collection. It is the negation of the built-in `include?`:
|
||||
|
||||
```ruby
|
||||
to_visit << node if visited.exclude?(node)
|
||||
|
|
@ -3330,7 +3330,7 @@ date.end_of_hour # => Mon Jun 07 19:59:59 +0200 2010
|
|||
|
||||
`beginning_of_hour` is aliased to `at_beginning_of_hour`.
|
||||
|
||||
INFO: `beginning_of_hour` and `end_of_hour` are implemented for `Time` and `DateTime` but *not* `Date` as it does not make sense to request the beginning or end of an hour on a `Date` instance.
|
||||
INFO: `beginning_of_hour` and `end_of_hour` are implemented for `Time` and `DateTime` but **not** `Date` as it does not make sense to request the beginning or end of an hour on a `Date` instance.
|
||||
|
||||
##### `ago`, `since`
|
||||
|
||||
|
|
@ -3389,7 +3389,7 @@ prev_year (last_year)
|
|||
next_year
|
||||
```
|
||||
|
||||
The following methods are reimplemented so you do *not* need to load `active_support/core_ext/date/calculations.rb` for these ones:
|
||||
The following methods are reimplemented so you do **not** need to load `active_support/core_ext/date/calculations.rb` for these ones:
|
||||
|
||||
```ruby
|
||||
beginning_of_day (midnight, at_midnight, at_beginning_of_day)
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ Introduction to instrumentation
|
|||
|
||||
The instrumentation API provided by ActiveSupport allows developers to provide hooks which other developers may hook into. There are several of these within the Rails framework, as described below in <TODO: link to section detailing each hook point>. With this API, developers can choose to be notified when certain events occur inside their application or another piece of Ruby code.
|
||||
|
||||
For example, there is a hook provided within Active Record that is called every time Active Record uses an SQL query on a database. This hook could be *subscribed* to, and used to track the number of queries during a certain action. There's another hook around the processing of an action of a controller. This could be used, for instance, to track how long a specific action has taken.
|
||||
For example, there is a hook provided within Active Record that is called every time Active Record uses an SQL query on a database. This hook could be **subscribed** to, and used to track the number of queries during a certain action. There's another hook around the processing of an action of a controller. This could be used, for instance, to track how long a specific action has taken.
|
||||
|
||||
You are even able to create your own events inside your application which you can later subscribe to.
|
||||
|
||||
|
|
|
|||
|
|
@ -240,7 +240,7 @@ link to your view so this is the default behavior. However, sometimes you'll wan
|
|||
* `:loaded:` => `code` The transfer is completed, but the data is not processed and returned yet
|
||||
* `:interactive:` => `code` One step after `:loaded`: The data is fully received and being processed
|
||||
* `:success:` => `code` The data is fully received, parsed and the server responded with "200 OK"
|
||||
* `:failure:` => `code` The data is fully received, parsed and the server responded with *anything* but "200 OK" (typically 404 or 500, but in general with any status code ranging from 100 to 509)
|
||||
* `:failure:` => `code` The data is fully received, parsed and the server responded with **anything** but "200 OK" (typically 404 or 500, but in general with any status code ranging from 100 to 509)
|
||||
* `:complete:` => `code` The combination of the previous two: The request has finished receiving and parsing the data, and returned a status code (which can be anything).
|
||||
* Any other status code ranging from 100 to 509: Additionally you might want to check for other HTTP status codes, such as 404. In this case simply use the status code as a number:
|
||||
|
||||
|
|
|
|||
|
|
@ -135,7 +135,7 @@ class Array
|
|||
end
|
||||
```
|
||||
|
||||
WARNING: Using a pair of `+...+` for fixed-width font only works with *words*; that is: anything matching `\A\w+\z`. For anything else use `<tt>...</tt>`, notably symbols, setters, inline snippets, etc.
|
||||
WARNING: Using a pair of `+...+` for fixed-width font only works with **words**; that is: anything matching `\A\w+\z`. For anything else use `<tt>...</tt>`, notably symbols, setters, inline snippets, etc.
|
||||
|
||||
### Regular Font
|
||||
|
||||
|
|
|
|||
|
|
@ -406,7 +406,7 @@ $ bundle exec rake assets:precompile
|
|||
|
||||
For faster asset precompiles, you can partially load your application by setting
|
||||
`config.assets.initialize_on_precompile` to false in `config/application.rb`, though in that case templates
|
||||
cannot see application objects or methods. *Heroku requires this to be false.*
|
||||
cannot see application objects or methods. **Heroku requires this to be false.**
|
||||
|
||||
WARNING: If you set `config.assets.initialize_on_precompile` to false, be sure to
|
||||
test `rake assets:precompile` locally before deploying. It may expose bugs where
|
||||
|
|
@ -433,7 +433,7 @@ The default matcher for compiling files includes `application.js`, `application.
|
|||
[ Proc.new{ |path| !%w(.js .css).include?(File.extname(path)) }, /application.(css|js)$/ ]
|
||||
```
|
||||
|
||||
NOTE. The matcher (and other members of the precompile array; see below) is applied to final compiled file names. This means that anything that compiles to JS/CSS is excluded, as well as raw JS/CSS files; for example, `.coffee` and `.scss` files are *not* automatically included as they compile to JS/CSS.
|
||||
NOTE. The matcher (and other members of the precompile array; see below) is applied to final compiled file names. This means that anything that compiles to JS/CSS is excluded, as well as raw JS/CSS files; for example, `.coffee` and `.scss` files are **not** automatically included as they compile to JS/CSS.
|
||||
|
||||
If you have other manifests or individual stylesheets and JavaScript files to include, you can add them to the `precompile` array:
|
||||
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ Rails:
|
|||
|
||||
NOTE: You can install more generators through generator gems, portions of plugins you'll undoubtedly install, and you can even create your own!
|
||||
|
||||
Using generators will save you a large amount of time by writing *boilerplate code*, code that is necessary for the app to work.
|
||||
Using generators will save you a large amount of time by writing **boilerplate code**, code that is necessary for the app to work.
|
||||
|
||||
Let's make our own controller with the controller generator. But what command should we use? Let's ask the generator:
|
||||
|
||||
|
|
@ -140,7 +140,7 @@ Example:
|
|||
Helper: app/helpers/credit_card_helper.rb
|
||||
```
|
||||
|
||||
The controller generator is expecting parameters in the form of `generate controller ControllerName action1 action2`. Let's make a `Greetings` controller with an action of *hello*, which will say something nice to us.
|
||||
The controller generator is expecting parameters in the form of `generate controller ControllerName action1 action2`. Let's make a `Greetings` controller with an action of **hello**, which will say something nice to us.
|
||||
|
||||
```bash
|
||||
$ rails generate controller Greetings hello
|
||||
|
|
@ -190,7 +190,7 @@ $ rails server
|
|||
|
||||
The URL will be [http://localhost:3000/greetings/hello](http://localhost:3000/greetings/hello).
|
||||
|
||||
INFO: With a normal, plain-old Rails application, your URLs will generally follow the pattern of http://(host)/(controller)/(action), and a URL like http://(host)/(controller) will hit the *index* action of that controller.
|
||||
INFO: With a normal, plain-old Rails application, your URLs will generally follow the pattern of http://(host)/(controller)/(action), and a URL like http://(host)/(controller) will hit the **index** action of that controller.
|
||||
|
||||
Rails comes with a generator for data models too.
|
||||
|
||||
|
|
@ -213,7 +213,7 @@ Description:
|
|||
|
||||
NOTE: For a list of available field types, refer to the [API documentation](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html#method-i-column) for the column method for the `TableDefinition` class.
|
||||
|
||||
But instead of generating a model directly (which we'll be doing later), let's set up a scaffold. A *scaffold* in Rails is a full set of model, database migration for that model, controller to manipulate it, views to view and manipulate the data, and a test suite for each of the above.
|
||||
But instead of generating a model directly (which we'll be doing later), let's set up a scaffold. A **scaffold** in Rails is a full set of model, database migration for that model, controller to manipulate it, views to view and manipulate the data, and a test suite for each of the above.
|
||||
|
||||
We will set up a simple resource called "HighScore" that will keep track of our highest score on video games we play.
|
||||
|
||||
|
|
@ -250,9 +250,9 @@ $ rails generate scaffold HighScore game:string score:integer
|
|||
create app/assets/stylesheets/scaffolds.css.scss
|
||||
```
|
||||
|
||||
The generator checks that there exist the directories for models, controllers, helpers, layouts, functional and unit tests, stylesheets, creates the views, controller, model and database migration for HighScore (creating the `high_scores` table and fields), takes care of the route for the *resource*, and new tests for everything.
|
||||
The generator checks that there exist the directories for models, controllers, helpers, layouts, functional and unit tests, stylesheets, creates the views, controller, model and database migration for HighScore (creating the `high_scores` table and fields), takes care of the route for the **resource**, and new tests for everything.
|
||||
|
||||
The migration requires that we *migrate*, that is, run some Ruby code (living in that `20120528060026_create_high_scores.rb`) to modify the schema of our database. Which database? The sqlite3 database that Rails will create for you when we run the `rake db:migrate` command. We'll talk more about Rake in-depth in a little while.
|
||||
The migration requires that we **migrate**, that is, run some Ruby code (living in that `20120528060026_create_high_scores.rb`) to modify the schema of our database. Which database? The sqlite3 database that Rails will create for you when we run the `rake db:migrate` command. We'll talk more about Rake in-depth in a little while.
|
||||
|
||||
```bash
|
||||
$ rake db:migrate
|
||||
|
|
@ -563,7 +563,7 @@ add 'app/controllers/application_controller.rb'
|
|||
add 'log/test.log'
|
||||
```
|
||||
|
||||
We had to create the *gitapp* directory and initialize an empty git repository before Rails would add files it created to our repository. Let's see what it put in our database configuration:
|
||||
We had to create the **gitapp** directory and initialize an empty git repository before Rails would add files it created to our repository. Let's see what it put in our database configuration:
|
||||
|
||||
```bash
|
||||
$ cat config/database.yml
|
||||
|
|
|
|||
|
|
@ -314,7 +314,7 @@ Ruby on Rails has two main sets of documentation: the guides help you in learnin
|
|||
|
||||
You can help improve the Rails guides by making them more coherent, consistent or readable, adding missing information, correcting factual errors, fixing typos, or bringing it up to date with the latest edge Rails. To get involved in the translation of Rails guides, please see [Translating Rails Guides](https://wiki.github.com/lifo/docrails/translating-rails-guides).
|
||||
|
||||
If you're confident about your changes, you can push them directly yourself via [docrails](https://github.com/lifo/docrails). Docrails is a branch with an *open commit policy* and public write access. Commits to docrails are still reviewed, but this happens after they are pushed. Docrails is merged with master regularly, so you are effectively editing the Ruby on Rails documentation.
|
||||
If you're confident about your changes, you can push them directly yourself via [docrails](https://github.com/lifo/docrails). Docrails is a branch with an **open commit policy** and public write access. Commits to docrails are still reviewed, but this happens after they are pushed. Docrails is merged with master regularly, so you are effectively editing the Ruby on Rails documentation.
|
||||
|
||||
If you are unsure of the documentation changes, you can create an issue in the [Rails](https://github.com/rails/rails/issues) issues tracker on GitHub.
|
||||
|
||||
|
|
|
|||
|
|
@ -431,7 +431,7 @@ true
|
|||
|
||||
Now `@posts` is included in the instance variables, because the line defining it was executed.
|
||||
|
||||
TIP: You can also step into *irb* mode with the command `irb` (of course!). This way an irb session will be started within the context you invoked it. But be warned: this is an experimental feature.
|
||||
TIP: You can also step into **irb** mode with the command `irb` (of course!). This way an irb session will be started within the context you invoked it. But be warned: this is an experimental feature.
|
||||
|
||||
The `var` method is the most convenient way to show variables and their values:
|
||||
|
||||
|
|
|
|||
|
|
@ -18,13 +18,13 @@ Engines can be considered miniature applications that provide functionality to t
|
|||
|
||||
Therefore, engines and applications can be thought of almost the same thing, just with very minor differences, as you'll see throughout this guide. Engines and applications also share a common structure.
|
||||
|
||||
Engines are also closely related to plugins where the two share a common `lib` directory structure and are both generated using the `rails plugin new` generator. The difference being that an engine is considered a "full plugin" by Rails as indicated by the `--full` option that's passed to the generator command, but this guide will refer to them simply as "engines" throughout. An engine *can* be a plugin, and a plugin *can* be an engine.
|
||||
Engines are also closely related to plugins where the two share a common `lib` directory structure and are both generated using the `rails plugin new` generator. The difference being that an engine is considered a "full plugin" by Rails as indicated by the `--full` option that's passed to the generator command, but this guide will refer to them simply as "engines" throughout. An engine **can** be a plugin, and a plugin **can** be an engine.
|
||||
|
||||
The engine that will be created in this guide will be called "blorgh". The engine will provide blogging functionality to its host applications, allowing for new posts and comments to be created. At the beginning of this guide, you will be working solely within the engine itself, but in later sections you'll see how to hook it into an application.
|
||||
|
||||
Engines can also be isolated from their host applications. This means that an application is able to have a path provided by a routing helper such as `posts_path` and use an engine also that provides a path also called `posts_path`, and the two would not clash. Along with this, controllers, models and table names are also namespaced. You'll see how to do this later in this guide.
|
||||
|
||||
It's important to keep in mind at all times that the application should *always* take precedence over its engines. An application is the object that has final say in what goes on in the universe (with the universe being the application's environment) where the engine should only be enhancing it, rather than changing it drastically.
|
||||
It's important to keep in mind at all times that the application should **always** take precedence over its engines. An application is the object that has final say in what goes on in the universe (with the universe being the application's environment) where the engine should only be enhancing it, rather than changing it drastically.
|
||||
|
||||
To see demonstrations of other engines, check out [Devise](https://github.com/plataformatec/devise), an engine that provides authentication for its parent applications, or [Forem](https://github.com/radar/forem), an engine that provides forum functionality. There's also [Spree](https://github.com/spree/spree) which provides an e-commerce platform, and [RefineryCMS](https://github.com/resolve/refinerycms), a CMS engine.
|
||||
|
||||
|
|
@ -88,7 +88,7 @@ By inheriting from the `Rails::Engine` class, this gem notifies Rails that there
|
|||
|
||||
The `isolate_namespace` method here deserves special notice. This call is responsible for isolating the controllers, models, routes and other things into their own namespace, away from similar components inside the application. Without this, there is a possibility that the engine's components could "leak" into the application, causing unwanted disruption, or that important engine components could be overridden by similarly named things within the application. One of the examples of such conflicts are helpers. Without calling `isolate_namespace`, engine's helpers would be included in an application's controllers.
|
||||
|
||||
NOTE: It is *highly* recommended that the `isolate_namespace` line be left within the `Engine` class definition. Without it, classes generated in an engine *may* conflict with an application.
|
||||
NOTE: It is **highly** recommended that the `isolate_namespace` line be left within the `Engine` class definition. Without it, classes generated in an engine **may** conflict with an application.
|
||||
|
||||
What this isolation of the namespace means is that a model generated by a call to `rails g model` such as `rails g model post` won't be called `Post`, but instead be namespaced and called `Blorgh::Post`. In addition, the table for the model is namespaced, becoming `blorgh_posts`, rather than simply `posts`. Similar to the model namespacing, a controller called `PostsController` becomes `Blorgh::PostsController` and the views for that controller will not be at `app/views/posts`, but `app/views/blorgh/posts` instead. Mailers are namespaced as well.
|
||||
|
||||
|
|
@ -645,7 +645,7 @@ A matter worth taking into consideration when writing functional tests is that t
|
|||
get :index
|
||||
```
|
||||
|
||||
It may not function correctly. This is because the application doesn't know how to route these requests to the engine unless you explicitly tell it *how*. To do this, you must pass the `:use_route` option (as a parameter) on these requests also:
|
||||
It may not function correctly. This is because the application doesn't know how to route these requests to the engine unless you explicitly tell it **how**. To do this, you must pass the `:use_route` option (as a parameter) on these requests also:
|
||||
|
||||
```ruby
|
||||
get :index, :use_route => :blorgh
|
||||
|
|
@ -829,7 +829,7 @@ If you wish to reference the application inside the engine in a similar way, use
|
|||
<%= link_to "Home", main_app.root_path %>
|
||||
```
|
||||
|
||||
If you were to use this inside an engine, it would *always* go to the application's root. If you were to leave off the `main_app` "routing proxy" method call, it could potentially go to the engine's or application's root, depending on where it was called from.
|
||||
If you were to use this inside an engine, it would **always** go to the application's root. If you were to leave off the `main_app` "routing proxy" method call, it could potentially go to the engine's or application's root, depending on where it was called from.
|
||||
|
||||
If a template is rendered from within an engine and it's attempting to use one of the application's routing helper methods, it may result in an undefined method call. If you encounter such an issue, ensure that you're not attempting to call the application's routing methods without the `main_app` prefix from within the engine.
|
||||
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ When called without arguments like this, it creates a `<form>` tag which, when s
|
|||
</form>
|
||||
```
|
||||
|
||||
Now, you'll notice that the HTML contains something extra: a `div` element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name `utf8` enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are "GET" or "POST". The second input element with name `authenticity_token` is a security feature of Rails called *cross-site request forgery protection*, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the [Security Guide](./security.html#cross-site-request-forgery-csrf).
|
||||
Now, you'll notice that the HTML contains something extra: a `div` element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name `utf8` enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are "GET" or "POST". The second input element with name `authenticity_token` is a security feature of Rails called **cross-site request forgery protection**, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the [Security Guide](./security.html#cross-site-request-forgery-csrf).
|
||||
|
||||
NOTE: Throughout this guide, the `div` with the hidden input elements will be excluded from code samples for brevity.
|
||||
|
||||
|
|
@ -247,8 +247,8 @@ There are a few things to note here:
|
|||
|
||||
* `@article` is the actual object being edited.
|
||||
* There is a single hash of options. Routing options are passed in the `:url` hash, HTML options are passed in the `:html` hash. Also you can provide a `:namespace` option for your form to ensure uniqueness of id attributes on form elements. The namespace attribute will be prefixed with underscore on the generated HTML id.
|
||||
* The `form_for` method yields a *form builder* object (the `f` variable).
|
||||
* Methods to create form controls are called *on* the form builder object `f`
|
||||
* The `form_for` method yields a **form builder** object (the `f` variable).
|
||||
* Methods to create form controls are called **on** the form builder object `f`
|
||||
|
||||
The resulting HTML is:
|
||||
|
||||
|
|
@ -288,7 +288,7 @@ The object yielded by `fields_for` is a form builder like the one yielded by `fo
|
|||
|
||||
### Relying on Record Identification
|
||||
|
||||
The Article model is directly available to users of the application, so -- following the best practices for developing with Rails -- you should declare it *a resource*:
|
||||
The Article model is directly available to users of the application, so -- following the best practices for developing with Rails -- you should declare it **a resource**:
|
||||
|
||||
```ruby
|
||||
resources :articles
|
||||
|
|
@ -296,7 +296,7 @@ resources :articles
|
|||
|
||||
TIP: Declaring a resource has a number of side-affects. See [Rails Routing From the Outside In](routing.html#resource-routing-the-rails-default) for more information on setting up and using resources.
|
||||
|
||||
When dealing with RESTful resources, calls to `form_for` can get significantly easier if you rely on *record identification*. In short, you can just pass the model instance and have Rails figure out model name and the rest:
|
||||
When dealing with RESTful resources, calls to `form_for` can get significantly easier if you rely on **record identification**. In short, you can just pass the model instance and have Rails figure out model name and the rest:
|
||||
|
||||
```ruby
|
||||
## Creating a new article
|
||||
|
|
@ -469,7 +469,7 @@ Generating options tags with `options_for_select` requires that you create an ar
|
|||
<%= options_for_select(cities_array) %>
|
||||
```
|
||||
|
||||
This is a perfectly valid solution, but Rails provides a less verbose alternative: `options_from_collection_for_select`. This helper expects a collection of arbitrary objects and two additional arguments: the names of the methods to read the option *value* and *text* from, respectively:
|
||||
This is a perfectly valid solution, but Rails provides a less verbose alternative: `options_from_collection_for_select`. This helper expects a collection of arbitrary objects and two additional arguments: the names of the methods to read the option **value** and **text** from, respectively:
|
||||
|
||||
```erb
|
||||
<%= options_from_collection_for_select(City.all, :id, :name) %>
|
||||
|
|
@ -580,7 +580,7 @@ will produce the same output if the current year is 2009 and the value chosen by
|
|||
Uploading Files
|
||||
---------------
|
||||
|
||||
A common task is uploading some sort of file, whether it's a picture of a person or a CSV file containing data to process. The most important thing to remember with file uploads is that the rendered form's encoding *MUST* be set to "multipart/form-data". If you use `form_for`, this is done automatically. If you use `form_tag`, you must set it yourself, as per the following example.
|
||||
A common task is uploading some sort of file, whether it's a picture of a person or a CSV file containing data to process. The most important thing to remember with file uploads is that the rendered form's encoding **MUST** be set to "multipart/form-data". If you use `form_for`, this is done automatically. If you use `form_tag`, you must set it yourself, as per the following example.
|
||||
|
||||
The following two forms both upload a file.
|
||||
|
||||
|
|
|
|||
|
|
@ -879,7 +879,7 @@ but will be very soon.
|
|||
|
||||
The `:method => :put` option tells Rails that we want this form to be
|
||||
submitted via the `PUT`, HTTP method which is the HTTP method you're expected to use to
|
||||
*update* resources according to the REST protocol.
|
||||
**update** resources according to the REST protocol.
|
||||
|
||||
TIP: By default forms built with the +form_for_ helper are sent via `POST`.
|
||||
|
||||
|
|
@ -1183,7 +1183,7 @@ put "posts/:id" => "posts#update"
|
|||
delete "posts/:id" => "posts#destroy"
|
||||
```
|
||||
|
||||
That's a lot to type for covering a single *resource*. Fortunately,
|
||||
That's a lot to type for covering a single **resource**. Fortunately,
|
||||
Rails provides a `resources` method which can be used to declare a
|
||||
standard REST resource. Here's how `config/routes.rb` looks after the
|
||||
cleanup:
|
||||
|
|
|
|||
|
|
@ -341,7 +341,7 @@ def opt_parser
|
|||
end
|
||||
```
|
||||
|
||||
The class *is* defined in `Rack::Server`, but is overwritten in `Rails::Server` to take different arguments. Its `parse!` method begins like this:
|
||||
The class **is** defined in `Rack::Server`, but is overwritten in `Rails::Server` to take different arguments. Its `parse!` method begins like this:
|
||||
|
||||
```ruby
|
||||
def parse!(args)
|
||||
|
|
@ -509,7 +509,7 @@ This file begins with requiring `config/application.rb`.
|
|||
|
||||
### `config/application.rb`
|
||||
|
||||
This file requires `config/boot.rb`, but only if it hasn't been required before, which would be the case in `rails server` but *wouldn't* be the case with Passenger.
|
||||
This file requires `config/boot.rb`, but only if it hasn't been required before, which would be the case in `rails server` but **wouldn't** be the case with Passenger.
|
||||
|
||||
Then the fun begins!
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ In this guide you will:
|
|||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
NOTE: This guide assumes the user knows how to use the [Rails form helpers](form_helpers.html) in general. Also, it’s *not* an API reference. For a complete reference please visit [the Rails API documentation](http://api.rubyonrails.org/).
|
||||
NOTE: This guide assumes the user knows how to use the [Rails form helpers](form_helpers.html) in general. Also, it’s **not** an API reference. For a complete reference please visit [the Rails API documentation](http://api.rubyonrails.org/).
|
||||
|
||||
|
||||
Model setup
|
||||
|
|
|
|||
|
|
@ -177,7 +177,7 @@ Performance tests can be run in two modes: Benchmarking and Profiling.
|
|||
#### Benchmarking
|
||||
|
||||
Benchmarking makes it easy to quickly gather a few metrics about each test run.
|
||||
By default, each test case is run *4 times* in benchmarking mode.
|
||||
By default, each test case is run **4 times** in benchmarking mode.
|
||||
|
||||
To run performance tests in benchmarking mode:
|
||||
|
||||
|
|
@ -190,7 +190,7 @@ $ rake test:benchmark
|
|||
Profiling allows you to make an in-depth analysis of each of your tests by using
|
||||
an external profiler. Depending on your Ruby interpreter, this profiler can be
|
||||
native (Rubinius, JRuby) or not (MRI, which uses RubyProf). By default, each
|
||||
test case is run *once* in profiling mode.
|
||||
test case is run **once** in profiling mode.
|
||||
|
||||
To run performance tests in profiling mode:
|
||||
|
||||
|
|
@ -265,7 +265,7 @@ GC Time measures the amount of time spent in GC for the performance test case.
|
|||
| **JRuby** | yes | no | no | no | no | no | no | no |
|
||||
|
||||
NOTE: To profile under JRuby you'll need to run `export JRUBY_OPTS="-Xlaunch.inproc=false --profile.api"`
|
||||
*before* the performance tests.
|
||||
**before** the performance tests.
|
||||
|
||||
### Understanding the Output
|
||||
|
||||
|
|
|
|||
|
|
@ -95,7 +95,7 @@ creates seven different routes in your application, all mapping to the `Photos`
|
|||
| PATCH/PUT | /photos/:id | update | update a specific photo |
|
||||
| DELETE | /photos/:id | destroy | delete a specific photo |
|
||||
|
||||
NOTE: Rails routes are matched in the order they are specified, so if you have a `resources :photos` above a `get 'photos/poll'` the `show` action's route for the `resources` line will be matched before the `get` line. To fix this, move the `get` line *above* the `resources` line so that it is matched first.
|
||||
NOTE: Rails routes are matched in the order they are specified, so if you have a `resources :photos` above a `get 'photos/poll'` the `show` action's route for the `resources` line will be matched before the `get` line. To fix this, move the `get` line **above** the `resources` line so that it is matched first.
|
||||
|
||||
### Paths and URLs
|
||||
|
||||
|
|
@ -901,7 +901,7 @@ Rails offers facilities for inspecting and testing your routes.
|
|||
|
||||
### Seeing Existing Routes
|
||||
|
||||
To get a complete list of the available routes in your application, visit `http://localhost:3000/rails/info/routes` in your browser while your server is running in the *development* environment. You can also execute the `rake routes` command in your terminal to produce the same output.
|
||||
To get a complete list of the available routes in your application, visit `http://localhost:3000/rails/info/routes` in your browser while your server is running in the **development** environment. You can also execute the `rake routes` command in your terminal to produce the same output.
|
||||
|
||||
Both methods will list all of your routes, in the same order that they appear in `routes.rb`. For each route, you'll see:
|
||||
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ HTML Guides
|
|||
|
||||
### Generation
|
||||
|
||||
To generate all the guides, just `cd` into the *`guides`* directory and execute:
|
||||
To generate all the guides, just `cd` into the **`guides`** directory and execute:
|
||||
|
||||
```
|
||||
bundle exec rake guides:generate
|
||||
|
|
|
|||
|
|
@ -199,11 +199,11 @@ NOTE: _First, as is required by the W3C, use GET and POST appropriately. Secondl
|
|||
|
||||
The HTTP protocol basically provides two main types of requests - GET and POST (and more, but they are not supported by most browsers). The World Wide Web Consortium (W3C) provides a checklist for choosing HTTP GET or POST:
|
||||
|
||||
*Use GET if:*
|
||||
**Use GET if:**
|
||||
|
||||
* The interaction is more _like a question_ (i.e., it is a safe operation such as a query, read operation, or lookup).
|
||||
|
||||
*Use POST if:*
|
||||
**Use POST if:**
|
||||
|
||||
* The interaction is more _like an order_, or
|
||||
* The interaction _changes the state_ of the resource in a way that the user would perceive (e.g., a subscription to a service), or
|
||||
|
|
@ -236,7 +236,7 @@ There are many other possibilities, including Ajax to attack the victim in the b
|
|||
protect_from_forgery :secret => "123456789012345678901234567890..."
|
||||
```
|
||||
|
||||
This will automatically include a security token, calculated from the current session and the server-side secret, in all forms and Ajax requests generated by Rails. You won't need the secret, if you use CookieStorage as session storage. If the security token doesn't match what was expected, the session will be reset. *Note:* In Rails versions prior to 3.0.4, this raised an `ActionController::InvalidAuthenticityToken` error.
|
||||
This will automatically include a security token, calculated from the current session and the server-side secret, in all forms and Ajax requests generated by Rails. You won't need the secret, if you use CookieStorage as session storage. If the security token doesn't match what was expected, the session will be reset. **Note:** In Rails versions prior to 3.0.4, this raised an `ActionController::InvalidAuthenticityToken` error.
|
||||
|
||||
It is common to use persistent cookies to store user information, with `cookies.permanent` for example. In this case, the cookies will not be cleared and the out of the box CSRF protection will not be effective. If you are using a different cookie store than the session for this information, you must handle what to do with it yourself:
|
||||
|
||||
|
|
@ -346,13 +346,13 @@ Intranet and administration interfaces are popular attack targets, because they
|
|||
|
||||
In 2007 there was the first tailor-made trojan which stole information from an Intranet, namely the "Monster for employers" web site of Monster.com, an online recruitment web application. Tailor-made Trojans are very rare, so far, and the risk is quite low, but it is certainly a possibility and an example of how the security of the client host is important, too. However, the highest threat to Intranet and Admin applications are XSS and CSRF.
|
||||
|
||||
*XSS* If your application re-displays malicious user input from the extranet, the application will be vulnerable to XSS. User names, comments, spam reports, order addresses are just a few uncommon examples, where there can be XSS.
|
||||
**XSS** If your application re-displays malicious user input from the extranet, the application will be vulnerable to XSS. User names, comments, spam reports, order addresses are just a few uncommon examples, where there can be XSS.
|
||||
|
||||
Having one single place in the admin interface or Intranet, where the input has not been sanitized, makes the entire application vulnerable. Possible exploits include stealing the privileged administrator's cookie, injecting an iframe to steal the administrator's password or installing malicious software through browser security holes to take over the administrator's computer.
|
||||
|
||||
Refer to the Injection section for countermeasures against XSS. It is _recommended to use the SafeErb plugin_ also in an Intranet or administration interface.
|
||||
|
||||
*CSRF* Cross-Site Reference Forgery (CSRF) is a gigantic attack method, it allows the attacker to do everything the administrator or Intranet user may do. As you have already seen above how CSRF works, here are a few examples of what attackers can do in the Intranet or admin interface.
|
||||
**CSRF** Cross-Site Reference Forgery (CSRF) is a gigantic attack method, it allows the attacker to do everything the administrator or Intranet user may do. As you have already seen above how CSRF works, here are a few examples of what attackers can do in the Intranet or admin interface.
|
||||
|
||||
A real-world example is a [router reconfiguration by CSRF](http://www.h-online.com/security/Symantec-reports-first-active-attack-on-a-DSL-router--/news/102352). The attackers sent a malicious e-mail, with CSRF in it, to Mexican users. The e-mail claimed there was an e-card waiting for them, but it also contained an image tag that resulted in a HTTP-GET request to reconfigure the user's router (which is a popular model in Mexico). The request changed the DNS-settings so that requests to a Mexico-based banking site would be mapped to the attacker's site. Everyone who accessed the banking site through that router saw the attacker's fake web site and had his credentials stolen.
|
||||
|
||||
|
|
@ -600,7 +600,7 @@ Ruby uses a slightly different approach than many other languages to match the e
|
|||
/^https?:\/\/[^\n]+$/i
|
||||
```
|
||||
|
||||
This may work fine in some languages. However, _in Ruby ^ and $ match the *line* beginning and line end_. And thus a URL like this passes the filter without problems:
|
||||
This may work fine in some languages. However, _in Ruby ^ and $ match the **line** beginning and line end_. And thus a URL like this passes the filter without problems:
|
||||
|
||||
```
|
||||
javascript:exploit_code();/*
|
||||
|
|
@ -629,7 +629,7 @@ Since this is a frequent mistake, the format validator (validates_format_of) now
|
|||
validates :content, :format => { :with => /^Meanwhile$/, :multiline => true }
|
||||
```
|
||||
|
||||
Note that this only protects you against the most common mistake when using the format validator - you always need to keep in mind that ^ and $ match the *line* beginning and line end in Ruby, and not the beginning and end of a string.
|
||||
Note that this only protects you against the most common mistake when using the format validator - you always need to keep in mind that ^ and $ match the **line** beginning and line end in Ruby, and not the beginning and end of a string.
|
||||
|
||||
### Privilege Escalation
|
||||
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ You'll find fixtures under your `test/fixtures` directory. When you run `rails g
|
|||
|
||||
#### YAML
|
||||
|
||||
YAML-formatted fixtures are a very human-friendly way to describe your sample data. These types of fixtures have the *.yml* file extension (as in `users.yml`).
|
||||
YAML-formatted fixtures are a very human-friendly way to describe your sample data. These types of fixtures have the **.yml** file extension (as in `users.yml`).
|
||||
|
||||
Here's a sample YAML fixture file:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue