What Is An Element?

• Elements are the smallest logical building blocks in a web application.
• They are only responsible for the execution of their business logic.
• The execution flow and data flow is orchestrated by the engine.
• Elements are linked together through a site-structure to make this possible.

Defining An Element

Implementation

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE element SYSTEM "/dtd/element.dtd">

<element id="Version" implementation="com.uwyn.rife.jumpstart.elements.Version"/>

So this really is an extremely simple element. It hasn't got any connections to the outside world, so what does it do? Well, we can put it somewhere in our site structure and if it is accessed the implementation will be called. It's as simple as that. Most elements you define will require an implementation, although sometimes you get around it by extending another element. The interesting part is what your implementation does and that is something that we'll discuss in the section about [Element Implementation].

Submissions

Defined By Parameters

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE element SYSTEM "/dtd/element.dtd">

<element implementation="tutorial.numberguess.Guess">
  <input name="gameid"/>

  <submission name="performGuess">
    <param name="guess">
      <default>-1</default>
    </param>
  </submission>

  <exit name="start"/>
  <exit name="success"/>

  <output name="gameid"/>
</element>

So the excerpt above is taken from the infamous number guess example and what we're interested here is the <submission>-tag and it's contents. Basically what is defined here is a submission called "performGuess" (this id is mainly used in the implementation) which has a parameter called "guess". Also, "guess" has a default value of -1. What we could do now is add more parameters and that's basically all there is to it.

Defined By A Submission Bean

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE element SYSTEM "/dtd/element.dtd">

<element implementation="com.yourcompany.rife.elements.Signup">
	<submission name="validateCredentials">
		<bean classname="com.yourcompany.rife.model.UserForm"/>
	</submission>
</element>

So, instead of listing our parameters one by one, we instead refer to a so-called Submission Bean, that can be a POJO class. The syntax is pretty much self explanatory, to learn how to implement a submission bean, please check our chapter on [Bean Implementation].

Connectability

The basic idea of a component framework is that it's components do not have to worry about their surroundings. That's why we define what inputs our element needs and what outputs it provides and think about wiring it all up later. This may seem like a little tedious at first, but once you get the hang of it, it'll only take you seconds to write those element definitions. And it really pays off on larger projects to have a huge library of reusable, configurable elements that you can just pull out of your pocket at any time.

So here's an example of an element, taken from the Number Guess Tutorial, which you might want to check out if you don't really get that concept of flowlinks and datalinks yet.

<element implementation="tutorial.numberguess.Guess">
  <input name="gameid"/>

  <submission name="performGuess">
    <param name="guess">
      <default>-1</default>
    </param>
  </submission>

  <exit name="start"/>
  <exit name="success"/>

  <output name="gameid"/>
</element>

Well, at this point you may wonder: "If there are inputs, outputs and exits... where are the entries?" Basically, each element has one entry which is implicit. So, we just move on right to the ...

Inputs

Ok, sometimes your elements need some data to work with. This data may come from cookies, the database, it may fall from the sky, but most of the time it will come from another element that ran previously. In this case you will need an input that you can - in the Site Structure - connect to that element's corresponding output. It's that simple. Then in your [Element Implementation] you can just get the value from this input and work with it. If the other element changes, no problem, all you have to do is update you site structure. Very neat.

The definition of an input is very straightforward, so I really don't know what to explain about it. You give it a name, which is used to reference it both in the Site Structure and the [Element Implementation]. That's it.

Outputs

When your element is done processing the data it may put it in a template to show it to the user or maybe write it to the database. In some cases however there is still work to do. So you define an output just as you defined those inputs. Of course there can also be multiple inputs and outputs. Afterwards, wire them up in your Site Structure.

Exits

Again, this is a layer of abstraction that is used so that elements can work regardless of their environment. Instead of naming the element you want to link to, you link to an exit and - in the Site Structure - wire it to that element. That way, if you use the same element in another context, you can just wire the exit to a different element. Oh boy, it can be so simple.

Extending Other Elements

Instead of writing a new element from scratch, sometimes it's easier to extend one of your existing elements. Just like extending your classes, extending your elements makes your site more flexible and a lot easier to maintain.

Let's look at an example.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE element SYSTEM "/dtd/element.dtd">

<element extends="rife/authenticated/memory.xml">
  <property name="template_name">auth.form</property>
  <property name="role">admin</property>

  <submission name="credentials">
    <param name="login"/>
    <param name="password"/>
  </submission>

  <childtrigger name="authid"/>
</element>

This example is taken from the Guide about RIFE's Authentication facilities, so you might wanna check that out aswell.

Now, what do we have here? Our parent element is rife/authenticated/memory.xml which - as the name suggests - is responsible for the login when we're using RIFE memory authentication scheme. (That is, the valid credentials are stored in XML instead of a database.)

So let's take a look of what is actually added to the orginal element. First, there are two properties. So instead of putting those into the Site Structure, we just give them a value right here. Obviously our new element doesn't need this amount of flexibility anymore.

Next, we add a submission to the element. Nothing special.

Finally, we add a childtrigger and again, there's nothing different than when you normally define a childtrigger. (Although these are most common in the context of authentication right now.)

Childtriggers

todo: explain this here