Kiss A simpler, smarter web application framework for Ruby


Creating an Application Running the Application Main Application Components Other Application Directories Adding Actions to Your Application For the Design Pattern Purists

Creating an Application

After installing the Kiss gem, you can create a new application by running the command:

kiss create <app_name>

Kiss will unpack an application scaffold in the current working directory and name it to match the <app_name> you've chosen. This scaffold serves as a starting point for your application, containing a skeleton of basic directories and files. Let's take a quick look at what we just created:

cd <app_name>

These files and directories include a "Hello World!" action, as well as actions for handling very basic user registration and login, and some other stuff to get you started. We'll describe the various components of a Kiss application later in this chapter.

But first, let's see our new application out for a spin.

Running the Application

We assume that you're working with Kiss on your own computer for now, so you should be able to run your application as an app server. Make sure you're just inside the application directory, and then type this command to start the app:

kiss run

The Kiss application will start running on the WEBrick web server. To see it in action, point your web browser to:  http://localhost:4000/

If you see "Hello world!" then you have successfully run your first Kiss application!

Side Note About Running Modes: App Server vs. CGI

The above command runs your Kiss application using a persistent server called WEBrick. Kiss can also be run on Mongrel, Thin, and other servers, or from a CGI script.

Kiss applications perform fastest when run as persistent app servers. This allows one app server process to answer several requests in succession, even multiple requests simultaneously using threads. The app server loads and interprets the Kiss framework just once, when the app is started, so each request can be answered very quickly after that. As Kiss loads the necessary files from your application to handle each request, it caches them in memory to have them instantly ready for future requests, making the application even faster.

However, some shared web hosting environments will not allow you to run a persistent Kiss application server. Fortunately, Kiss can also be run via CGI. If your host supports CGI scripts and has Ruby installed, just install the necessary gems in your user directory and tell your CGI script where to look for them. More details on using Kiss with CGI will be coming in a future installment to this documentation.

Kiss is designed to load and initialize quickly, so it can be run from a CGI script with reasonably fast response times.   However, as your traffic load increases, the repeated initialization of the framework for each request may cause excessive CPU usage. You will want to consider the speed benefits available by running your application as a persistent app server, probably at around the same time you consider moving from a shared hosting package to your own dedicated or virtual dedicated server.

More information on choosing and configuring the application running mode can be found in the Config chapter of this documentation.

Main Application Components

The functionality of Kiss applications is separated into three main types of components: actions, templates, and models. To explain the distinct functions of each component type, let's imagine that we're building a social networking application using the Kiss framework.


Action classes contain the business logic for handling the various types of requests that users can make to the application.

For example, in our imaginary social networking application, a user can request to see another user's profile. This request is sent by the user's web browser to our application, where it would then be dispatched by the Kiss framework to an action class that specifically deals with this type of request. The "view user profile" action class would check to make sure the active user was authorized to view the other user's profile, then fetch the user profile data, and prepare the data to be sent back to the user.

Action files are stored in the actions directory of the application. More information on actions can be found in the Actions chapter of this documentation.


Templates describe what the user sees when interacting with your application. After an action finishes execution, the Kiss framework loads a template to generate what will be sent back to the user. In web applications, templates are typically written in HTML, with embedded Ruby commands to insert output data from the action that was just called.

In our example social networking application, we would want a user profile template to go along with the "view user profile" action. We would design an HTML web page to display the user's profile data, photo, friends, and other information. We'd probably add some links as well,  to browse more photos, send an email message to the user, or leave a comment on the user's profile page. And we'd give this template file a similar name to its corresponding action file, to make it clear that they go together.

Because templates are often closely related to actions, template files are stored alongside action files in the actions directory of the application. However, if you wish to keep them in a separate location, to restrict which members of your team can modify actions or templates, you can create a templates directory and configure Kiss to look for your template files there.

More information on templates can be found in the Templates chapter of this documentation.


Model classes contain business logic specific to handling the various types of data managed by the application. Our social networking application deals with users, email messages, photos, comments, and other types of data. Usually each type of data is stored in a separate table of our application's database, which could be accessed by a model class. Kiss can automatically create a model class for any table in your application's database, allowing you to create, read, update, and destroy data in the table. You can specify relationships between models, allowing you to easily fetch related data from other models. For example, you can specify in the users model class that a user may have many photos, which automatically creates a method that you can fetch records of a user's photos from the database. You can also define custom methods to perform more complicated business logic.

Model classes greatly simplify database access, and they also serve as convenient places to store data-specific business logic that will be used by multiple actions to handle multiple types of requests.

Model files are stored in the models directory of the application. More information on models can be found in the DB Models chapter of this documentation.

Other Application Directories

These directories are listed here as a quick reference to what else you'll find inside Kiss applications, but you don't need to worry about them much yet.

Adding Actions to Your Application

If you're ready to do more interesting things with your new Kiss application, head on over to the next chapter, all about Actions.

For the Design Pattern Purists

How is Kiss an MVC Framework?

Many web frameworks claim to be based on the Model-View-Controller (MVC) design pattern. Unfortunately, there is not a clear consensus of what exactly MVC means when used for web applications. Loosely, MVC has come to imply some separation between business logic (the "Model") and user interface (the "View"), with the flow of data between those two sides dispatched by a "Controller." Beyond that, the definitions get fuzzy, as each framework has its own ideas regarding the boundaries between Model, View, and Controller.

In Kiss, we might try to apply the MVC pattern as follows. The Kiss framework itself is the Controller, receiving requests from the user and dispatching them to action and template code. Kiss templates make up the View, the interface that user sees and navigates. Kiss database models contain business logic, which belongs in the Model. But where do actions fit in? Sometimes, actions perform validation of user input, which some people argue is a function of the View. Sometimes, actions manipulate data directly and perform other business logic, which are functions of the Model. It's not entirely clear where Kiss actions belong in the MVC pattern.

We admit that MVC might not be the right description of what we're doing in Kiss. Yet we don't think MVC is a very good fit for what happens in Rails or Merb either. Django also freely admits that it's not really an MVC framework. Really, it's not very clear how MVC in its pure definition applies to any web application, where the View is split between generation by the application code on the server side and display by the web browser on the client side, and the communication between Model, View, and Controller is forced into a bidirectional flow of requests up and responses down. Maybe none of the web frameworks are truly MVC.

However, since MVC has become a generic buzzword for separation of business logic from user interface, feel free to call Kiss an MVC framework if you want. We certainly won't mind.

If You Want to Be More Precise, Call It MVP

There's another design pattern related to MVC, called Model-View-Presenter (MVP). Like the MVC pattern, MVP separates the functions of the application, but in a slightly different way, which happens to be more similar to Kiss.

We still say that the Kiss framework serves as the controller, coordinating the functions of the above MVP components.

Say What?

If none of this talk about MVC and MVP makes any sense, don't worry. It's not really all that important, unless you like debating fine definitions of computer science with your friends. Let's move on to some more practical material in the next chapter, Actions.