@@ -56,6 +56,7 @@ so this book can help the community as a whole. [Matt Aimonetti][], Merb Core team member + [Apress]: http://www.apress.com/ [Beginning Merb]: http://www.apress.com/book/view/9781430218234 [DataMapper]: http://datamapper.org/doku.php book-content/en/0-front-matter/1-preface.markdown @@ -153,6 +153,7 @@ During RubyConf 2008, Matz made a comment about Merb: {: cite=http://merbist.com/2008/11/09/merb-1-0-released/} + [Ada]: http://en.wikipedia.org/wiki/Ada_%28programming_language%29) [Dave Thomas]: http://pragdave.pragprog.com/ [dynamic]: http://en.wikipedia.org/wiki/Dynamic book-content/en/1-introduction/1-ruby.markdown @@ -1,21 +1,29 @@ # Merb Merb is the brainchild of [Ezra Zygmuntowicz][]. -The very first 'public' version of Merb appeared as a pastie on September 21st, 2006[^first-pastie]. -You can find this pastie [here](http://pastie.org/14416) or [here](http://gist.github.com/33252) -(mirror). Currently, the lead developer of the Merb project is [Yehuda Katz](http://yehudakatz.com/). +The very first 'public' version of Merb appeared as a pastie +on September 21st, 2006[^first-pastie]. +You can find this pastie [here](http://pastie.org/14416) +or [here](http://gist.github.com/33252) (mirror). +Currently, the lead developer of the Merb project is [Yehuda Katz][]. -Starting with version 0.9 of the framework, all of the essential functionality was -put into 'merb-core', with the remaining extra functionality moved to other -components (such as merb-haml and merb-helpers). -Version 1.0 was announced at [RubyConf](http://rubyconf.org/) on November 7th, 2008. - -The main source code repository is located on [Github](http://github.com/wycats/merb/). +Starting with version 0.9 of the framework, +all of the essential functionality was put into 'merb-core', +with the remaining extra functionality moved to other components +(such as merb-haml and merb-helpers). +Version 1.0 was announced at [RubyConf][] on November 7th, 2008. +Merb is maintained using [Git][], a distributed version control system. +The main source code [repository][] is located on [Github][].  -[Ezra Zygmuntowicz]: http://brainspl.at/ +[Ezra Zygmuntowicz]: http://brainspl.at/ +[Git]: http://git.or.cz/ +[Github]: http://github.com/ +[repository]: http://github.com/wycats/merb/ +[RubyConf]: http://rubyconf.org/ +[Yehuda Katz]: http://yehudakatz.com/  -[^first-pastie]: http://pastie.org/14416 \ No newline at end of file +[^first-pastie]: http://pastie.org/14416 \ No newline at end of file book-content/en/1-introduction/2-merb.markdown @@ -8,46 +8,53 @@ ## Introduction -[RSpec][] is a Behavior Driven Development framework for Ruby. -It provides two frameworks for writing and executing examples of how your Ruby -application should behave[^rspec]: +[RSpec][] is a Behavior Driven Development[^BDD] (BDD) framework for Ruby. +It provides two frameworks for writing and executing examples +of how your Ruby application should behave[^rspec]: - * a Scenario Framework[^cucumber] for describing behavior at the application level + * a Scenario Framework[^cucumber] for describing behavior + at the application level * a Code Example Framework for describing behavior at the object level -[RSpec][] was influenced by [Dan North][] and his Java-based BDD testing framework called [JBehave][]. +[RSpec][] was influenced by [Dan North][] +and his Java-based BDD testing framework called [JBehave][]. ## History -Initially BDD was just a discussion between [Aslak Hellesøy][] and [Dan North][] -in the [ThoughtWorks][] London office. -[Dave Astels][] joined the conversation with a blog post stating that he thought -these ideas could be easily implemented in [Smalltalk][] or [Ruby][]. -[Steven Baker][] jumped in with an initial implementation, and released -RSpec 0.1. Later in 2006, maintenance was handed over to [David Chelimsky][].[^rspec-history] +Initially, BDD was just a discussion between [Aslak Hellesøy][] +and [Dan North][] in the [ThoughtWorks][] London office. +[Dave Astels][] joined the conversation with a blog post, +suggestinging that these ideas could be easily implemented +in [Smalltalk][] or [Ruby][]. +[Steven Baker][] jumped in with an initial implementation, +released as RSpec 0.1. +Later in 2006, +maintenance was handed over to [David Chelimsky][].[^rspec-history] ## Behavior Driven Development -Behavior Driven Development[^BDD] is an [Agile][] development process that comprises -aspects of [Acceptance Test Driven Planning][], [Domain Driven Design][] and -[Test Driven Development][]. +Behavior Driven Development is an [Agile][] development process +that incorporates aspects of [Acceptance Test Driven Planning][], +[Domain Driven Design][], and [Test Driven Development][]. > Behaviour-driven development is an “outside-in” methodology. -> It starts at the outside by identifying business outcomes, and then drills down -> into the feature set that will achieve those outcomes. -> Each feature is captured as a “story”, which defines the scope of the feature -> along with its acceptance criteria. +> It starts at the outside by identifying business outcomes, +> and then drills down into the feature set that will achieve those outcomes. +> Each feature is captured as a “story”, +> which defines the scope of the feature along with its acceptance criteria. > - [Dan North][]{: .quote-author} {: cite=http://dannorth.net/whats-in-a-story} By focusing on the expected behaviors rather than the technical details, -developers can have better communication with the project owner and other stakeholders. +developers can have better communication +with the project owner and other stakeholders. ## Implementation -RSpec is a Domain Specific Language for describing the expected behavior -of a system with executable examples. +RSpec is a [Domain-Specific Language][] (DSL) +for describing the expected behavior of a system, +using a collection of executable examples. Here is a very simple RSpec example. @@ -68,20 +75,24 @@ Here is a very simple RSpec example.  [Acceptance Test Driven Planning]: http://testing.thoughtworks.com/node/89 -[Agile]: http://en.wikipedia.org/wiki/Agile_software_development -[Aslak Hellesøy]: http://blog.aslakhellesoy.com/ -[Dan North]: http://dannorth.net -[Dave Astels]: http://blog.daveastels.com/ -[David Chelimsky]: http://blog.davidchelimsky.net +[Agile]: http://en.wikipedia.org/wiki/Agile_software_development +[Aslak Hellesøy]: http://blog.aslakhellesoy.com/ +[Dan North]: http://dannorth.net +[Dave Astels]: http://blog.daveastels.com/ +[David Chelimsky]: http://blog.davidchelimsky.net [Domain Driven Design]: http://domaindrivendesign.org/ -[JBehave]: http://jbehave.org/ -[RSpec]: http://rspec.info -[Ruby]: http://ruby-lang.org -[Smalltalk]: http://www.smalltalk.org -[Steven Baker]: http://blog.lavalamp.ca +[Domain-Specific Language]: http://en.wikipedia.org/wiki/Domain_Specific_Language +[JBehave]: http://jbehave.org/ +[RSpec]: http://rspec.info +[Ruby]: http://ruby-lang.org +[Smalltalk]: http://www.smalltalk.org +[Steven Baker]: http://blog.lavalamp.ca [Test Driven Development]: http://en.wikipedia.org/wiki/Test-driven_development -[ThoughtWorks]: http://www.thoughtworks.com/ +[ThoughtWorks]: http://www.thoughtworks.com/  +*[BDD]: Behavior Driven Development +*[DSL]: Domain Specific Language *[TDD]: Test Driven Development -*[BDD]: Behavior Driven Development \ No newline at end of file + + book-content/en/1-introduction/4-rspec.markdown @@ -58,31 +58,35 @@ Windows users have a couple of options for installing Ruby and RubyGems. One way is to download the Ruby binaries, install them, and then install RubyGems. An alternative is to use the [One-Click Ruby Installer][] -which comes packaged with RubyGems (as well as a few other things). If you use -the One-Click Installer, make sure you check the 'Enable RubyGems' box in the -install wizard. +which (as well as a few other things) comes packaged with RubyGems. +If you use the One-Click Installer, +make sure you check the "Enable RubyGems" box in the install wizard. By default, it will install Ruby in the <tt>C:\Ruby</tt> directory. Once installed, do the following: -Start --> Programs --> Ruby-<version> --> RubyGems --> RubyGems Package Manager +Start --> Programs --> Ruby-<version> +--> RubyGems --> RubyGems Package Manager -This will open a command prompt in the <tt>C:\Ruby</tt> directory and display -some usage information. Then it's just a simple matter of installing Merb: +This will open a command prompt in the <tt>C:\Ruby</tt> directory +and display some usage information. +Then it's just a simple matter of installing Merb: C:\Ruby> gem install merb -This command might take a couple of minutes to run, since it must update the gem -cache, fetch all Merb related gems and then install them. +This command might take a couple of minutes to run, +because it must update the gem cache, fetch all Merb-related gems, +and then install them. -_Note_: If you want to use SQLite database (which is the default), you must -download and install it separately. More information can be found on the -[SQLite][] site. +_Note_: If you want to use SQLite database (which is the default), +you must download and install it separately. +More information can be found on the [SQLite][] site. + [Apple developer website]: http://developer.apple.com/technology/xcode.html -[RubyGems]: http://www.rubygems.org/ -[Ubuntu]: http://www.ubuntu.com/ -[RedHat]: http://www.redhat.com/ [One-Click Ruby Installer]: http://rubyinstaller.rubyforge.org/wiki/wiki.pl +[RedHat]: http://www.redhat.com/ +[RubyGems]: http://www.rubygems.org/ [SQLite]: http://www.sqlite.org/ +[Ubuntu]: http://www.ubuntu.com/ book-content/en/2-getting-started/1-install-instructions.markdown @@ -8,7 +8,7 @@ in order to create Merb applications. The generator can generate different types of Merb applications; to see all of the available generator options, type - $ merb-gen -h + $ merb-gen -H {:lang=shell html_use_syntax=true} For now, let's just stick with the types of Merb applications @@ -85,7 +85,7 @@ where the entire application is in one file. To run a very flat application, start up Merb with the following command (within your application directory): - $ merb -I my-applcation.rb + $ merb -I my-application.rb {:lang=shell html_use_syntax=true} This will start Merb and bind it to the default port (4000). book-content/en/2-getting-started/2-generate-an-application.markdown @@ -130,6 +130,7 @@ which is where you can customize the actual spec runner (among other things). This directory contains Merb's [thor][] tasks. + [bundle]: /deployment/bundle [controllers]: /getting-started/controllers [deploy]: /deployment book-content/en/2-getting-started/3-project-structure.markdown @@ -59,6 +59,8 @@ to keep their controllers as 'skinny' as possible by pushing code that does not directly relate to the request/response cycle (or the gathering of data) into the Model. + + [CakePHP]: http://www.cakephp.org/ [Controllers]: /getting-started/controllers [Django]: http://www.djangoproject.com/ book-content/en/2-getting-started/4-mvc.markdown @@ -15,30 +15,32 @@ {: cite=http://heim.ifi.uio.no/~trygver/1979/mvc-2/1979-12-MVC.pdf .lead-quote} -In the [MVC][] paradigm, controllers represent the glue layer that connects the -business logic (Model) with the View. - -Concretely, the controller is responsible for mapping an end-user action to -an application response. - -In Merb, technically speaking, controllers are classes inheriting from -``Merb::Controller``. -In a Merb stack app, a controller class called ``Application`` is created. -All generated controllers will inherit from ``Application`` and therefore -share the same attributes as ``Application``. - -The [Router][] logic in Merb finds a controller and an action to send the -request to while taking in consideration the incoming request details. - -In this chapter we will look at how to generate and organize controllers. -We will also discuss how to write **actions**; -the methods that are called on a controller. +In the [MVC][] paradigm, controllers represent the glue layer +that connects the business logic (Model) with the View. + +Concretely, the controller is responsible for mapping an end-user action +to an application response. + +In Merb, technically speaking, +controllers are classes inheriting from ``Merb::Controller``. +In a Merb-stack app, a controller class called ``Application`` is created. +All generated controllers inherit from ``Application``; +therefore, they share the same attributes as ``Application``. + +Merb's [Router][] logic examines the details of the incoming request, +comparing them to rules specified in the ``router.rb`` file. +Assuming that a match can be found, +it then sends the request to the appropriate controller and action. + +In this chapter, we will look at how to generate and organize controllers. +We will also discuss how to write **actions**, +controller methods that are called on to handle incoming requests. Finally, we will look at how to extend the functionalities of a controller. ## Generating controllers -You can generate two types of controllers. -A standard controller and a [RESTful][] controller. +You can generate two types of controllers: +a standard controller and a [RESTful][] controller. ### A standard controller @@ -49,10 +51,15 @@ A standard controller and a [RESTful][] controller. [ADDED] app/helpers/birds_helper.rb {:lang=shell html_use_syntax=true} -The command above will generate a controller with an ``index action`` and -an ``index view`` (template). +The command above generates several files. +The controller file (``birds.rb``) will contain methods for each action, +as well as other methods needed by the controller. +The view template file (``index.html.erb``) can be used to generate HTML, +using an ``erb`` (embedded Ruby) processor. +The remaining files (``birds_spec.rb``, ``birds_helper.rb``) +should be used to store test specifications and helper methods. -Let's quickly look at the generated controller: +Let's take a quick look at the generated controller: class Birds < Application @@ -63,20 +70,21 @@ Let's quickly look at the generated controller: end {:lang=ruby html_use_syntax=true} -The generator added a new class called ``Birds`` inheriting from ``Application``. -The new class has one method called index. In the context of a controller, we will -often refer to these methods as ``controller actions`` or simply ``actions``. - +The generator added a new class called ``Birds``, +inheriting from ``Application``. +The new class has one method called ``index``. +In the context of a controller, +we will often refer to these methods as **controller actions** or simply **actions**. -Remember what we said earlier? -``Application`` is the controller class from which all controller usually inherits and ``Application`` is just a subclass of ``Merb::Controller`` and a convenient way -to share code between controllers. +``Application`` (a subclass of ``Merb::Controller``) +is the class from which controllers usually inherit. +So, it is a convenient place to share code between controllers. (_use with care_) +-- {: .notes} - If you realized you made a mistake when generating your controller, +If you realize that you made a mistake when generating your controller, you can delete the generated controller by appending ``-d`` at the end of the command you just sent: @@ -100,11 +108,11 @@ end of the command you just sent: [ADDED] app/helpers/cats_helper.rb {:lang=shell html_use_syntax=true} -If you open the newly generated controller file (``app/controllers/cats.rb``) +If you open the newly generated controller file (``app/controllers/cats.rb``), you will notice that the generator created a new class called ``Cats``. -As expected, the class inherits from Application. -However, this time, instead of an empty index action, we find 7 fully defined -actions. +As expected, the class inherits from ``Application``. +However, this time, instead of an empty ``index`` action, +we find seven fully-defined actions. Let's look at the generated file: @@ -170,9 +178,10 @@ Let's look at the generated file: Wow, that's a lot code. -As a rule of thumb, you should **not** use generated code you don't understand. -Luckily, the code above is pretty simple to understand and we'll go through in -great details +As a rule of thumb, +you should **not** use generated code that you don't understand. +Luckily, the code above is pretty simple to understand +and we'll go through it in great detail. But before we dig into the code, let's talk about [REST][]. @@ -180,24 +189,28 @@ But before we dig into the code, let's talk about [REST][]. [REST][] is an acronym for [Representational State Transfer][]. It was first introduced in 2000 by [Roy Fielding][][^rest\_intro]. -REST refers to a software architectural style outlining how [resources][] are defined and addressed. -So, the center piece of REST are [resources][]. +REST refers to a software architectural style outlining how [resources][] +are defined and addressed. +So, [resources][] are the key components of REST. -**What is a resource in the context of REST?** +**What is a resource, in the context of REST?** -A resource is a source of specific information referenced by a URI (global identifier). +A resource is a source of specific information, +referenced by a URI (global identifier). In lay terms, it's some information you can access via a specific address. REST uses the HTTP protocol to communicate data between the different actors. -It's often used for web services since its principles apply very well to web resources. +It's often used for web services, +because its principles apply very well to web resources. **Here is how people usually map REST web resources:** -``URI:`` http://site.com/cats or http://site.com/cats/1-felix (global identifier/address) -``Format``: MIME Type or extension (HTML, JSON, XML, YAML, CSV, PDF...) -``action``: map the HTTP methods (POST, GET, PUT and DELETE) to resource methods +**URI:** http://site.com/cats or http://site.com/cats/1-felix +(global identifier/address) +**Format:** MIME Type or extension (HTML, JSON, XML, YAML, CSV, PDF, ...) +**action:** map the HTTP methods (POST, GET, PUT, and DELETE) to resource methods -If a resource is defined, Merb uses the ``URI`` and the the HTTP method to pick -a controller and an action. +If a resource is defined, Merb uses the ``URI`` and the HTTP method +to pick a controller and an action. ---- @@ -211,21 +224,21 @@ which maps URL Paths  to Controllers like this: /:controller/:action/:id(.:format) -This means that a request for 'http://example.com/posts/display/17' would cause -an in instance of the Posts controller to be created, -and the method 'display' to be called on that instance with the :id of 17. +This means that a request for ``http://example.com/posts/display/17`` +would cause an instance of the ``Posts`` controller to be created. +The method ``display`` would be called on that instance with an ``:id`` of 17. It might look something like this: Posts < Application def display #Post is a Model class - @post = Post.git(params[:id]) + @post = Post.get(params[:id]) display @post end end. {:lang=ruby html_use_syntax=true} -In this style methods are created to handle different actions. +In this style, methods are created to handle different actions. Each Controller has a method for every action that it can respond to. There are no limits on the number of actions that can be in a controller. Particularly in small applications where there are only a couple of controllers, @@ -234,8 +247,9 @@ by simply adding a method to a controller. ###The RESTful Style -The REST philosophy is to view every web request as a request to retrieve(GET), -create (POST), change(PUT), or remove(DELETE) some resource +The REST philosophy is to view every web request +as a request to retrieve (GET), +create (POST), change (PUT), or remove (DELETE) some resource over which the server is keeping track. There are a number of benefits to this model.  @@ -245,16 +259,16 @@ and performance. Generally, it is considered to be good practice to have one resource controller for each Model. -To route to a resource controller use this line when setting up routes: +To route to a resource controller, use this line when setting up routes: resources :posts Resources can also be singleton and/or nested. Please read the [Router][] chapter for more information. -By default a resource Controller has seven methods. -These methods are routed to based on the HTTP method (GET, POST, PUT and DELETE) -as well as the URL. +By default, a resource Controller has seven methods. +The routing for these methods is based on the HTTP method +(GET, POST, PUT, and DELETE), as well as the URL. ####Index @@ -263,9 +277,9 @@ routed to by: GET /posts /posts.index(.:format) -The expectation here is that the user will be presented with a list of all the -Resources of this type the server knows about. -In this case all the Posts in a blog perhaps. +The expectation here is that the user will be presented with a list +of every resource of this type that the server knows about. +In the current example, this might be all of the posts in a blog. ####New @@ -273,13 +287,13 @@ routed to by: GET /posts/new -This is the first of three User Interface methods that don't map nicely onto -the HTTP verbs. -It is used to show the use a form to create a new resource. +This is the first of three User Interface methods that don't map nicely +onto the HTTP verbs. +It is used to show the use of a form to create a new resource. The form's content will be sent back to the server -and handled by the 'create' method. -In the example above the page might present the use with a form to write a new -blog post. +and handled by the ``create`` method. +In the example above, +the page might present the use with a form to write a new blog post. ####Create @@ -287,23 +301,25 @@ routed to by: POST /posts -This method receives data from the client that is used to construct a new -resource. -Generally, the system responds by redirecting the client to the newly created -resource, but that only a convention. +This method receives data from the client +that is used to construct a new resource. +Generally, the system responds by redirecting the client +to the newly created resource, but this is only a convention. ####Show routed to by: + GET /posts/:id -This request displays an individual resource identified by ':id'. +This request displays an individual resource identified by ``:id``. For example, the above might show an single blog posting with all of its comments. ####Edit routed to by: + GET /posts/:id/edit This is another User Interface method. @@ -323,10 +339,10 @@ This method is a request to change an already existing resource. The method needs to update the model and the return a response to the user. A common convention is to redirect the user to the modified resource. -Of special interest in this function is the use of the HTTP verb 'PUT'. +Of special interest in this function is the use of the HTTP verb "PUT". Very few clients can use this verb. To get around this restriction, -any POST with a method field containing 'PUT' +any POST with a method field containing "PUT" is silently converted to a PUT method by Merb before the request is routed. @@ -340,42 +356,45 @@ This is the last of the User Interface methods. It is used to remove a resource from the server. It presents the user with the information they need to construct a proper destroy request. -It may also be used to confirm a users desire to remove the resource. -Request from this page are routed to the'destroy' method. +It may also be used to confirm a user's desire to remove the resource. +Requests from this page are routed to the ``destroy`` method. ####Destroy routed to by: + DELETE /posts/:id -This is a request for the server to remove a resource identified by :id. -For example the user might wish to remove an unwanted post from their blog. +This is a request for the server to remove a resource identified by ``:id``. +For example, the user might wish to remove an unwanted blog post. -Like update, this method relies upon an HTTP verb - DELETE - that is not widely -supported. -A Post with the a method field containing 'DELETE' +Like update, this method relies upon an HTTP verb - DELETE - +that is not widely supported. +A POST whose method field contains "DELETE" is silently converted to a DELETE Request. -This can present issues as a link tag cannot generate a post request +This can present issues, as a link tag cannot generate a POST request without the use of JavaScript. One way around this is to use the delete page above with a form or button to confirm the request. -Another is to use JavaScript to form a proper request. +Another way is to use JavaScript to form a proper request. ###Adding and Removing Methods -While the above methods are standard, there are provisions made to add others. -It is best if such actions deal with a single resource, -and only doing the four basic operations to it. +Although the methods listed above are standard in Merb, +provisions have been made to add others. +It is best if such actions deal with a single resource +and only perform the four basic operations to it. Examples of good uses for adding functions might be having multiple ways to view a resource -or needing more then one form to create or edit a resource. -These methods must be passed as option to the 'resources' declaration in the -router. -(Please see API documentation) - -There are also circumstances where it is not necessary to use all the methods. -Perhaps no on is allowed to delete a resource, -or the show page contains a form to edit the resource already. +or needing more than one form to create or edit a resource. +These methods must be passed as options +to the 'resources' declaration in the router. +(Please see the API documentation) + +There are also circumstances where it is not necessary +to use all of these methods. +Perhaps no user is allowed to delete a resource, +or the show page already contains a form to edit the resource. In these cases, simply not providing the method will prevent it from being called. @@ -390,11 +409,13 @@ Keep in mind that controller methods should be as light as possible. ###Render and Display -The most important thing a controller method does it return a value that is -passed on to the response. -This is different from Rails where the framework will always call a view for you. -In Merb is it perfectly fine to return a string directly in the controller. -eg: +In general, the last thing a controller method does is return a value +that is passed on as its portion of the response. +This is different from Rails, +where the framework will always call a view for you. +In Merb, it is perfectly fine to return a string directly from the controller. + +For example: class Hello < Merb::Controller def hello_world @@ -405,18 +426,19 @@ eg: This would send the text "Hello World!" directly back as the response. -Usually, we do not want to put the text in the controller. +Usually, we do not want to generate output text in the controller. This is what the [View][] layer is for. -Views are invoked from controllers using either the 'render' or 'display' -methods. - -The render method does a number of thing behind the seen. It determines the -Layout to use, determines which View file to render, renders it and returns the -resulting text. -Render ensures that all instance variable -(ie variables that begin with an '@') +Views are invoked from controllers +using either the ``render`` or ``display`` method. + +The ``render`` method does a number of things behind the scenes. +It determines the Layout to use, determines which View file to render, +renders it, and returns the resulting text. +``render`` ensures that all instance variables +(ie, variables that begin with an '@') which were set in the controller are available to the view and layout. -eg: + +For example: class Posts < Application def show(id) @@ -426,19 +448,21 @@ eg: end {:lang=ruby html_use_syntax=true} -This might render the 'show.html.erb template using the posts.html.erb layout. -Both of these file would have the @post variable available to them. -Also note that render was the last item in the method. +This might render the ``show.html.erb`` template, +using the ``posts.html.erb`` layout. +Both of these files would have the ``@post`` variable available to them. +Also note that ``render`` was the last item in the method. Ruby automatically returns the last value in a method as the return value for that method.  -The 'display' method does everything the render method does +The ``display`` method does everything the ``render`` method does, but goes a step further. -If display cannot find a valid template to render, +If ``display`` cannot find a valid template to render, it instead calls a method on the object it was passed based on the format. -If that method returns a value it is passed to the response. -eg: +If that method returns a value, it is passed to the response. + +For example: class Posts < Application def show(id) @@ -448,50 +472,54 @@ eg: end {:lang=ruby html_use_syntax=true} -Here, we might render the same templates as before, in response to a request -for HTML. -But, if this method was marked as providing XML(see format below for how) +Here, we might render the same templates as before, +in response to a request for HTML. +But, if this method was marked as providing XML +(see format below for details) and there was no XML template, -then the display method would instead call ``@post.to_xml`` +then the ``display`` method would instead call ``@post.to_xml`` and return the result. There are many other options for both of these methods. Developers should consult the API Documentation for both of them. -###Interaction with Model +###Interaction with Models -Most action methods will want to interact with Model. +Most action methods will want to interact with one or more Models. How this is done will depend on the ORM used. Records returned from the model should be stored in instance variables (these begin with an '@') so they can be used by the Views. -While we cannot antisipate all circumstances, +While we cannot anticipate all circumstances, the need to use more then two or three Model methods is often a sign -that more functionality need to be added to the model layer. +that more functionality needs to be added to the Model layer. If the same Model class is being called repeatedly, -moving that login into a new method for that class is a good way to refactor. +moving that login (???) into a new method for that class +is a good way to refactor. When more then two or three Model classes are needed by a controller, ether rework the controller to match your models more closely, -or create a presentor model that encapisolates these relationships. +or create a presenter model that encapsulates these relationships. -Merb can handle many of the exceptions thrown by ORM with 404 pages. -It is a good practice howevever to catch exceptions from the Model layer, -and give the user a better discription of the problem. +Using 404 pages, +Merb can handle many of the exceptions thrown by the ORM. +It is a good practice, however, to catch exceptions from the Model layer, +and give the user a better description of the problem. -###Information From the Request: The 'params' and 'request' Hashes +###Information From the Request: The ``params`` and ``request`` Hashes The controller has access to two hashes that are formed out of the request. -The params hash contains: +The ``params`` hash contains: * The controller and action the router decided on. * A hash of any Post or Query data sent by the client. (this is where the data from forms ends up) -* Other elements from the URI parsing, such as :id - (please see the chapter on the [Router][] for more information +* Other elements from the URI parsing, such as ``:id`` + (please see the [Router][] chapter for more information -The request hash contains information from the HTML request and the envrionment. -Normally, Merb will translate the infromation here into an easier to use form +The ``request`` hash contains information from the HTML request +and the environment. +Normally, Merb will translate the information here into an easier to use form for you, but that is not always sufficient. ###Persistant Information About the Client: Sessions and Cookies @@ -499,45 +527,47 @@ for you, but that is not always sufficient. HTTP is a stateless protocol. That means that each request stands on its own, and there is no way to keep information between calls. -For web applications it is convient to simulate a persistant state. -Cookies are used to idintify clients. +For web applications it is convenient to simulate a persistent state. +Cookies are used to identify clients. They can be used through the cookies hash in the controller. However, there is an easier and more flexible way to give an app the illusion -that there is a persistant state that follows a client around. -The session hash persists between different requests from the same client. +that there is a persistent state that follows a client around. +The ``session`` hash persists between different requests from the same client. There are a number of different ways to maintain sessions, -which we will not go into here. -The result is the same however. +but we will not go into these here. +The result is the same, however. Any object that is stored into the session will still be there the next time the user makes a request. Sessions can be use to store user credentials. -Indeed it is the session that Merb-Auth is authintication. +Indeed, it is the session that Merb-Auth is authenticating. Sessions can be used to store error messages after a redirect. -It can also store information about the steps completed in a multi-step -process. -eg. +They can also store information about the steps that have been completed +in a multi-step process. + +For example: class Users < Application def login if login_was_successful - #make sure that when the user reaches the home page we can remember - #who they were. + # Make sure that when the user reaches the home page, + # we can remember who they were. session[:user] = User.current_user redirect url(:home) else - #Provide a message telling the user why ther are back at the login - #screen. - session[:error_message] = "Could not log you in please try again." + # Provide a message telling the user why they are back + # at the login screen. + session[:error_message] = "Could not log you in; please try again." redirect url(:login) end end end {:lang=ruby html_use_syntax=true} -Developers coming from rails will note that there is not 'flash' hash in merb. -Instead Sessions can be used directly to send messages between pages. +Developers coming from Rails will note +that there is no ``flash` hash in Merb. +Instead, Sessions can be used directly to send messages between pages. ###Redirecting @@ -546,49 +576,50 @@ a server can ask the browser to go to a different page for information. In Merb, this is often done in response to a request to modify a resource through a POST, PUT, or DELETE request. -To accomplish this the server sends the client a specially formatted response, +To accomplish this, the server sends the client a specially formatted response, usually without any body. -Merb will create these responses for you with the [redirect][] function. -eg. +Merb will create these responses for you +using the [redirect][] method. + +For example: class Posts < Application def update(id) post = Post.get(id) if post.update_attributes(params[:post]) - redirect resource(post) #show the client the updated post + redirect resource(post) # Show the client the updated post. else session[:errors] = post.errors - #send the client back to the edit page so they can fix the errors. + # Send the client back to the edit page so they can fix the errors. redirect resource(:edit, post) end end end # - #NOTE: The resource method in the example above returns a URI. It is - # simular to the url method. + # NOTE: The resource method in the example above returns a URI. + # It is similar to the url method. {:lang=ruby html_use_syntax=true} - - ###Exceptions and Status Codes -TODO -- How does merb deal with exceptions +TODO -- How does merb deal with exceptions? -In addation to raising exceptions, +In addition to raising exceptions, Merb can set the status code directly using the 'status=' method. -eg. + +For example: class Posts < Application def update(id) unless params[:post] - status = 401 #tell the client we could not understand the request. + status = 401 # Tell the client we could not understand the request. return render("We could not seem to find the content of modified post", :layout=>'error') end post = Post.get(id) post.update_attributes(params[:post]) - redirect resource(post) #show the client the updated post + redirect resource(post) # Show the client the updated post. end end {:lang=ruby html_use_syntax=true} @@ -600,39 +631,42 @@ and how to use them to fine tune the behavior of an application. ###Formats -TODO - What formats are, How do we determin the format of a -request(.format || accept-format header), using provides, generating differnt +TODO - What formats are, How do we determine the format of a +request(.format || accept-format header), using provides, generating different formats, examples. Mention the value of RESTful controllers and web services. ###Before and After Filters -TODO -- about filter, creating filters, order of exicution, breaking out of -the filter chain, returning or modifying the responce in a filter, examples. +TODO -- about filter, creating filters, order of execution, breaking out of +the filter chain, returning or modifying the response in a filter, examples. -###Use of 'Application' +###Use of ``Application`` -The default stack for the merb app as well as the controller generators make -all their controllers inherit from Application. +Both the default stack for the merb app and the controller generators +make all of their controllers inherit from ``Application``. Developers can take advantage of this by putting methods -in the application class. +in the ``Application`` class. These methods will then be available to all controllers. -The application class can also set before and after filters that will be run -for all controllers. +The ``Application`` class can also set "before" and "after" filters +that will be run for all controllers. -The Application class is defined in the file, "app/controllers/application.rb" +The ``Application`` class is defined +in the file ``app/controllers/application.rb``. ###Private Methods It is best to refactor as much logic out of the controller as possible. -When the controller does need to have more complex logic in it, -it should be placed in private methods. -This keeps action methods cleaner and easier to test an debug. -It is important to make these methods private +When the controller does need to contain complex logic, +this should be placed in private methods. +This keeps action methods cleaner and easier to test and debug. +It is important to make these methods private, because public methods can be invoked by the router by default. This can be a security hole. -[MVC]: /getting-started/mvc + + +[MVC]: /getting-started/mvc [redirect]: http://merbivore.com/documentation/1.0/doc/rdoc/merb-core-1.0/index.html?a=M000529&name=redirect [Representational State Transfer]: http://en.wikipedia.org/wiki/Representational_State_Transfer [resources]: http://en.wikipedia.org/wiki/Representational_State_Transfer#REST.27s_central_principle:_resources @@ -643,8 +677,10 @@ This can be a security hole. [Trygve Reenskaug]: http://en.wikipedia.org/wiki/Trygve_Reenskaug [View]: /getting-started/view + [^rest\_intro]: Chapter 5 of Fielding’s dissertation is ["Representational State Transfer (REST)"](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) [^mvc-essay]: http://heim.ifi.uio.no/~trygver/1979/mvc-2/1979-12-MVC.pdf -*[REST]: Representational state transfer + *[HTTP]: Hypertext Transfer Protocol +*[REST]: Representational state transfer book-content/en/2-getting-started/5-controllers.markdown @@ -8,7 +8,7 @@ of the concepts and data that an application uses. In a blogging application, these would be things such as postings, comments, and users. In a store-front application, -they might be products, costumers, shopping carts, sales, etc... +they might be products, customers, shopping carts, sales, etc. Merb was designed to give developers as much latitude as possible in describing their models. Models can be anything a developer can represent with Ruby classes. @@ -17,14 +17,17 @@ Having said this, the vast majority of applications will use some kind of [ORM][] (Object Relational Mapper) to persist data between requests. Most apps will store their data in some form of a database. -The default Merb Stack uses DataMapper to communicate with an SQLite database. +The default Merb Stack uses [DataMapper][] to communicate +with an [SQLite][] database. This is an excellent choice for easy development of new projects. Once in production, however, it is generally recommended that developers make the switch -to one of the more powerful database engines, such as Postgres or MySQL. +to one of the more powerful database engines, +such as [PostgreSQL][] or [MySQL][]. Projects which are coming from the Rails world -may wish to keep their ActiveRecord models; Merb supports this as well. +may wish to keep their [ActiveRecord][] models; +Merb supports this as well. The rest of this chapter will focus on using DataMapper to create Model classes. @@ -32,10 +35,11 @@ to create Model classes. ## Attributes In a DataMapper model, attributes are defined with the ``property`` method. -This method takes the name of the attribute, a data type, and a hash of -options. Unlike ActiveRecord, a DataMapper model doesn't require separate -migration files (although migrations are supported). Here's a fairly standard -DataMapper model: +This method takes the name of the attribute, a data type, +and a hash of options. +Unlike ActiveRecord, a DataMapper model doesn't require separate migration files +(although migrations are supported). +Here's a fairly standard DataMapper model: class Article include DataMapper::Resource @@ -46,20 +50,21 @@ DataMapper model: end {:lang=ruby html_use_syntax=true} -Take a look at the [properties][] section of the DataMapper site for more details. +See the [properties][] section of the DataMapper site for more details. ## Validations -You can do model validations two different ways. Either you can define them at -the same time as the attribute definition, or use an explicit ``validates_*`` -method. The following two examples are equivalent: +You can do model validations in two different ways. +Either you can define them at the same time as the attribute definition +or use an explicit ``validates_*`` method. +The following two examples are equivalent: # Using "auto-validations", defined with the property. class Person include DataMapper::Resource property :id, Serial property :name, String, :nullable => false - property :age, Integer, :length => 1..150 + property :age, Integer, :length => 1..150 end # Using the "validates_*" methods. @@ -74,7 +79,7 @@ method. The following two examples are equivalent: end {:lang=ruby html_use_syntax=true} -For more info, head over to DataMapper's [validations][] page. +For more information, see DataMapper's [validations][] page. ## Associations @@ -82,18 +87,19 @@ DataMapper has a very versatile way of defining associations between your models All association types are supported, including One-To-Many, Many-To-Many, etc. Associations are configured using the ``has`` and ``belongs_to`` methods. -Lets say, for example, you're writing a blog application. This application will -have Article and Comment models. Here's how we would setup the association: +Lets say, for example, that you're writing a blog application. +This application will have Article and Comment models. +Here's how we would set up the association: class Article include DataMapper::Resource - # setup properties + # Set up properties. has n, :comments end class Comment include DataMapper::Resource - # setup properties + # Set up properties. belongs_to :article end {:lang=ruby html_use_syntax=true} @@ -106,12 +112,15 @@ This gives you methods to work with the associations. comment.article # Returns the parent Article. {:lang=ruby html_use_syntax=true} -If you take a look at the Article model, you'll notice the "mythical, magical ``n``". -This method is a shortcut to ``Infinity`` and is used to provide the -"has many" association. +If you take a look at the Article model, +you'll notice the "mythical, magical ``n``". +This method is a shortcut to ``Infinity`` +and is used to provide the "has many" association. Setting up a "has one" association is as simple as passing the integer ``1`` -(one) to the ``has`` method. For example: +(one) to the ``has`` method. + +For example: class Person include DataMapper::Resource @@ -126,7 +135,8 @@ Setting up a "has one" association is as simple as passing the integer ``1`` end {:lang=ruby html_use_syntax=true} -Similar to the "has many" association, you get some helper methods: +Like the ``has many`` association in Rails, +these associations provide some helper methods: person = Person.first person.coffee_cup # Returns the person's cup. @@ -134,19 +144,21 @@ Similar to the "has many" association, you get some helper methods: cup.person # Returns the cup's owner. {:lang=ruby html_use_syntax=true} -For more complicated examples, such as "has many through", refer to DataMapper's -[associations][] page. +For more complicated examples, such as ``has many through``, +refer to DataMapper's [associations][] page. ## Callbacks -Callbacks allow you to "hook" into various methods, to provide additional -functionality, or (for example) ensure that a property is formatted in a certain -manner. DataMapper supports callbacks using an [aspect-oriented][] approach +Callbacks allow you to "hook" into various methods, +to provide additional functionality +or (for example) ensure that a property is formatted in a certain manner. +DataMapper supports callbacks using an [aspect-oriented][] approach and includes (among others) the ``before`` and ``after`` methods. -Let's say you have a Comment model and you wanted to ensure that the -``homepage`` property begins with "http://" without having to require -the person to explicitly provide it. This is one way of achieving that: +Let's say that you have a Comment model. +You want to ensure that the ``homepage`` property begins with "http://", +without having to require the person to explicitly provide it. +This is one way of achieving that: class Comment include DataMapper::Resource @@ -164,8 +176,9 @@ the person to explicitly provide it. This is one way of achieving that: end {:lang=ruby html_use_syntax=true} -As you can see, the ``before`` method takes (as symbols) the name of the -method you're "hooking" into and the name of the method which will do the work. +As you can see, the ``before`` method takes (as symbols) +the name of the method you're "hooking" into +and the name of the method which will do the work. You can also pass a block: before :save do @@ -176,9 +189,16 @@ You can also pass a block: You can define callbacks for essentially any method, including class methods. For more details, refer to DataMapper's [hooks][] page. + + +[ActiveRecord]: http://en.wikipedia.org/wiki/ActiveRecord_%28Rails%29 +[aspect-oriented]: http://en.wikipedia.org/wiki/Aspect_oriented +[associations]: http://datamapper.org/doku.php?id=docs:associations +[DataMapper]: http://datamapper.org/doku.php +[hooks]: http://datamapper.org/doku.php?id=docs:hooks +[MySQL]: http://en.wikipedia.org/wiki/MySQL [ORM]: http://en.wikipedia.org/wiki/Object-relational_mapping +[PostgreSQL]: http://en.wikipedia.org/wiki/PostgreSQL [properties]: http://datamapper.org/doku.php?id=docs:properties +[SQLite]: http://www.sqlite.org/ [validations]: http://datamapper.org/doku.php?id=docs:validations -[associations]: http://datamapper.org/doku.php?id=docs:associations -[aspect-oriented]: http://en.wikipedia.org/wiki/Aspect_oriented -[hooks]: http://datamapper.org/doku.php?id=docs:hooks book-content/en/2-getting-started/7-models.markdown @@ -3,115 +3,127 @@ * This will become a table of contents (this text will be scraped). {:toc} -All web applications begin with an HTTP request by a client. -They all end with a response from our server. +All web applications act in response to an HTTP request by a client. +Each action ends with a response from the HTTP server. In this chapter, we are going to follow the program flow from the client request through to the response. ## From the Client to Our Doorstep -The inner working of the Internet are beyond the scope of this book. -It is however helpful to remember that there is a client (web browser) out -there -and that the request it generates passes through a number of steps to reach -our servers. -Along the way proxies, caches and firewalls may look at the request, modify it, +The inner workings of the Internet are beyond the scope of this book. +It is, however, helpful to remember +that there is a client (eg, web browser) out there +and that the request it generates passes through a number +of entities (eg, proxies, caches, firewalls) to reach our servers. +Any of these entities may look at the request, modify it, and possibly store what we send back. -If all goes well this will be transparent to both our server and the user. -There are times, particularly with dynamic sites, where these things will need -to be taken into account. -There are also ways to take advantage of the infrastructure of the internet -that reduce the load on the server -while can save both bandwidth and equipment costs. +If all goes well, this will be transparent to the user +and of no concern to the server. + +There are situations, however (particularly with dynamic sites), +where these activities will need to be taken into account. +There are also ways to take advantage of the infrastructure of the Internet +to reduce the load on the server. +This can save both bandwidth and equipment costs. ## Reverse Proxy (optional) -The first stop for a request in a live application is usually a reverse proxy like -[NginX][] or [Apache mod\_proxy][]. -Depending on the setup, these proxies may serve static files like images, -CSS style sheets, JavaScript, videos etc. -Often, we will even let it serve cached pages without ever interacting -with our application. +The first stop for a request in a live application +is usually a reverse proxy such as [NginX][] or [Apache][]'s [mod\_proxy][]. +Depending on the setup, these proxies may serve static files +(eg, images, CSS style sheets, JavaScript code, videos). +Often, we will even let a proxy serve cached pages +without ever interacting with our application. -[Phusion Passenger][] is not a reverse proxy per say. However, for the sake -of the argument let's pretend it is one as it will receive the request via Apache -and send a rack request to the server application. +[Phusion Passenger][] is not a reverse proxy, _per se_. +However, for the sake of argument, let's pretend that it is one. +(Specifically, that it will receive the request via Apache +and send a [Rack][] request to the server application.) ## Web server -If the request was not already returned by by the reverse proxy. -Or if no reverse proxy is being used, the request is being forwarded on to a Web Server. -[Mongrel][], [Thin][], [Ebb][] and a number of lesser-know programs fill this -role. +If the request was not already returned by the reverse proxy, +or if no reverse proxy is being used, +the request will be forwarded to a **web server**. +[Mongrel][], [Thin][], [Ebb][], and a number of lesser-known programs +fill this role. -Once the response is received by the webserver, its being parsed and sent to [Rack][] -via a handler. +Once the response is received by the web server, +it will be parsed and sent to [Rack][] via a handler. ## Rack and Merb -Merb receives the request as a [Rack][] environment. A Rack environment wraps -all the cgi style headers for the request. -Because Merb uses Rack as an abstraction layer, it becomes really easy to change -web servers. +Merb receives the request as a [Rack][] environment. +A Rack environment wraps all of the CGI-style headers for the request. +Because Merb uses Rack as an abstraction layer, +changing web servers is really easy. You might hear people refer to these web servers as adapters. -Before Merb dispatches the request through the stack, one can add "Rack middlewares". -Rack middlewares can process the request before it's sent through Merb or even wrap it -allowing custom code to be execute before and after going through the stack. -Rack Middlewares end up being very powerful tools allowing you to do -custom logging, caching, profiling etc... +Before Merb dispatches the request through the stack, +one can add "Rack middlewares". +Rack middlewares can process the request before it's sent through Merb. +Alternatively, they can "wrap" the request, +allowing custom code to be executed both before and after the request +goes through the stack. +Rack middlewares can be very powerful tools, allowing you to do +custom logging, caching, profiling, etc. We will not cover the use of Rack extensively here, -but you can find Merb's Rack setup in 'config/rack.rb' (full stack app). +but you can find Merb's Rack setup in the ``config/rack.rb`` file +(in the full stack app). ## Router -Once the request is being passed to the stack, the router is asked where to go -by the request. +Once the request has been passed to the stack, +the router is asked where to go by the request. The request then sends itself to the controller. The Router's job is to set up parameters extracted from the request and to tell the request where to go. -In most cases, the router maps a request to a controller method (action) and also -sets up parameters extracted from the request. +In most cases, the router maps a request to a controller method (action) +and also sets up parameters extracted from the request. -Behind the scenes the Merb framework has already done some work for you. +Behind the scenes, the Merb framework has already done some work for you. By the time a request reaches the controller, Merb has: - * Extracted the request URI Path. - * Parses any Post or Query data sent by the client into the params hash. - * Setup access to request cookies and the current session. +* Extracted the request URI Path. +* Parsed any Post or Query data sent by the client, + placing it in the ``params`` hash. +* Set up access to request cookies and the current session. The developer can use any of this information to route the request. -Please see the chapter on routing for more information. +Please see the chapter on routing (???) for more information. ## Controller Action The request is now being dispatched to a controller method. -For instance: the **show** method/action from the **Articles** controller. +For instance: the ``show`` method/action from the ``Articles`` controller. The action can render a view or simply return a string. The returned value from the method will be used to build a Rack response. A Rack response is just a simple tuple containing [status, headers, body]. ## Out the Door -Finally Merb sends a well formed rack response back to the web server. -The web server in turn formats an HTTP response which is put out over -the wire. -The client receives the response and interprets by, for example, rendering a web page. +Finally, Merb sends a well-formed Rack response back to the web server. +The web server, in turn, formats an HTTP response +which is put out over the wire. +The client receives the response and interprets it by, for example, +rendering a web page. ## Caching -If caching is enabled, the request might not go through the entire process -described above. -Caching may happen within Merb, by a Rack Middleware, a Proxy server, -or by the client web browser. +If caching is enabled, +the request might not go through the entire process described above. +Caching may happen within Merb, a Rack Middleware, a Proxy server, +or the client web browser. -[Apache mod\_proxy]: http://httpd.apache.org/docs/2.0/mod/mod_proxy.html + +[Apache]: http://httpd.apache.org/ [GlassFish]: /deployment/jruby +[mod\_proxy]: http://httpd.apache.org/docs/2.0/mod/mod_proxy.html [Mongrel]: http://mongrel.rubyforge.org/ [MVC]: /getting-started/mvc [NginX]: /deployment/nginx book-content/en/2-getting-started/8-request-path.markdown @@ -3,10 +3,10 @@ * This will become a table of contents (this text will be scraped). {:toc} -It is important to test your application to ensure that you minimize the chances -of [regression][]. -Merb stack's default testing framework uses the [RSpec][] testing framework and a combination of -model specs, request specs, and integration specs. +It is important to test your application +to ensure that you minimize the chances of [regression][]. +Merb stack's default testing framework uses the [RSpec][] testing framework +and a combination of model, request, and integration specs. ## Types of Tests @@ -17,5 +17,6 @@ model specs, request specs, and integration specs. ### Integration + [regression]: http://en.wikipedia.org/wiki/Software_regression [RSpec]: http://rspec.info/ \ No newline at end of file book-content/en/4-testing-your-application/1-why.markdown @@ -5,7 +5,8 @@ [Cucumber][] is the preferred method for integration testing your Merb applications. -Cucumber is a tool that can execute feature documentation written in plain text. +Cucumber is a tool that can execute "feature documentation" +written in plain text. Here is an example of a typical Cucumber feature: Feature: Login @@ -24,26 +25,26 @@ Here is an example of a typical Cucumber feature: ## Merb and Cucumber -In order to use Cucumber with Merb, you need to install the [merb\_cucumber][] -plugin. +In order to use Cucumber with Merb, +you need to install the [merb\_cucumber][] plugin. To install the plugin, run the command $ sudo gem install merb_cucumber -or, if you're using the local gems directory run +or, if you're using the local gems directory, run $ thor merb:gem:install merb_cucumber -Then, inside of your merb project root run +Then, inside of your merb project root, run $ merb-gen cucumber -Or to install with [Webrat][] support run +Or, to install with [Webrat][] support, run $ merb-gen cucumber --session-type webrat -This will also install the login feature shown above, which should pass if -you’re using merb-auth. +This will also install the login feature shown above. +This should pass if you’re using merb-auth. Running your features is then as simple as running @@ -79,12 +80,13 @@ directory that looks like this: Then [outcome] And [another outcome] -If you then run your features from the command line, you'll see that Cucumber -gives you hints about how to implement each step. -More information about implementing Cucumber features can be found on the -[Cucumber wiki]. +If you then run your features from the command line, +you'll see that Cucumber gives you hints about how to implement each step. +More information about implementing Cucumber features can be found +on the [Cucumber wiki]. + [Cucumber]: http://github.com/aslakhellesoy/cucumber/wikis/home +[Cucumber wiki]: http://github.com/aslakhellesoy/cucumber/wikis/home [merb\_cucumber]: http://github.com/david/merb_cucumber/tree/master [Webrat]: http://github.com/brynary/webrat/wikis -[Cucumber wiki]: http://github.com/aslakhellesoy/cucumber/wikis/home book-content/en/4-testing-your-application/4-cucumber.markdown @@ -16,9 +16,10 @@ [merb-auth][] is a meta-gem. A meta-gem is a Ruby gem without any code. -It's sole purpose is to declare dependencies and make installation easier. +Its sole purpose is to declare dependencies and make installation easier. + +As of Merb 1.0.x, merb-auth uses three gems: -As of Merb 1.0.x merb-auth uses 3 gems: * [merb-auth-core][] * [merb-auth-more][] * [merb-auth-slice-password][] @@ -27,34 +28,37 @@ As of Merb 1.0.x merb-auth uses 3 gems: [merb-auth-core][] does not try to dictate what you should use as a user model, or how it should authenticate. -Instead it focuses on the logic required to check that an object -passes authentication, and store the keys of authenticated objects -in the session. +Instead, it focuses on the logic required +to check that an object passes authentication +and to store the keys of authenticated objects in the session. -This is in fact the guiding principle of MerbAuth. +This is, in fact, the guiding principle of MerbAuth. The Session is used as the place for authentication, with a sprinkling of controller helpers. -You can choose to protect a controller action, or a route/group of routes. +You can choose to protect a controller action, a route, or a group of routes. This is why you might hear people refer to an authenticated session. -MerbAuth makes use of Merb’s exception handling facilities which -return correct HTTP status codes. +MerbAuth makes use of Merb’s exception handling facilities, +which return correct HTTP status codes. To fail a login, or to force a login at any point in your controller code, -simply raise an ``Unauthenticated`` exception, with an optional message -and the user will be presented with login page. -The login page is in fact the view template for ``Extensions#unauthenticated``. +simply raise an ``Unauthenticated`` exception (with an optional message) +and the user will be presented with a login page. +The login page is, in fact, +the view template for ``Extensions#unauthenticated``. It is possible to use MerbAuth with any object as a user object, -provided that object does not evaluate to false and -it can be serialized in and out of the session. +provided that the object does not evaluate to false +and it can be serialized in and out of the session. -Finally, merb-auth is very powerful mainly because of its chained strategies capacity. -You can add as many strategies as you like and they will be tried one after another -until either one is found that works (login), or none of them have passed (failed attempt). +Finally, merb-auth gains great power from its "chained strategies" capacity. +You can add as many strategies as you like; +they will be tried one after another until either one is found that works (login) +or none of them have passed (failed attempt). An authentication strategy is just a way to authenticate a request. Examples of strategies would be: + * Salted user (user login with a password using a "salted" encryption) * OpenID * API key/token @@ -64,43 +68,46 @@ Examples of strategies would be: ### merb-auth-more [merb-auth-more][] adds extra features to merb-auth-core. -The gem offers a series of generic Strategies and "User" object mixins. +The gem offers a series of generic Strategies and "User" object "mixins". Strategies: + * login or email password form (aka password\_form) * basic HTTP authentication (aka basic\_auth) * OpenID - Mixins: + * ActiveRecord salted user * DataMapper salted user * relaxdb salted user * sequel salted user The salted user mixin provides basic salted SHA1 password authentication. -It implements the required User.authenticate method for use with -the default password strategies. +It implements the required ``User.authenticate method`` +for use with the default password strategies. ### merb-auth-slice-password -[merb-auth-slice-password][] is a very simple Merb slice. -The slice will provide developers with a basic login and logout function. -By default it also include the form based password logins and basic authentication. +[merb-auth-slice-password][] is a very simple Merb slice, +providing basic login and logout functionality, +form-based password logins, and basic authentication. -By default the slice will load the password\_form and the basic\_auth strategies +By default, the slice will load the ``password\_form`` +and ``basic\_auth`` strategies. -Views and strategies can be customized as exlained in the -Authenticated Hello World example. +Views and strategies can be customized, +as explained in the "Authenticated Hello World" example. ## Authentication in Merb Stack When you generate an application with the default merb stack[^merb-stack-app], -merb-auth is already setup for normal usage. +merb-auth is already set up for normal usage. -If you don't want to use this, simply comment out the dependency on merb-auth -in config/dependencies.rb +If you don't want to use this, +simply comment out the dependency on ``merb-auth`` +in ``config/dependencies.rb``. ## Authenticated Hello World @@ -108,7 +115,7 @@ in config/dependencies.rb ### Generate an application -First step is to generate your application using the Merb stack. +The first step is to generate your application, using the Merb stack. $ merb-gen app hello_world $ cd hello_world @@ -123,9 +130,9 @@ The basic elements are: merb/merb-auth/strategies.rb {:lang=ruby html_use_syntax=true} -The setup for user authentication is taken care of by default using a password -and login. -Of course we need to setup the database and add a user first. +By default, the setup for user authentication is taken care of, +using a password and login. +Of course, we first need to set up the database and add a user. $ rake db:automigrate @@ -138,7 +145,7 @@ Of course we need to setup the database and add a user first. ### Generate something to protect -Now we have an application, and a user, we need something to protect. +Now that we have an application and a user, we need something to protect. $ merb-gen controller hello_world {:lang=ruby html_use_syntax=true} @@ -152,16 +159,17 @@ Let's put something into the controller. end {:lang=ruby html_use_syntax=true} -If you fire up merb now and head on over to <http://localhost:4000/hello_world> +If you fire up merb now and look at <http://localhost:4000/hello_world>, you'll see the "Hello World" results. ### Protect the route It's not protected yet, so let's fix that. -We can either protect it in the routes in config/router.rb or in the controller action. -Let's do the router option first. +We can either protect it using the routes in ``config/router.rb`` +or in the controller action. +Let's try the router-based approach first. -Open up config/router.rb +Open up ``config/router.rb``: Merb::Router.prepare do authenticate do @@ -171,22 +179,23 @@ Open up config/router.rb {:lang=ruby html_use_syntax=true} This will cause the user to login. -This is discovered in the router and when it fails, it stops in the router. +This is discovered in the router and when it fails, it stops in the router. (???) Try to hit <http://localhost:4000/hello_world> now. -You'll see that you need to login to access it! +You'll see that you need to log in to access it! -Ok. Logout, <http://localhost:4000/logout> +Ok. +Logout, using <http://localhost:4000/logout>. ### Protect the controller -Now let's remove the code from the router, and put the protection at the -controller level. +Now let's remove the code from the router +and put the protection at the controller level. This will allow a finer control over resources for example. Merb::Router.prepare do - match("/hello_world").to(:controller => "hello_world") + match("/hello_world").to(:controller => "hello_world") end {:lang=ruby html_use_syntax=true} @@ -204,12 +213,13 @@ Let's now put it into the controller: {:lang=ruby html_use_syntax=true} -To get access to the currently logged in user inside your controller use: +To get access to the currently logged-in user inside your controller, use: session.user {:lang=ruby html_use_syntax=true} -Really... For a basic Hello World authentication, that's it. +Really... +For a basic Hello World authentication, that's it. ### Overwrite the default views @@ -220,13 +230,11 @@ If you want more customization, you can do: rake slices:merb-auth-slice-password:freeze:views {:lang=ruby html_use_syntax=true} -What that will do is copy the views from the slice to the /slices/ folder -in your application. - -Then you need to move/copy them to your /views/. -Editing the copied views in /app/views/ should now be taken into account. - +What that will do is copy the views from the slice +to the ``slices`` directory in your application. +Then you need to move/copy them to your ``app/views`` directory +and edit the copied views. (???) [^merb-stack-app]: merb-gen app hello\_world @@ -236,7 +244,7 @@ Editing the copied views in /app/views/ should now be taken into account. To test a request that needs to be authenticated, you will first need to login. The easiest way to login when you are running a request spec is to use a helper. -Here is an example of two helpers added to /spec/spec\_helper.rb +Here is an example of two helpers added to ``spec/spec\_helper.rb``. Merb::Test.add_helpers do @@ -276,6 +284,7 @@ Now that you added these helpers, you just need to slightly modify your examples In the above example, the request sent to the articles URI will be authenticated. + [Adam French]: http://adam.speaksoutofturn.com [merb-auth]: http://github.com/wycats/merb/tree/master/merb-auth [merb-auth-core]: http://github.com/wycats/merb/tree/master/merb-auth/merb-auth-core book-content/en/5-merb-more/1-authentication.markdown @@ -22,7 +22,7 @@ alongside a version of Ruby you currently have installed, as it will be installed into the <tt>/opt</tt> directory. *Note:* -You will need to have the development <tt>readline</tt> libraries installed +You will need to have the development ``readline`` libraries installed if you want run Merb interactively. ### Download REE @@ -74,7 +74,7 @@ into your Merb application's root directory: ## Capistrano Task + [Phusion Passenger]: http://www.modrails.com/ [Rack]: http://rack.rubyforge.org/ [Ruby Enterprise Edition]: http://www.rubyenterpriseedition.com/ - book-content/en/7-deployment/1-passenger.markdown @@ -10,7 +10,7 @@ [Nginx][] (pronounced "engine x") is a free, open-source, high-performance HTTP server and [reverse proxy][], as well as an IMAP/POP3 [proxy server][]. -Written by [Igor Sysoev](http://sysoev.ru/en/) in 2005, +Written by [Igor Sysoev][] in 2005, Nginx now hosts between 1% and 4% of all domains worldwide (sources: [1](http://googleonlinesecurity.blogspot.com/2007/06/web-server-software-and-malware.html), [2](http://survey.netcraft.com/Reports/200806/)). @@ -42,8 +42,8 @@ Use the package manager your system provides to install Nginx. ## Configuration -The nginx configuration lives in /etc/nginx/nginx.conf, if you're on Linux, -and /opt/local/etc/nginx/nginx.conf on Mac OS X. +The nginx configuration lives in ``/etc/nginx/nginx.conf``, if you're on Linux, +and ``/opt/local/etc/nginx/nginx.conf`` on Mac OS X. ### /etc/nginx/nginx.conf @@ -164,15 +164,16 @@ After that, you can deploy with ## Monit -[Monit][] is a tool that can be used for starting, stopping and monitoring -arbitrary services. Engine Yard created a wrapper script called -[monit\_merb\_mpc][], that helps monit handle Merb -and its master process. -At its current incarnation, monit\_merb\_mpc needs some minor modifications -to run outside of the Engine Yard stack. +[Monit][] is a tool that can be used for starting, stopping, +and monitoring arbitrary services. +Engine Yard created a wrapper script called [monit\_merb\_mpc][] +that helps monit handle Merb and its master process. +In its current incarnation, ``monit\_merb\_mpc`` +needs some minor modifications to run outside of the Engine Yard stack. A full introduction can be found on [Ezra's blog][]. -To monitor the Merb master process and workers, you need to add this configuration to monit: +To monitor the Merb master process and workers, +you need to add this configuration to monit: check process merb_app_master with pidfile /var/log/engineyard/app/app-production-merb.main.pid @@ -195,17 +196,18 @@ To monitor the Merb master process and workers, you need to add this configurati stop program = "/engineyard/bin/monit_merb_mpc app restart_worker 4001" if totalmem is greater than 80.0 MB for 2 cycles then restart # eating up memory? group merb_app - + + +[Ebb]: http://ebb.rubyforge.org/ +[Ezra's blog]: http://brainspl.at/articles/2008/12/07/merb-master-worker-monit-control-setup +[Glassfish]: https://glassfish.dev.java.net/ [Igor Sysoev]: http://sysoev.ru/en/ +[MacPorts]: http://macports.org/ +[Mongrel]: http://mongrel.rubyforge.org/ +[Monit]: http://mmonit.com/monit/ +[monit\_merb\_mpc]: http://pastie.org/333352 [Nginx]: http://wiki.codemongers.com/Main [proxy server]: http://en.wikipedia.org/wiki/Proxy_server [reverse proxy]: http://en.wikipedia.org/wiki/Reverse_proxy -[Mongrel]: http://mongrel.rubyforge.org/ [Thin]: http://code.macournoyer.com/thin/ -[Ebb]: http://ebb.rubyforge.org/ -[Glassfish]: https://glassfish.dev.java.net/ -[MacPorts]: http://macports.org/ -[Monit]: http://mmonit.com/monit/ -[monit\_merb\_mpc]: http://pastie.org/333352 -[Ezra's blog]: http://brainspl.at/articles/2008/12/07/merb-master-worker-monit-control-setup \ No newline at end of file book-content/en/7-deployment/2-nginx.markdown @@ -1,9 +1,17 @@ Merb.logger.info("Compiling routes...") Merb::Router.prepare do - match('(/:language)/table-of-contents', :language => /^[a-z]{2}$/).to(:controller => 'pages', :action => 'index').name(:toc) - match("(/:language)/:chapter(/:page_name)", :language => /^[a-z]{2}$/, :chapter => /[^\/]{3,}/).to(:controller => 'pages', :action => 'show').name(:page) - #default_routes - - match('/(:language)', :language => /^[a-z]{2}$/).to(:controller => 'pages', :action => 'index') + match('(/:language)/table-of-contents', + :language => /^[a-z]{2}$/). + to(:controller => 'pages', :action => 'index').name(:toc) + + match('(/:language)/:chapter(/:page_name)', + :language => /^[a-z]{2}$/, + :chapter => /[^\/]{3,}/). + to(:controller => 'pages', :action => 'show').name(:page) + + # default_routes + + match('/(:language)', :language => /^[a-z]{2}$/). + to(:controller => 'pages', :action => 'index') end \ No newline at end of file config/router.rb abbf0ba37e3f9883386629ba23aa596e55e6fe25 324b780baa510fa0dd1c0fd7e4ac40a9abfd7047 Matt Aimonetti mattaimonetti@gmail.com http://github.com/mattetti/merb-book/commit/cd5c1b95e7da7ed3ad6dbd9ff3844b3f4e5a4702 cd5c1b95e7da7ed3ad6dbd9ff3844b3f4e5a4702

2008-12-14T22:11:04-08:00

Merge branch 'english' * english: numerous small tweaks typo 'git' => 'get' Actual help switch is -H or --help or -?, not -h. Fixed a typo 24eb1f832df4299376e1699c41d3d9c12f7c0dfb Matt Aimonetti mattaimonetti@gmail.com