Documentation with RDoc

Generating documentation with RDoc

We’ll suppose that your application is a Rails application.

1. Go to the root of your application
2. Type rake doc:app

This rake task (that uses RDoc) will start generating the documentation for your application. It will detect every controllers, every models, every helpers, every methods, every attributes, every constants, every whatever and will structure all of this in a logical manner. Then, it will output a bunch of HTML files that you will find in doc/app. Moreover, it will detect every comments you wrote and try to include them at the right place in the doc.

Syntaxes and Examples to do comments on your applications :

Text Decoration :

This method is a very critical one in our system. Please be careful!

The text above is bigger because I used 2 heading characters "==" before typing the actual comment. (It‘s like the h1, h2, h3 tags in HTML but instead you use =, ==, === and so on)

Ordering:

1. It takes 2 params
2. We discard the 1st one
3. We put "mister t" in the second one if nothing has been supplied.

As you can see, you can also create ordered lists with RDoc. Just type a digit and then a period before your comment. If you need a non-ordered list, type * or - before your comment. If you need an alpha list, type a letter followed by a period. Note also that RDoc automatically put hyperlinks around method and class names. That‘s a very easy and useful way to help people navigating in your documentation! Hey let‘s try it…

Hyperlink :

RDoc also detects external links, like www.railsthinker.blogspot.com. If you prefer displaying a label instead of an URL address, use the label[url] format instead, like that : www.railsthinker.blogspot.com. If your label as more than 2 words (like in the example), put them inside curly braces, like that {Rock on!} [the url]

HTML basic formatting :

Finally, how about some HTML basic formatting? if it is just one word long, use * hello * for bold and _ hello _ for italic (just remove the spaces). Now if the thing to format is more than one word long, use the more traditionnal and <em> and <b> tags (just a nitpicky question though : Why "b" instead of "strong"?).

One final note :

RDoc is not specific to Rails. Like I said earlier, it is a ruby library and thus you can use it in other contexts. I took Rails because I knew that the % of people using Ruby without Rails was rather small.

Filters in RoR

Hi to all,

Filters enable you to write code in your controllers that wrap the processing
performed by actions—you can write a chunk of code once and have it be
called before or after any number of actions in your controller (or your controller’s
subclasses). This turns out to be a powerful facility. Using filters, we
can implement authentication schemes, logging, response compression, and
even response customization.

Rails supports three types of filter: before, after, and around.

before and after filters are invoked before or after
an action. Rails maintains two chains of filters for each controller. When a
controller is about to run an action, it executes all the filters on the before
chain. It executes the action before running the filters on the after chain.

eg: if u want to do the authentication for few files in ur app. Use this following code

put this code in ur applicaion.rb file of ur respective controller:

def authorize
unless User.find_by_id(session[:user_id])
flash[:notice] = "Please log in"
redirect_to(:controller => "login" , :action => "login" )
end
end

put the below in ur controller file. eg: name_controller.rb


class AdminController <>
end


using this filter u can protect each and every methods under this controller.

After Filter:

U can call this method after u executed any methods ( in ur controller ) like the below code:

class AdminController <>
before_filter :authorize
# ....
end


Around Filters

Around filters wrap the execution of actions. You can write an around filter in
two different styles. In the first, the filter is a single chunk of code. That code
is called before the action is executed. If the filter code invokes yield, the action
is executed. When the action completes, the filter code continues executing.
Thus, the code before the yield is like a before filter, and the code after the
yield is the after filter. If the filter code never invokes yield, the action is not
run—this is the same as having a before filter return false.


Example :

around_filter :one, :two
def one
logger.info("start one" )
yield
logger.info("end one" )
end
def two
logger.info("start two" )
yield
logger.info("end two" )
end

Output:

the sequence of log messages will be
start one
start two
. . .
end two
end one

Simple AJAX concept : observe_field

Hi to all,

There are lot of ways to do AJAX in ruby on rails. This is one of the easiest way i found. Use the observe_field method.

Syntax:

observe_field(field_id, options = {})


Sample Code:

In the view u need to put this code:

Search By:

<%= select("listing", "search_by", [["City","1"],["Zip Code","2"],["State","3"]]) %>

<%=observe_field("listing_search_by", :url=>{:controller=>"search",:action=>"updatefields"},
:update=>"updatefields", :frequency => 0.5)%>

<label id="updatefields">Enter the City</label>

<%= text_field_tag :query%>

Note: frequency determines the speed ( in seconds ) if it less than zero its event time observer.

Controller code:

def updatefields
@rvalue=request.raw_post
if @rvalue == "1"
@value="Enter the City"
elsif @rvalue == "2"
@value="Enter the Zip Code"
else @rvalue == "3"
@value="Enter the State"
end
end


The above sample code is used to display the label. Dynamically search text field's label is going to change... we can manipulate with the data avail in the database also(without reloading the window or browser. ie AJAX). This is easy to learn and simple to use and effective in the output.

Use and Enjoy.....

(If i made any mistake or u need any more clarification on this prompt me at gokulamurthy@gmail.com)