Hello World!

Main.html

<html>
<head><title>Hello World!</title></head>
<body><h1>Hello World!</h1></body>
</html>

Before this HTML file can become an Iowa application, you also need to provide a short Ruby program that will start the Iowa application process. There is a template for this provided in the distribution. It is at utils/startup_template.rb. A template of the configuration file that it uses can also be found at utils/startup_template.cnf. The startup script establishes a subclass of the Iowa::Application and of the Iowa::Session classes to contain any application specific changes, then forks itself, establishing a persistent backend process, while the parent process exits. The backend process uses the configuration file to tell it what port to listen on and where to put the logs that it writes. For the application above, and really, for most applications, the startup script and configuration files will look a lot like those that follow.

hello_world.rb

#!/usr/local/bin/ruby
require 'iowa'
#require 'iowa_webrick' #Uncommment here and comment above to use WEBrick
class MySession < Iowa::Session
def initialize(*args)
#####
#// One can setup special per/session objects or data items here.
#####
super
end
end
class MyApplication < Iowa::Application
def initialize(*args)
#####
#// Initialize any application wide items here.
#// An example would be a database connection
#// connection pool.
#####
super
end
end
Iowa.startDaemon('hello_world.cnf')
Iowa.run

hello_world.cnf

socket:
hostname: localhost
port: 9988
logging:
basedir: /var/log/iowa/hello_world
minlevel: 0
maxsize: 10000000
maxage: 86400

Iowa, when not coupled with WEBrick, runs applications run as persistent processes that communicate via a socket. Iowa supports both TCP sockets and Unix domain sockets. In this example, the application is being told that it should create a TCPServer attached to port 9988 of localhost. If the hostname is omitted then localhost is assumed, as well. If one want to use Unix domain sockets, then instead of providing a port and a hostname, one should provide a path that can be used as the socket.

When setting up your web server to communicate with the application, regardless of the method of communication chosen (as discussed in the Getting Started section), you will have to provide a descriptor that specifies the socket to connect to. If you are using TCP sockets, the descriptor should look like:

localhost:9988

If one uses Unix sockets, one should just provide the path to the socket:

/tmp/iowa.hello_world

If one wants to use Iowa integrated with WEBrick, things are a little bit simpler. When running with WEBrick, the WEBrick process and the Iowa process are the same process, so no socket is needed for communications. To make the process use WEBrick, just change the

require 'iowa'

statement into a

require 'iowa_webrick'

statement. If you do nothing else, when you run the startup script, your application will be ran with WEBrick and will be available on port 2000, by default.

Since WEBrick is a complete web server that can deliver standard content such as HTML and images as well as execute CGI scripts, one can provide it with a docroot directory that it will look in to deliver any non-Iowa content, as well as a cgiroot directory that it will look to for CGI scripts. By default, the docrrot that it looks for is ../htdocs relative to the directory that the Iowa application is in. Also by default, the cgi-bin root is defined as ../cgi-bin and the cgi prefix on urls is /cgi-bin. If these directories can not be found, however, the code is smart enough not to use them.

Overriding these defaults is simply a matter of adding an additional section to our .cnf file:

port: 80
docroot: ../doc
cgiprefix: /cgi
cgiroot: ../cgi

When running with WEBrick, the socket section of the configuration file is not needed. However, there is no harm in it being there, so if you think that you may switch to, for example, using Apache with mod_iowa to access the Iowa application after you have finished developing it, you may as well leave it in.

Okay, back to our application. This is a very, very simple Iowa application. It is nothing more than a standard bit of regular static HTML. However, if you start an Iowa process (as described above) within a directory that contains this file, Iowa will turn this file into class, and when you view the page generated by that Iowa process, it will display this HTML. In fact, here is a link to a running example. As you can see, this application doesn't really do much. There is nothing gained here over just accessing the file directly as an HTML file. So let's add a little bit to it. Let's show the current date and time on a line after the "Hello World!" is displayed.

Main.html

<%
class Main < Iowa::Component
def current_time; Time.now.to_s;end
end
%>
<html>
<head><title>Hello World!</title></head>
<body><h1>Hello World!</h1>
@current_time</body>
</html>

What's this? The file now has code in it?

Iowa provides two methods of associating code with content. The first is what is shown above. The code gets wrapped in <% %> at the top of the file, and everything after is the content. The other method is to split the code block off into its own file, as shown below: Main.iwa

class Main < Iowa::Component
def current_time; Time.now.to_s;end
end

If Iowa finds a file with the same name as a content file, but with a suffix of iwa, that file is assumed to be the code file that goes with the like named content file. Code files are just regular Ruby files that define a class for this particular content object. You will almost always want to use the Iowa::Component class as the parent. Each of the methods that are defined within the class can be invoked within the HTML simply by prepending the method name with an @ character. Anything that starts with an @ character is interpreted to be a method name.

One other thing that you probably noticed is the name of the files. Our HTML file was named Main.html. An Iowa application has to have a default entry or starting point. This is the component to display at the start of a session. Iowa expects this starting point to be called Main. Thus, all Iowa application have to have, at a minimum, a Main.html file. Another thing to remember about file names is that since the HTML and code files collectively define a component class, Iowa wants the file names to conform to Ruby's rules regarding valid class names. This is currently a requirement. I am currently considering whether this requirement is a good or a bad thing; it may be loosened in a future release.

So, what should happen is that we should see the current date and time displayed on the next line after our "Hello World!" line. You may click here to see if it worked.

Iowa replaces a method invocation with the result returned by that method invocation. This single, simple mechanism is the fundamental way through which data produced in the code gets merged into the content, and it works equally well for any sort of method access, including accessors and the object an accessor may contain. So, for example, if there were an accessor, start_time defined in the code, and start_time contained a Time object, then this would work:

@start_time.now.to_s

Letting The World Talk Back

An important part of web applications is the handling of HTML forms. Forms present the user with some set of input fields, radio boxes, checkboxes, text areas, and listboxes in order to get input back from the user. Forms in an Iowa application work exactly as one would expect, except that one provides method names for handling of form submissions, and one provides accessors to receive the data from each of the form elements. The HTML for this looks like this:

<form oid="talk_back">
World, how are you today?<br/>
<input type="text" size="60" maxlength="250" oid="words"><br/>
<input type="submit" value="Talk Back" oid="talk_back">
</form>

In our code file, we are also going to want to add this:

attr_accessor :words

Notice that the oid attribute appears in several places in that example. Generally, when a tag contains an oid attribute, that is Iowa's clue to step in and apply some special handling of that tag. In the case of the <form> tag, the oid attribute both alerts Iowa that the form is one that the Iowa application will be handling, and provides a default method to invoke on form submission. In this case, unless another control specifically named a different method, form submission will invoke the talk_back() method.

The next place where oid appears is in the first <input> tag. The tag is written exactly like it would be in any other form, except that the name attribute which would normally be there is absent, instead replaced by the oid attribute. In this form, @words will be accessed in order to provide the starting value of the field, and after the form is submitted, the value of the field will be inserted into @words. This mechanism lets forms values be handled via regular Ruby variables from within the code, and it essentially works the same way for all form input tags.

In the final line there is a tag to create a submit button. As in the prior example, the name attribute has been replaced by the oid. In the case of a submit button, the oid specifies the method to invoke when the button is pressed. This example invokes the same method that we specified in the <form> tag earlier, the talk_back() method. It will be up to this method to process the data gathered from the form and to specify what the application should do next.

So, what will this talk_back() method do? Since this is already a pretty contrived example, let's bring it to a contrived conclusion. Our talk_back() method should take the input from the form and just pass it on to a new page, where it will be displayed. It's also going to deactive any HTML that it finds. To do this, the code would be:

def talk_back
@words = @words.gsub('<','<').gsub('>','>')
new_page = page_named('TalkBack')
new_page.world_words = @words
yield new_page
end

That's it. Since pages are components, and components are objects, to pass control to a new page, we just instantiate it with the page_named() method. We can then assign values to any accessors, or call any other methods that might need to be called before that compent receives control. Once everything is ready, a call to yield() with the component as an argument passes control to that component. Note that if a method does not yield(), the current component retains control and the current page will be redisplayed. There is also a method available, reload(), that, when called, causes the current page to be reloaded. In most cases one never needs to call this method explicitly, however.

For completeness, here's the HTML and the code for the TalkBack component:

TalkBack.html

<html>
<head><title>The World Talks Back</title></head>
<body><h1>The World Talks Back</h1>
<p>@world_words</p>
</body>
</html>

TalkBack.iwa

class TalkBack < Iowa::Component
attr_accessor :world_words
end

Here's a link to a live demo of this Hello World application.

In the next section the rest of the building blocks that Iowa provides to application developers will be introduced. These include the remainder of the special markup tags and bindings.

Do you have a comment or a suggestion?

Client Login
User ID:
Password: