6. Adding friends

A database with a list of friends isn't that useful if new friends can't be added to it, is it? Now that the database framework is there, we can extend our application with an element, a template and the backing database code for adding friends.

6.1. Declaring the new element

The ADD element is pretty simple, it has no exits other than the global menu and no datalinks. The only thing we haven't talked about before is the use of a submission bean. Let's take a look at the site file and the element file, and then explain how submission beans work:

Example 7.8. Updating the site file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE site SYSTEM "/dtd/site.dtd">
  <arrival destid="DISPLAY"/>
  <globalexit name="menu" destid="MENU"/>
  <element id="DISPLAY" file="display.xml" url="/display"/>
  <element id="MENU" file="menu.xml" url="/menu">

    <!-- Add a flowlink to the new add element -->
    <flowlink srcexit="add" destid="ADD"/>

    <flowlink srcexit="display" destid="DISPLAY"/>
  <!-- Add the new element -->    
  <element id="ADD" file="add.xml" url="/add"/>

The comments in the site file points out the changes: a new flowlink from the menu to the add element, and a declaration of the new element itself.

Example 7.9. Element for adding a friend

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE element SYSTEM "/dtd/element.dtd">
<element implementation="tutorial.friends.Add">
  <submission name="friend_data">
    <bean classname="tutorial.friends.backend.Friend"/>

6.2. Submission beans

A submission bean is, like many of RIFE's features, an abstraction of a common web application task, more specifically handling the input from a form.

Submission beans are set up similarly to regular submission parameters, except that instead of listing one or more parameters, a bean is used, as seen in Example 7.9, “Element for adding a friend” above.

classname points to the class of the bean, in this case our representation of a friend. After setting up the bean like this, getSubmissionBean can be used to get a bean with its properties set to the values entered by the user in the submission form:

Friend friend = (Friend)getSubmissionBean("friend_data", Friend.class);      

This way, fewer lines of code are needed and there are less places to change if properties are added to or removed from our friend representation, compared to using submission parameters.

6.3. The add template

Finally, we only have the template left to write, which is more or less similar to the submission template for the numberguess game in Chapter 3, Creating a more advanced RIFE application.

Example 7.10. Template for adding a friend


  <head><title>Add a new friend to the database</title></head>
    <h3>Add a friend</h3>

    <!--V 'content'/-->
    <!--BV 'content'-->
      <form name="friend_data" action="[!V 'SUBMISSION:FORM:friend_data'/]"
        <!--V 'SUBMISSION:PARAMS:friend_data'/-->
        <input type="text" name="firstname" length="51" maxlength="50"/><br/>
        <input type="text" name="lastname" length="51" maxlength="50"/><br/>
        <textarea name="description" cols="80" rows="6"></textarea><br/>
        <input type="text" name="url" length="80" maxlength="255"/><br/>
        <input type="submit" name="Add this friend."/>
    <!--B 'content_added'-->
      <p>The friend has been added.</p>
    <p><a href="[!V 'EXIT:QUERY:menu'/]">back to menu</a></p>

Just like when using submission parameters, the values SUBMISSION:FORM: and SUBMISSION:PARAMS: are used to handle the submission bean.

6.4. Adding a friend to the database

Building and executing the insert query becomes particularly easy when we have all the data in a bean:

Example 7.11. Adding a friend to the database

public void add(Friend friend)
throws DatabaseException
  Insert insert = new Insert(getDatasource());
  DbPreparedStatement insert_stmt = getPreparedStatement(insert);