Opening the RadRails Views
Some of the views that we will go through in this article are available as part of the Rails default perspective, which means you don't need to do anything special to open them; they will appear as tabbed views in a pane at the bottom of your workbench. Just look for the tab name of the view you want to see and click on it to make it visible.
However, there are some views that are not opened by default, or maybe you closed them at some point accidentally, or maybe you changed to the Debug perspective and you want to display some of the RadRails views there. When you need to open a view whose tab is not displaying, you can go to the Window menu, and select the Show View option.
If you are in the Rails perspective, all the available views will be displayed in that menu, as you can see in the screenshot above. When opening this menu from a different perspective, you will not see the RadRails views here, but you can select Other.... If this is the case, in the Show View dialog, most of the views will appear under the Ruby category, except for the Generators, Rails API, and Rake Tasks views, which are located under Rails.
As happens with any modern programming language, Ruby has an extensive API. There are lots of libraries and classes and even with Ruby being an intuitive language with a neat consistent API, often we need to read the documentation.
As you probably know, Ruby provides a standard documentation format called RDoc, which uses the comments in the source code to generate documentation. We can access this RDoc documentation in different ways, mainly in HTML format through a browser or by using the command-line tool RI. This produces a plain-text output directly at the command shell, in a similar way to the man command in a UNIX system.
RadRails doesn't add any new functionality to the built-in documentation, but provides some convenient views so we can explore it without losing the context of our project's source.
Ruby Interactive (RI) View
This view provides a fast and comfortable way of browsing the local documentation in the same way as you would use RI from the command line.
You can look either for a class or a method name. Just start typing at the input box at the top left corner of the view and the list below will display the matching entries. That's a nice improvement over the command line interface, since you can see the results as you type instead of having to run a complete search every time.
If you know the name of both the class and the method you are looking for, then you can write them using the hash (pound) sign as a separator. For example, to get the documentation for the sum method of the class Enumerable you would write Enumerable#sum.
The documentation will display in the right pane, with a convenient highlighting of the referenced methods and classes. Even if the search results of RI don't look very attractive compared to the output of the HTML-based documentation views, RI has the advantage of searching locally on your computer, so you can use it even when working off-line.
Ruby Core, Ruby Standard Library, and Rails API
There are three more views related to documentation in RadRails: Ruby Core API, Ruby Standard Library API, and Rails API. Unlike the RI view, these ones look for the information over the Internet, so you will not be able to use them unless you are on-line.
On the other hand, the information is displayed in a more attractive way than with RI, and it provides links to the source code of the consulted methods, so if the documentation is not enough, you can always take a look at the inner details of the implementation.
The Ruby Core API view displays the documentation of the classes included in Ruby's core. These are the classes you can directly use without a previous require statement. The documentation rendered is that at http://www.ruby-doc.org/core/.
You are probably familiar with this type of layout, since it's the default RDoc output. The upper pane displays the navigation links, and the lower pane shows the detail of the documentation. The navigation is divided into three frames. The one to the left shows the files in which the source code is, the one in the middle shows the Classes and Modules, and in the third one you can find all the methods in the API.
The Ruby Standard Library API is composed of all the classes and modules that are not a part of Ruby's core, but are typically distributed as a part of the Ruby installation. You can directly use these classes after a require statement in your code. The Ruby Standard Library API View displays the information from http://www.ruby-doc.org/stdlib.
In this case, the navigation is the same as in Ruby Core, but with an additional area to the left, in which you can see all the available packages (the ones you would require for using the classes within your code). When you select a package link, you will see the files, classes, and methods for that single package.
The last of the documentation views displays information about the Rails API. It includes the documentation of ActiveRecord, the ActionPack, ActiveSupport, and the rest of the Rails components. The information is obtained from http://api.rubyonrails.org.
In this case the layout is slightly different because the information about the files, classes, and methods is displayed to the left instead at the top of the view. Apart from that, the behavior is identical to that of the Ruby Core API view.
Since some of the API descriptions are fairly long, it can be convenient to maximize the documentation views when you are using them. Remember you can maximize any of the views by double-clicking its tab or by using the maximize icon on the view's toolbar. Double-clicking again will restore the view to the original size and position.
We went briefly over the Servers view when creating our first application and also when talking about debugging. This is a fairly simple view, but it's also a very useful one. Basically, you can start and stop your Rails servers (WEBrick, Mongrel, or LightTPD), launch the built-in browser, or start a debugging session.
The Servers view displays all the available servers for the current workspace, and not only for the current project. This view provides a 'project' column, so you can know to which project your server is associated at a glance.
The very first time that you open RadRails after a fresh installation this view will be empty. By default, when you create a new Rails project, RadRails will select the option to create a Mongrel server for it. Unless you manually uncheck this option at the New Rails Project dialog, whenever you create a RadRails project you will see a new server in this view.
If you chose not to create any server from the New Rails Project dialog, nothing would appear in this view, and you wouldn't have a way for starting your server from the IDE, having to switch to the command line for that operation.
In that case, you can add a new server for your project from this view. The first icon in this view's toolbar is the one for adding a new server. You can click directly on the icon, or open the drop-down with the small arrow by its side, and then select Rails Server. There are also options for adding a new server both in the context menu of the project in the Ruby Explorer and from the New option under the File menu. No matter how you choose to add your server, a pop-up will appear prompting you to fill in the server properties.
For the Project name you have to select a project from the drop-down box. Note that, only open projects will display in the list, so make sure your project is open before trying to add a new server for it. The name of your server will be the one showing in the Servers view, so it's in your interest to provide a meaningful name, especially if you have many projects in the same workspace.
The type of project must be one of the three available options: WEBrick, Mongrel, or LightTPD. The only arguments you can provide to the server are the IP address or Host name, the server port number, and the Rails environment. RadRails will default the port number to the first port starting from 3000 on which you don't have any other server configured. If you want, you can change this value and configure two different servers to use the same port.
The new server will be listed in the Servers view. After adding a server, you can at once start it, start it in debugging mode, or stop it. You can perform these operations directly from the view's toolbar or from the context menu by right-clicking on the project name. When you start a server, its output will be displayed at the Console view, providing the same information you would get when starting from the command line.
If you prefer to have access directly to your server logs, you can open the context menu and select the Open Log option. This will display your server's log in the Tail view.
If you need to restart the server, you could just stop and start it or you can use the convenient restart option. If you want to change the properties of your server (port, environment) you can use the Edit option or just double-click on the project's name and enter the new settings. Observe that you cannot edit the server's properties while it's running, so you would need to stop it first.
When your server is started you can easily open the built-in browser pointing to the home page of your project from the Launch Browser option of the context menu.
If you are a user of the Professional version, the Server view will also display an option for launching under profile mode to identify the bottlenecks in your application. Profiling is not available under the RadRails Community version, so we will not cover it in this book. You can find more information in the online documentation of Aptana.
Starting a Server with Additional Arguments
Usually, the only options you need to use for starting your Rails server are the port and environment. However, there are some cases in which you want to provide extra arguments like the mime-types definition file or the timeout for Mongrel, for example. In these cases, you cannot use the built-in Servers view, but it doesn't mean you cannot use Eclipse for managing your server anyway.
If you need to pass extra parameters to the 'script/server' command, you can use the Rails Shell View. If you want to launch your server with extra parameters and without using 'script/server', for example when using mongrel cluster, you can still do it from Eclipse by configuring it as an external tool.
Managing Non-Rails Servers from the Servers View
Since version 1.0, the Servers view has support for Apache, MySQL, and generic web servers. This means you can start or stop your servers and have access to the logs directly from the Servers view.
Please note that your MySQL or Apache will need to be installed and properly configured before trying to start your servers from this view. Installation of MySQL and Apache are out of the scope of this book, so refer to the documentation of those tools if you have any questions about how to set them up.
To add a MySQL or Apache web server to your servers list, use the Add Server icon from the Servers view toolbar, and select MySQL or Apache instead of the Rails Server option. A dialog will display asking for information about your server.
You need to provide information about where the executable is located, and where the log file is. Depending on your server, there will be some extra options you can configure. These options are pre-filled with default values that should work fine for the typical user.
After you click OK, a new entry will be listed in your Servers view, and you will be able to start, stop, and browse the logs in the same way as with any Rails server.