As mentioned, RIFE is built on the Java platform which means that you need to install a JDK to develop and run RIFE applications. Java can be downloaded from http://java.sun.com/. You also need a web server with servlet support and for this tutorial we have chosen Jetty, which is easy to setup and use. You can download it from the Jetty web page at http://jetty.mortbay.com/. RIFE itself can be downloaded from the RIFE site at http://rifers.org/downloads. There are a few different packages to choose from. When setting up a new web application, the base package is a good starting point, since it contains the RIFE framework together with the necessary files for getting started with a web application. The directory structure in the zip file is only a recommendation, and you can change it to your liking. However, keeping the web.xml file in the recommended location makes it possible to package this directory as a war file easily and deploy it on any servlet engine. The jar file, on the other hand, contains just RIFE, which is convenient when upgrading RIFE in an existing application. We'll set up a web application directory tree in our home directory, starting with Jetty mkdir ~/tutorial cd ~/tutorial jar xf {download directory}/jetty-{version}.zip Now we need to setup our test application in the webapps subdirectory: cd jetty-{version} cd webapps After that we unpack the RIFE distribution and set up the base directories for the web application: jar xf {download directory}/rife-base-{version}.zip mv rife-base-{version} my-application cd my-application cd WEB-INF mkdir classes cd classes mkdir rep mkdir sites mkdir elements mkdir templates So far so good! It's probably a good idea to copy this whole directory hierarchy so that you can start over from a fresh setup after doing some experimenting, or just to have a boiler-plate application to start new projects from. For example: cd ../../.. cp -r my-application ../../blueprint Now we can start filling in the bits and pieces that are needed to create a very simple RIFE application. But first, we'd like to take the opportunity to explain a bit more about web applications and RIFE. If you look at the contents of the RIFE zip file, you see that it contains the Java classes for RIFE along with a file called web.xml. Applications that are packaged this way can be used directly with any application server, by just dropping the file into the right directory. The only thing missing from the zip file an actual implementation of a web application, which you'll soon be able to write yourself. But first it's time to try out a finished RIFE application, and we'll use an example from the examples package that can be downloaded from the RIFE site. The package contains a number of examples that are ready to run and test. To try out the first example, a simple "Hello World" application, take the following steps: First, go back into the webapps directory and unpack the examples there. cd ~/tutorial jar xf {download directory}/rife-examples-{version}.zip cd rife-examples-{version} Install RIFE into the web application's lib directory. We'll download the jar file from the RIFE site and put it in the right directory: mkdir 01_helloworld/WEB-INF/lib cp ROOT/WEB-INF/lib/rife-{version}.jar 01_helloworld/WEB-INF/lib/ mv 01_helloworld ../jetty-{version}/webapps/ Don't put this jar file in your servlet engine's lib, ext, or other engine-wide library location. Each web application needs to have its own private copy of the RIFE jar. Now we can start the application and test it! cd ~/tutorial/jetty-{version} java -jar start.jar You will see an exception when you start Jetty because the my-application web application is missing required files. We will add those later. The important part now is to look at the hello world example. To try out the example, point your web browser to the location: http://localhost:8080/01_helloworld/home, which should show a "Hello world." message. The following section will walk you through this example and explain the different parts. The center of every RIFE application is the repository. It keeps the different parts of the application together, such as configuration data, site users, data sources, etc. These parts are called participants. The repository is available from anywhere in the application and offers a convenient way to initialize and access application-wide resources. In the simple Hello World example, the repository file is located in ~/tutorial/jetty-{version}/webapps/01_helloworld/WEB-INF/classes/rep/participants.xml. From now on, we will skip the leading directories in the text, so, for example, this file will be referred to as rep/participants.xml. <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE rep SYSTEM "/dtd/rep.dtd"> <rep> <participant param="sites/helloworld.xml">ParticipantSite</participant> </rep> Since this is a very simple example, we only have one participant, which is the site itself. As specified with the param attribute, the site file is found in sites/helloworld.xml. A real life application would most likely contain more participants. A site is made up of elements, which are the smallest logical building blocks in the application. Elements are linked together to form a flow through the web site. You can think of this as electronic components that need to be wired together before they become useful. An electronic component has no use by itself, but when it's combined with others, the most amazing products can be created. It's also possible to use the same components but with different contact points wired together or in a different order. This will cause the functionality to dramatically change without the necessity to pull components apart or build new ones. More even, when your product evolves you might need to include new components in between existing wires. It's not a big task to just remove the existing wire and put the new component in between. The rest of your product continues to function without you being bothered about it. A RIFE element corresponds to the electronic component and the flow corresponds to the wiring. You can take any element from any application and just include it in the flow of another application (rewiring). Each element can have input and output variables. These can be connected and data will be passed around when the links between them are followed. If we take a look at the site structure defined in sites/helloworld.xml, we can see that it contains only one element called HELLOWORLD and that it's mapped to the URL /home. <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE site SYSTEM "/dtd/site.dtd"> <site> <element id="HELLOWORLD" implementation="tutorial.helloworld.HelloWorld" url="home"/> </site> Since our first example only has one element, there are no inputs or outputs, and no links. Therefore, the entire element has been declared in-line. When you want to create reusable elements, you'll probably want to declare them in their own XML file. We'll talk about those features in more detail in the next example. The important thing to notice here is the implementation attribute of the element tag. The implementation of the element can be either a Java class file or a Java source file, which is then compiled on the fly if needed, or a supported Java scripting language, like Jython. Our implementation of the element is a Java class, that just outputs a greeting. It is implemented in HelloWorld.java import com.uwyn.rife.engine.Element; public class HelloWorld extends Element { public void processElement() { Template template = getHtmlTemplate("tutorial.helloworld"); template.setValue("hello", "Hello world."); print(template); } } Element implementations must extend the com.uwyn.rife.engine.Element class and implement the processElement() method. As you can see, this element will use a template and output "Hello world.". We will talk more about templates alter in the tutorial.