Your First Application in Aptana RadRails

Here we are! programming in a powerful language specially designed for the Web and using an IDE that promises to help us with many of the mechanical tasks involved in the coding.

If you have been already programming with Rails, you probably know that if we take advantage of scaffolding we can have a simple web application for table maintenance in a matter of minutes (yes/no typo here, it really takes just a few minutes). And we are even talking about the database table creation process.

If we wanted to add validations, a nice design, and some more complexity we would be talking about a few hours. Still pretty impressive, depending from which programming language (or framework) you are coming.

The truth is, creating the wireframe of your application in Rails is quick and easy enough even from the command line, but we'll be learning in this article how to do it a bit more comfortably by using RadRails for creating your models, controllers, database migrations, and for starting your server and test your application.

Basic Views

Most of the time when working with our IDE we will be using the Editor Area. Apart from that, two of the views we will be working with more frequently are the Ruby Explorer—the enhanced equivalent of the Rails Navigator, if you were using RadRails Classic—and the Console.

Both of these views are fairly easy to use, but since they will be present at almost every point of the development process, it's interesting to get familiar with them from the beginning.

The Ruby Explorer View

If you have already opened the Rails perspective, then you should be seeing the Ruby Explorer at the left of your workbench.

Your First Application in Aptana RadRails

This view looks like a file-tree pane. At the root level, you will find a folder for each of the projects in your workspace. By clicking on the icon to the left of the project name, you will unfold its files and folders. The Ruby files can be expanded too, displaying the modules, classes, variables, and methods defined in the selected file. By clicking on any of these elements you will be taken directly to the line in which it is defined.

Before navigating through the contents of a project, we have to open it. Just right-click on its name and choose Open Project.

When opening a project, Eclipse will ask you if you want to open the referenced projects. By default, your projects don't have any references and that's the most common scenario when working with a Rails application.

Your First Application in Aptana RadRails

If you want, you can include references to other projects on the workspace so you can open and close them together. To view and change the project references, you can right-click on the project name, then select Properties. Notice you can also get here from the Project menu by selecting Properties. In the properties dialog, you have to select Project References. Here you will see a list of all the available projects in the workspace. Just check or uncheck all the projects you want to reference.

Your First Application in Aptana RadRails

Once your project is open, the mechanism for navigating the contents is pretty straightforward. You can open or close any sub-folders and you can right-click on any item to get a context menu. From this menu you can perform common file operations like creating, renaming, or deleting a file.

We will see more details about creating new files when talking about the Editor Area. There is also a Properties option from where you can change the encoding for a particular file, or the file attributes (read only, for example). The Properties option is also available at the project level.

Your First Application in Aptana RadRails

Also in the context menu, you can see there is a Tail option. This will work like the tail command in UNIX, displaying the contents of a file as it's changing. This option is especially useful for a quick monitoring of the log files of your application.

You can also find in the context menu two options with the names Compare With and Replace With. If you select either of them, you will see a new menu in which there is an option named Local history. This functionality is really interesting. You can compare your current version against an older version of the same file, or you could replace the contents with a previous one. This can be a life-saver because when using it on a folder the local history will contain copies even of deleted files.

Your First Application in Aptana RadRails

Comparing a file against another copy is a powerful tool, which can also be used when working with repositories or to compare different files between them. Let's try it and see how it works.

Open any of the files in your project tree by double-clicking on the file name. Now go to the Editor Area and add some lines with Mumbo-Jumbo text. After you are done, click on the save icon of the toolbar or select Save in the File menu. Now let's go back to the Ruby Explorer, double-click on the file name and select Compare With | Local History.

You will see there are some entries here, one for each time we saved the file. If this was the first time you worked with the file, then there will be only two versions, the original and the one you just saved. Double-click on the oldest local version you have.

Your First Application in Aptana RadRails

Now a new editor will be opened. The editor is divided into three panes, the top one displaying structural differences, the bottom-left one with the code of the current version, and the bottom-right one with the old version of the code.

At the top pane, you will see the structural differences between the versions being compared. For every added or deleted method or variable—at instance or class level, you will see the name of the element with an icon displaying a plus or a minus sign. If a method exists in both versions, but its content was changed, the name will be displayed without any additional icons.

Your First Application in Aptana RadRails

When reviewing the differences/changes you will see the editors at both sides are linked with a line representing the parts that are not equal between the files. When you are on a given change/difference you can select the icon for 'copying current change from right to left' (or the other way round, depending in which of the files the change is), which will override the contents of the left editor with those of the right. You can also just manually edit or copy/paste in your editor as usual.

There is an interesting icon labeled 'Copy all non-conflicting changes from right to left' that will do exactly as it promises. Any changes that can be automatically merged, will be incorporated to your editor. Depending on the differences between the files, the icon could be the contrary 'Copy all non-conflicting changes from left to right'.

When you finish comparing or modifying your current editor, remember to save the contents of the editor in order to keep your changes.

If you just wanted to review the changes without any modifications, you can directly scroll down the editors, use the 'Previous' or 'Next' icons, or use the quick marks by the right margin.

Your First Application in Aptana RadRails

You can also compare two files instead of comparing a file against an older version. Go to the Ruby Explorer and select one of the files, then hold down the control key and select another one. With both files selected, you right-click and select Compare With and then Each Other. Once opened, the compare editor works exactly the same as when comparing with an old version of the same file.


Ruby Explorer Top Icons

Before we finish with the Ruby Explorer, there are still a few functionalities we want to take a look at.

By default, the Ruby Explorer and the Editor Area are not linked, meaning that when I open a file from the Explorer the editor displays that file but not the other way around. If you select an open editor, it will not be selected for you in the Ruby Explorer. Sometimes, it's handy that both views are not linked, but most times I find it more convenient to have the current file automatically selected in the Ruby Explorer. Just select the icon with the two arrows on the top right of the Explorer view. By clicking on this icon you will toggle the linked views function.

Your First Application in Aptana RadRails

You can also access this option from the menu you get by clicking the small triangle to the right of the icon.

The next icon to the left, with a minus sign, is used to fold all the items. If you have a lot of sub-folders and you have opened lots of them, it comes handy to put some order in your view.

When you have lots of projects in the workspace, even if most of the projects are closed, still they occupy a place in your Explorer view. Often you don't want to see the whole list of projects but just to focus on your current project and hide the others. If you right-click on the name of your project in the Ruby Explorer and select Go Into, you will get exactly this functionality. You can also activate it through the Navigate menu on the top of the workbench. Notice you can do this on any given folder, and not just at the root project level.

If you go into any project or folder, then the first three icons of the Explorer view toolbar can be used to navigate your tree in a browser-like way. You can go back or forward to the last location, or up a level by using these controls. Unless you have gone into a project or folder, the icons will be deactivated.

The Console View

The console is the standard way for displaying any text output, especially when launching processes or applications such as Rake tasks, servers, or Subversion commands. Some other actions, like selecting Tail from the Ruby Explorer, will use an output console too.

When any of these actions is launched, a new console will be displayed in the console view. If the console view is open but it's in a tabbed view and it doesn't have the focus, the title of the tab will be displayed in bold so you can see that there is new output requesting your attention.

Your First Application in Aptana RadRails

When you launch a command that opens a console, it will not open a new view, but will reuse the existing view tab, hiding the contents of the former console. Nevertheless, the old console remains active in the background. You can select which of the active consoles to display by selecting the icon with a screen (labeled 'Display selected console'). Selecting the icon itself will rotate through the opened consoles, and selecting the small arrow will present a list so you can select which one to display.

By default, when an action is launched or a console receives some output, that console will move to the top hiding the others. You can change this behavior by 'pinning' the current displayed console. Selecting the icon with the pin (see above screenshot) will make your console always be on top unless you explicitly select a new one from the opened consoles list.

The icon clear (see above screenshot) represented by a paper sheet and a cross on the corner just cleans the console output. The console stays open and it will display all the new output.

The scroll lock icon (see above screenshot) will prevent the console from scrolling when new output is received. For fast changing output is very useful since otherwise, it gets impossible to keep track of what's going on. This icon has a toggle-like functionality. You can switch it on or off with a single click.

If you want, you can have several console tabs opened at the same time, each of them displaying a different console output. To do so, unfold the open console menu (see above screenshot), which is the small down-arrow by the top-right of your console view, and then select New Console view. That way you can have different outputs displaying side by side instead of having to keep selecting from the drop-down.

Depending on which type of console you are displaying, there will be some additional icons. The captions on top of the icons are self-explanatory, and what you can do with these icons is usually any of these actions: stop the current process or server, close all the terminated consoles, close the current console, and make the console view display automatically whenever it receives new output. This last option will cause the console view to show directly instead of just marking the tab title in bold.

Notice that in some cases the console can prompt you for some input and it will keep waiting until you answer. In that case, you have to type directly in the console, which will be the Standard Input for the process. For example, if you are trying to launch a process that would overwrite some files, the process could ask what to do (yes/no/always).

During the next sections in this article, we will be using the console to monitor our generators and to check everything is working properly.

The Generators View

You know that, when you work with Ruby on Rails, there are several generators available, which you can invoke from the command line. By using these generators, you can create controllers, models, migrations, scaffolds, unit tests, or plugins, for example. A generator will create one or several files in the appropriate places of your Rails project, so you can customize them to meet your needs, saving you from all the mechanical and boring process of creating the files with the proper syntax inside.

Doing this from the command line is easy enough, but you do have to remember which flags you can use, change context from your code editor to the command line and back, and so on. By using the Generators view integrated in RadRails, you can comfortably create any of the available generators in a more convenient way.

In the default Rails perspective, you can find the Generators view as a tab in the lower pane of your workbench. If you cannot see the Generators view, you can go to the Window menu, select Show View, and select Generators.

Your First Application in Aptana RadRails

The first thing you have to do when opening the Generators view is make sure there is a Rails project selected in the Ruby Explorer. If you don't have a Rails project selected, then select one now. You can also select the project you want to work with from the 'Select Rails Project' icon in the toolbar of this view.

In the drop-down list by the left of the view, you will see a list of all the existing generators for the current project. As you probably know, in Rails you can install new generators for your projects. To be sure you are displaying the right list of generators for the selected project, you can click on the 'Refresh' icon located at the top-right corner of the view (it's the icon with two arrows). After refreshing, we are sure the generators in the drop-down list are the ones available for the current project.

Once you select any of the generators, there are several things you can do with them. If you are not sure about what a generator does, you can select the Help button. This will display a pop-up window with the explanation for this generator. Let's select controller in the drop-down list, and then click on Help to see how it works.

Now let's go back to the Generators view by clicking on the tab name. Apart from the drop-down list and the Help button there are some other options in this view. Let's start by explaining the long drop-down list close to the generators list. Here you can type any parameters you want to supply to the generator. Depending on which type of generator you are launching, the number and meaning of the parameters may vary. Check with the help of the generator if you don't know which are the available parameters. This input element is a drop-down list instead of a simple text box because you can open the list and see the history of the parameters you used in previous executions. (Note that the list will display the recent entries only for this Eclipse execution. When you close the IDE the list will be cleaned.)

When working with the generate script in Rails, you can do one of two things: either creating or removing the files for the selected generator. There is a radio button below the generators list in which you can select which of the two actions to perform.

Finally, when launching a generator, there are some flags you can use to control the behavior of the script. You can find all the flags as checkboxes. The available options are:

  • Pretend: It just executes the generator displaying the output but without making any real changes in the file system.
  • Force: If there are any existing files, the generator will overwrite them without asking for your confirmation.
  • Skip: If there are any existing files, they will be automatically skipped.
  • Quiet: This will execute the script without displaying any output.
  • Backtrace: In the case of any errors, this will display debugging information.
  • Use SVN: Changes in the file system will be reflected on your repository. In order to do so, the 'svn' command must be available in the path.

Now we know our way around the Generators view, we are going to create a very small application by using different generators. Even if it's possible to get everything with a single generator, for the sake of learning the mechanics, we will create the models, migrations, and scaffolded controllers needed for a simple two-table maintenance.

Generating Models and Migrations

Our small application is going to be for the maintenance of two tables: Books and Comics. The first thing we'll need for this application is to create the tables and the models that will represent them from the Ruby layer.

We are going to use these tables as examples, so we are going to keep them unrealistically simple. The Books table will have only a title, author name, and date of publication. The Comics table will have the same fields and an extra field for the illustrator name.

To create the models and the corresponding migrations we will go to the Generators view and select Model from the drop-down list. As you probably know, the parameters for generating a model are the name of the model itself and then an optional list of pairs of field names and types separated by a colon (notice there is no space between the name, the colon, and the type), so we will write the following parameters on the parameters field:

Book title:string author_name:string publication_date:date

After we type in the parameters, we have to make sure the radio button below the generators list is set to Create and then we can click on Go.

After some seconds we will be presented with the console output. Even when doing routine tasks, be sure you take a look at the displayed output. Sometimes there are small errors, or the application may need some kind of confirmation if there are existing files, and you would get that information as part of the output. Besides, recent versions of RadRails will present the output as hyperlinks to the generated files, so you can click at any file name directly on the console and it will open in the appropriate editor.

After the generation is done, we can go to the Ruby Explorer and look for the app | models folder of our project. A file with the name book.rb should be there. Also, take a look at the directory db | migrate. A new file named 001_create_books.rb should exist. If you open this file, you will see the commands for creating and deleting the Books table in our database.

Your First Application in Aptana RadRails

Now let's repeat the operation for the Comics table. First we go to the Generators view and select Model in the drop-down list, then we type the following arguments (notice it's a single line):

Comic title:string author_name:string illustrator_name:string

After getting the console output, if you go to the Ruby Explorer you will see the newly created files.

Notice it's also possible to generate a migration file without any model code (for example, when you are adding or removing a column) just by using Migration instead of Model from the generators list. Also, it's possible to generate a model without a migration by passing the extra parameter --skip-migration.

Running Your Migrations

We already have our migrations describing the tables to create, but we still haven't made any changes to the database. In order to actually create the tables, we will have to run our migrations.

The first thing we have to do is configure our database connection. Look in the Ruby Explorer for the file named database.yml in the folder config. You will have to modify this file and specify your adapter type, host, database name, user, and password.

If you are going to use SQLite as your adapter, then you don't need to create the database beforehand since it will be done automatically for you. However, if you are using a different adapter you have to create the database before trying to run the migrations. If you are using Rails 2 and the user configured in your database.yml has enough privileges, we can take advantage of the built-in Rake task db:create to automatically create your database. If you are using an older version of Rails, or your user doesn't have privileges for creating databases, you will have to create it manually in your DBMS.

To create your database using a Rake task, go to the Ruby Explorer and right-click on the name of your project. In the context-menu, open the Rake option and then select db and create. This will launch the selected Rake task. Look at the console so you can see if there were any errors.

With the database created we can already run our migrations. We can execute the Rake task from the context-menu as we just learned, but there is a specialized Rake Tasks view, which provides some more functionality. Even if we don't need all that functionality at the moment, we can use it for running our migrations. Open this view by selecting the Rake Tasks tab. If you cannot see it, then open it from the Window menu, by using the Show View option.

Your First Application in Aptana RadRails

You will see this view looks pretty similar to the Generators view. Make sure your project is currently selected on the Ruby Explorer then hit the Refresh symbol of this view. Once the drop-down list is refreshed, you have to select the task with the name db:migrate and click on the Go button. After some seconds, you should see the results of running our migrations on the Console. If everything went well, now we have our tables created on the database.

Your First Application in Aptana RadRails

Generating Scaffolds

Now the Models and Migrations are created, we will have to create the Controllers and Views so we can start playing around with our application. Generating a controller is as easy as generating a model or a migration. If you go to the Generators view, you can see there is an option named controller in the drop-down list. If we were to use that option, we would get an empty controller, and some related files and folders for testing purposes.

However, Rails provides a more convenient way of creating a controller if you are going to use it for table maintenance. Of course we are talking about generating Scaffolds.

Obviously, you never want to use exactly what the scaffold provides, but you know how it is with programming. If you have to start from scratch, you feel lazy and it takes a while to get up and running; but if you already have some code and you only have to modify it then the things get done much more quickly.

Instead of using the Generators view to generate a stand-alone controller, we can generate a controller containing the source code for all the methods provided by the scaffold. Besides, we will get the views, so we can customize them as we please.

This functionality is provided by the Scaffold generator. This generator will create your controller, your views, and if the model doesn't already exist, it will create both the model and the migration file too.

Even if this generator can create the whole set of files, if you prefer to, you still can generate your model first together with the corresponding migration, then run your migration, and then run the Scaffold generator. As long as the name of the Model and that of the Scaffold match, everything will be fine and you will not get any errors.

We will create now the scaffolded controller for the model Comic. Go to the Generators view and select Scaffold from the drop-down menu. We will write Comic --skip-migration as the argument, and click on Go to launch the generator.

The '--skip-migration' argument is necessary because we previously created the migration, and the current scaffold for Rails 2 will stop if the migration file exists, without giving the option to ignore or overwrite. If you are generating a Scaffold without first creating a migration, don't use that argument.

As usual, after some seconds you will see the output in the console telling you about the generated files. Since the Comics model already existed because we created it in a previous step, you will see in the console this file was skipped by the Generator. To see the scaffolded controller, you can go to the Ruby Explorer, and open the file comics_controller.rb under the folder app | controllers, or you can directly click on the comics_controller.rb link in the console. When the file opens, you will see the methods are coded here. If you need to change any of them, you only need to modify the existing source.

Also, if you take a look at the app | views folder, you will see a new folder comics has been created for you. Inside this folder there are all the necessary views for our small application. Notice a layout named comics.html.erb has been generated in the folder all | views | layouts.

Your First Application in Aptana RadRails

Now let's generate the scaffold for the model Book. Go to the Generators view, select Scaffold from the drop-down menu, write Book --skip-migration as the argument, and Click on Go. The console will display all the files automatically generated for us.

This is starting to look like a good starting point from which we can customize our application without having to take care of the mechanical details of creating classes, views, and basic methods.

I know what you are thinking; this looks OK, but you want to see it running at once and see how it looks. You know, your wish is my command, so let's start our Rails server and play with our small application.

Starting Your Server

Starting your Rails server from RadRails is really easy, but it may require just a little bit of setup. If you remember, there was a checkbox to create a Mongrel server.

Creating a server in RadRails will allow us to start, stop, or restart our servers directly from the IDE and get the output in the integrated console, rather than having to work from a command line.

If you didn't create a server when creating your project, you can do so now. Right-click on the name of your project in the Ruby Explorer, select New and then Rails Server. We'll go about the server options later in the article, so for now it's OK to accept all the default options.

Your First Application in Aptana RadRails

Just a quick note, if you want to work with a Mongrel server, you must have it installed in your system. If you select to create a Mongrel server, but you haven't installed Mongrel, RadRails will ask you if you want to have it automatically installed.

If you had any problems with the automatic installation, you could try to install Mongrel manually as a gem by opening a command prompt and executing:

gem install mongrel_rails

Note that in some OS you will need either a privileged user or to execute this command via sudo (sudo gem install mongrel_rails).

Now that we already have a Rails Server configured, we only have to start it. We are going to use a new view for that. The name of the view is Server and it's one of the default views in the Rails perspective. If you cannot see it, just open it as usual from the Show View option of the Window menu.

Your First Application in Aptana RadRails

In this view, you will see an entry for each configured server (only one if this is your first project with RadRails). We are going to start our server, so make sure your database is running or start it if it's not. Now, right-click on the entry corresponding to the project we are working with and select Start.

After a little bit,you will see the console view displaying the usual server output. Once you see the server is started, we are going to try our application. Directly at the console view toolbar, there is a Launch Browser icon. Alternatively, you could go back to the Server view, right-click on the name of your server and select Launch Browser. In any case, the integrated browser will open and you should be seeing the Rails index page.

First we are going to take a look at our Books table maintenance functionalities. After the host and port of the URL, write books, so it will look something like http://localhost:3002/books (don't change the port number in the URL, or you will not be able to connect to your server).

In the browser, you will see an almost empty screen with the title Books Listing and a link to add a new book. Click on the link and a form for entering the book information will be presented.

Your First Application in Aptana RadRails

After entering some example data and accepting the form, you'll be redirected back to the listing screen, in which you can already see your brand new book. You can add more books, edit, show, or delete books.

If you change the world 'books' to 'comics' in the URL of the integrated browser, you will see exactly the same but for the Comics table.

Now with this skeleton created, we can start customizing our application, changing the appearance, adding validations, whatever needs to be done, but without all the hassle of the creation of the basic structure.

Monitoring Your Server

You know how convenient is to take a look once in a while at the Rails log file to see which actions are being called, which parameters are being passed, or what SQL is being sent to the database. By using RadRails, we can have one integrated view continuously monitoring the log of our server.

Go to the Ruby Explorer, open the log folder and right-click on development.log. Now select Tail from the context menu. By doing so, you will be display in the Console view the contents of the development log file as they are being written.

If the Console view is not in the foreground, click on the tab named Console to bring it to the front. Now go to the integrated browser and just navigate around a bit, creating or editing some records. You will see in real time the information being written to the log of your project.

Your First Application in Aptana RadRails

Here the Pin Console icon comes in most handy. Otherwise, the console output from the server and that of the log viewer will keep fighting to become the focus/foremost, since by default every time there is new output in any of the consoles, it will be brought out to the front If you’d rather just stick to seeing one or the other, you ought to 'pin' it down.

This tail feature is ok for a quick inspection of your logs. However, since version 1.0 of RadRails there is a new view, the Tail view, which has some more advanced features at the extra cost of a minimal setup.


In this article, we have learned how to use two of the views we will be using most of the time when developing with RadRails. By using the Ruby Explorer, we can browse the structure of our projects and make file-related tasks, which include working with the local history or file-comparison. From the Console view, we will have access to the output of every process we launch from our workbench, so we don't need to go to the command line or use a third-party application for monitoring the results.

We have also seen how to use the Generators view in order to create models, migrations, controllers, and scaffolds, and how we can start our Rails server and use an internal browser for quick testing of our applications, making the development process much more comfortable, and letting us focus on what we need to do and not on which tool we are using.

If you have read this article you may be interested to view :

You've been reading an excerpt of:

Aptana RadRails: An IDE for Rails Development

Explore Title