<p>Once the plugin is installed, it will register a list of exceptions that you can raise in your controller code. See [[AvailableExceptions]] for the actual list of exceptions and their corresponding status codes.</p>
<h2>Raising HTTPStatus exceptions</h2>
<p>You can simply raise an <code>HTTPStatus</code>-exception as soon as the normal execution of your code should stop.<br />
<pre><br />
class BlogController < ApplicationController<br />
def destroy<br />
raise HTTPStatus::Forbidden, “You cannot delete blogs!” unless user.admin?</p>
@blog = Blog.find(params[:id])
@blog.destroy
…
end
<p>end<br />
</pre></p>
<p>Raising exceptions works just as well in a <code>before_filter</code>:<br />
<pre><br />
class ApplicationController < ActionController::Base<br />
before_filter :set_current_user</p>
def set_current_user
@user = User.find(session[:user_id)
raise HTTPStatus::PaymentRequired, “Your account is expired” if @user.is_expired?
end
<p>end<br />
</pre></p>
<p>You can provide some additional details to the exception as well by passing an additional argument. This information can be used later on in the exception handler using the <code>details</code> function.<br />
<pre><br />
begin<br />
raise HTTPStatus::Forbidden.new(“message”, {:restricted_object => @blog })<br />
rescue HTTPStatus::Base => e<br />
logger.error e.details[:restricted_object].inspect<br />
end<br />
</pre></p>
<h2>Displaying an error page</h2>
<p>Once an <code>HTTPStatus</code> exception is raised, the default exception handler will be called. By default, it will return an empty response with the correct <span class="caps">HTTP</span> status code. It can return an error page easily by creating a template for that particular exception. For instance, to create an error page for the <code>HTTPStatus::NotFound</code> (404) exception, you should create a template file with the following name: <code>app/views/shared/http_status/not_found.html.erb</code>. The current layout will be applied to the template. The template file could look something like this:</p>
<pre>
<h1> Not found </h1>
<p> The resource you requested could not be found! </p>
<p style="color:red"> <%= h(@exception.message) %> </p>
<hr />
<p> <small>HTTP status <%= @exception.status_code %></small> </p>
</pre>
<p>Note that by using the <strong>.html.erb</strong> extension, this template will only be used for <span class="caps">HTML</span> formatted requests; if the same exception is raised with <span class="caps">XML</span> as format, the response will remain empty. In theory, you could create the file <code>app/views/shared/http_status/not_found.xml.builder</code> to generate an error page for <span class="caps">XML</span> requests. A template file without a format <code>app/views/shared/http_status/not_found.erb</code> will be used for any format. This is basically the same way Rails handles templates.</p>
<p>This simple exception handler should be sufficient for most situations. However, it is easy to customize the exception handler to your own liking. See [[Customization]] for details.</p>
2008-09-21T00:32:53-07:00
58496
basicusage
54644
BasicUsage
2008-09-21T01:20:48-07:00
15870