Iowa Reference
Application Structure
Iowa applications generally subclass Iowa::Application in order to define additional resources available to the application or to customize application parameters such as the initial session cache size. If the application interacts with a database, an Iowa::DbPool object can be created to provide a database connection pool. Additionally, application wide data resources can be initialized here. For example, if the application had several different forms that all provided lists of states or countries, a data structure with the state or country names could be initialized in the application subclass so that it would be available all throughout the application.
An application holds instances of Iowa::Session in its session cache. Each instance of Iowa::Session represents one user's interaction with the application. Iowa::Session can also be subclassed in order to provide any special per session initializations or to customize initial session parameters, such as the size of the session's page cache.
Each session maintains a cache of pages. Each page is an instance of a subclass of Iowa::Component. Components may also contain other components. Components contains static text as well as dynamic tags.
Every request is represented by an Iowa::Request object. The request object is placed inside of an Iowa::Context and then delivered to the session for handling. Every session, when first created, is given a unique identifier. Iowa uses a pure Ruby implementation of the ISAAC random number generator, Crypt::ISAAC. ISAAC is intended to be a cryptographically secure random number generator.
Iowa parses the content template for a component only the first time that it is loaded. If the content template or the code are change, Iowa will detect the change and reload both the code and the template.
Dynamic Tags
Dynamic tags are HTML or HTML-like tags marked by a special attribute, oid. Each dynamic tag maps to a class that defines that tag's behavior. When Iowa parses the content template, it stores a representation of the template as sequences of static text and objects for the dynamic tags. When the component is displayed, Iowa walks through this internal representation, constructing the response that will be sent back to the users browser by concatenating the static pieces of content with whatever content each of the dynamic tags returns for itself. Thus, each dynamic tag is responsible for its own representation in the content.
| Dynamic Tags, Not Form Related | |
|---|---|
| A | Links back into the application. |
| STRING | Invokes a method and inserts whatever the method returns. The same as using @METHOD in a template. |
| REPEAT | Repeats whatever content it encloses. |
| TABLE | Subclass of Repeat. Outputs a <table> tag and then repeats the content that it encloses. |
| TR | Subclass of Repeat. Outputs a <tr> tag and then repeats the content that it encloses. |
| UL | Subclass of Repeat. Outputs a <ul> tag and then repeats the content that it encloses. |
| OL | Subclass of Repeat. Outputs a <ol> tag and then repeats the content that it encloses. |
| IF | Invokes a method. If the return value of the method is true, the content that it encloses is displayed. Otherwise, the content that it encloses is not displayed. |
| SPAN | Invokes a method. If the return value of the method is true, the content that it encloses is displayed. Otherwise, the content that it encloses is not displayed. |
| UNLESS | Invokes a method. If the return value of the method is false, the content that it encloses is displayed. Otherwise, the content that it encloses is not displayed. |
| Dynamic Tags, Form Related | |
|---|---|
| FORM | Identifies a form that will be handled by the Iowa application. |
| INPUT | Takes some form of user input and delivers it to the application. Exact behavior is determined by the type of input field. |
| INPUT type="text" | A text input field. |
| INPUT type="password" | Like a text input field, but the exact text entered is obscured on the screen. |
| INPUT type="checkbox" | A box that can either be on/off (true/false). |
| INPUT type="radio" | A set of multiple toggles, except only one can be on at a time. |
| INPUT type="submit" | Invokes a method in the application for processing the form. |
| INPUT type="image" | Like a submit field, but the button is an image. |
| TEXTAREA | A multirow text input area. |
| SELECT | Presents a listbox for selection of values. |
| OPTION | Used with a select to indicate what the box should show. |
| Iowa Classes | |
|---|---|
| Iowa::Application | This is the superclass for all Iowa applications. |
| Iowa::Client | The tasks involved in sending a request to an Iowa application and getting a response from it are encapsulated with Iowa::Client |
| Iowa::Component | |
| Iowa::Context | |
| Iowa::DbPool | This is a database connection pool class that is packaged with Iowa. I recommend that any application that interacts with a database do so through a connection pool in order to limit the number of database like database connections that the application requires. |
| Iowa::FileData | When doing file uploads with Iowa, the uploaded file is returned to the application within an Iowa::FileData object. |
| Crypt::ISAAC | This is a pure ruby implementation of the ISAAC random number generator. ISAAC is a cryptographically secure random number generator with no cycles shorter than 2^40, and an expected cycle length of 2^8287. Crypt::ISAAC is also available as a seperate package. |
| Iowa::LRUCache | Iowa uses an LRU cache to store sessions and pages. |
| Iowa::Request | Iowa::Request is made to very closely resemble an Apache::Request, while still being marshalable. It is used to encapsulate a request to be sent to an Iowa application. |
| Iowa::Resource | An Iowa::Resource is used when one is generating inline content such as images from within a Ruby application. |
| Iowa::Session | Every unique session within an Iowa application is represented as an Iowa::Session or as a subclass of Iowa::Session. |
