Elements

An element is basically a reusable component of your page. Usually this will represent a single page in your website/application.

Let's look at a very simple element:

<element id="About" file="rife/template/print.xml" url="/about">
    <property name="name">pub.about</property>
</element>

This element would be accessible at yoursite.com/about and if accessed, RIFE would simply echo the Template from templates/pub/about and send it to the user.

rife/template/print.xml is an Element Definition file. The directory starts with rife/, which indicates that this element is defined in the RIFE framework itself. It is one of the Stock Elements.

Flowlinks

<element id="Guess" file="guess.xml" url="guess">
    <flowlink srcexit="start" destid="Start"/>
    <datalink srcoutput="gameid" destid="Start" destinput="gameid"/>

    <flowlink srcexit="success" destid="Success"/>
    <datalink srcoutput="gameid" destid="Success" destinput="gameid"/>
  </element>

Flowlinks determine the logic flow of the web application.

[todo: explanation]

Datalinks

<element id="Guess" file="guess.xml" url="guess">
    <flowlink srcexit="start" destid="Start"/>
    <datalink srcoutput="gameid" destid="Start" destinput="gameid"/>

    <flowlink srcexit="success" destid="Success"/>
    <datalink srcoutput="gameid" destid="Success" destinput="gameid"/>
  </element>

Datalinks connect the data inputs and outputs from various elements as defined in their Element Definition.

[todo: explanation]

External vs. Inline Definition

In all the examples above, we did wire the element into our site structure, but the actual element itself was defined in an Element Definition file. We can also define it inline - right here in the site structure. However, please keep in mind that this is usually a bad idea, because this way no other site definition file can reference this element. And no other element can inherit from it.

<element id="AuthAdmin" extends="rife/authenticated/memory.xml">
            <property name="password_encryption">SHA</property>
            <property name="template_name">authentication.admin</property>
            <property name="role">admin</property>
            <property name="authvar_type">cookie</property>
       
            <submission name="credentials">
                <param name="login"/>
                <param name="password"/>
            </submission>
       
            <childtrigger name="authid"/>
        </element>

This excerpt was taken right from a site structure. As you can see, there are a few new tags that we didn't discuss yet. But those are completely identical to the syntax of the Element Definition.

Properties

<element id="Home" file="rife/template/print.xml" url="/home">
		<property name="name">pub.home</property>
	</element>

Properties can be used to make the whole thing much more flexible, because you can write an element once and by giving it different properties, you can change it's behaviour depending on context.

Element IDs

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

The element id is the handle by which the element is referenced throughout the site structure.

Childtriggers

[todo: what are these\?]

Referring to other elements within the site structure

When referring to element ids (i.e. inherits, extends, globalexit, etc.), the following "path" indicators may be used:

Notation	Example	Explanation
none	ELEMENT1	Relative to the current site; "look within the the current site for ELEMENT1"
.	.ADMIN.LIST	Absolute reference from the top level site; "from the toplevel, look for the ADMIN subsite, and then the LIST element (or subsite) within it"
^	^DISPLAY	Relative to the parent site; "go up one level and look for DISPLAY"

Reference: Changing the site structure in the Authentication section of the Live Guide.

Arrival

<arrival destid="Home"/>

This simply defines the element that will be shown when someone enters this site or subsite.

Subsites

<subsite id="Marketing" file="marketing.xml" urlprefix="/marketing"/>

This will another site definition and either merge it with the current one or, if you use the urlprefix like in this example, it will be located below the current site. This way you can build up your sites hierarchy.

Groups

<site>
	<!-- public site -->
	<subsite id="Public" file="pub.xml"/>

	<!-- administration site -->
	<group>
		<globalcookie name="authid"/>
	
		<element id="AuthAdmin" extends="rife/authenticated/memory.xml">
			<property name="password_encryption">SHA</property>
			<property name="template_name">authentication.admin</property>
			<property name="role">admin</property>
			<property name="authvar_type">cookie</property>
		
			<submission name="credentials">
				<param name="login"/>
				<param name="password"/>
			</submission>
		
			<childtrigger name="authid"/>
		</element>
		
		<subsite id="Admin" file="admin.xml" urlprefix="/admin" inherits="AuthAdmin"/>
		
	</group>

	<!-- element that indicates the version of the application -->
	<element id="Version" implementation="com.uwyn.rife.jumpstart.elements.Version"/>
</site>

In the example a group is used to define what part of the site will require authentication.

[todo: I think we need a lot more info here.]

Global Exits

<globalexit name="contact" destid="Contact"/>

This is just a quick way of adding another exit to all elements in a site.

Global Vars

A globalvar is the same as an input, output and datalink for all the elements inside the scope of the globalvar declaration.

<site>
     <group>
         <globalvar name="globalvar1"/>

         <element id="SOURCE" url="/source" file="source.xml">
             <flowlink srcexit="exit1" destid="DESTINATION1"/>
             <flowlink srcexit="exit2" destid="DESTINATION2"/>
         </element>
         <element id="DESTINATION1" url="/destination1" 
file="destination.xml"/>
     </group>
</site>

Is roughly equivalent to:

<site>
     <group>
         <element id="SOURCE" url="/source" file="source.xml">
             <flowlink srcexit="exit1" destid="DESTINATION1"/>
             <flowlink srcexit="exit2" destid="DESTINATION2"/>

             <input name="globalvar1" />
             <output name="globalvar1" />
             <datalink srcoutput="globalvar1" destid="DESTINATION2" destinput="globalvar1"/>
         </element>
         <element id="DESTINATION1" url="/destination1" 
file="destination.xml">
            <input name="globalvar1" />
            <output name="globalvar1" />
            <datalink srcoutput="globalvar1" destid="DESTINATION1" destinput="globalvar1"/>
         </element>
     </group>
</site>

See also: The 06_Inheritance example in the examples (available in Downloads, or in the online subversion code).

Global Cookies

{todo: Will try to explain this later.]