RocketSled Tutorial 2: RocketSled Markup Language (RSML)

Author: David Grinton thegrinch@workingsoftware.com.au

Table of Contents

• Introduction
• The SugaryPastry class
• Modifying the Home class
• An RSML loop
• Nesting RSML loops
• Accessing non-arrays in RSML

Introduction

Welcome to RocketSled Tutorial 2.

In this tutorial we will extend the simple site built in RocketSled Tutorial 1 to use some basic RocketSled Markup Language (RSML) to display data stored in some new classes.

The SugaryPastry class

Create a class SugaryPastry in WEBROOT/yourdir/packages/my/sugary_pastry.class.php and add the following code:

<?php
   class SugaryPastry extends RsmlObject
   {
      private $name;
 
      public function SugaryPastry($name)
      {
         parent::RsmlObject();
         $this->name = $name;
      }
 
      public function name()
      {
         return $this->name;
      }
   }
?>

Modifying the Home class

Now edit the display() method in WEBROOT/yourdir/packages/my/home.class.php as follows:

public function display()
{
   $disp = Display::current();
   $disp->setValue('pastries',$this->pastries());
   $disp->addView('page_content','my.Home');
   $disp->displaySiteTemplate();
}

... and add a method pastries() to generate some data:

private function pastries()
{
   $ret = array(new SugaryPastry('chocolate croissant'),
                new SugaryPastry('baclava'),
                new SugaryPastry('apple turnover'));
   return $ret;
}

An RSML loop

Finally edit WEBROOT/yourdir/packages/my/home.rsml.php to add the <pattern> section as follows:

<fragment>
   <h2>Home</h2>
   <p>welcome home</p>

   <pattern data="pastries">
      <ul>
         <loop>
            <li>
               <local data="name"/>
            </li>
         </loop>
      </ul>
   </pattern>
</fragment>

In the above RSML, the <pattern> tag indicates that we wish to use data from the "pastries" value that we set in the Home class with the line:

 $disp->setValue('pastries',$this->pastries()); 

The <loop> tag will iterate over the contents of the "pastries" value (which must be an array).

The <local> tag calls the name() method (as specified in data="name") of the items in the "pastries" array and prints the returned value.

If you now view WEBROOT/yourdir/index.php?h=Home you should see a list of pastries as defined in the pastries() method.

Nesting RSML loops

The <pattern> tag may be nested within itself. If we add another member to the SugaryPastry class as follows:

<?php
   class SugaryPastry extends RsmlObject
   {
      private $name;
      private $ingredients;
 
      public function SugaryPastry($name,$ingredients = array())
      {
         parent::RsmlObject();
         $this->name = $name;
         $this->ingredients = $ingredients;
      }
 
      public function name()
      {
         return $this->name;
      }
 
      public function ingredients()
      {
         return $this->ingredients;
      }
   }
?>

... add a class Ingredient in WEBROOT/yourdir/packages/my/ingredient.class.php:

<?php
   class Ingredient extends RsmlObject
   {
      private $name;
 
      public function Ingredient($name)
      {
         parent::RsmlObject();
         $this->name = $name;
      }
 
      public function name()
      {
         return $this->name;
      }
   }
?>

... and correspondingly update the pastries() method of the Home class as follows:

private function pastries()
{
   $ret = array(new SugaryPastry('croissant',
               array(new Ingredient('flour'),
                     new Ingredient('sugar'),
                     new Ingredient('butter'))),
                new SugaryPastry('baclava',
               array(new Ingredient('flour'),
                     new Ingredient('sugar'),
                     new Ingredient('walnuts'))),
                new SugaryPastry('apple turnover',
               array(new Ingredient('flour'),
                     new Ingredient('sugar'),
                     new Ingredient('apple'))));
   return $ret;
}

... we can then add another loop in WEBROOT/yourdir/packages/my/home.rsml.php to access the second level of the pastries array:

<fragment>
   <h2>Home</h2>
   <p>welcome home</p>

   <pattern data="pastries">
      <ul>
         <loop>
            <li>
            <local data="name"/>
            <pattern data="ingredients">
               <ul>
                  <loop>
                     <li>
                        <local data="name"/>
                     </li>
                  </loop>
               </ul>
            </pattern>
            </li>
         </loop>
      </ul>
   </pattern>
</fragment>

Accessing non-arrays in RSML

Another way to reference data in RSML is with the <out> tag. Suppose we edit the display() method of the Home class, setting another value with the line:

 $disp->setValue('favourite',new SugaryPastry('pecan pie')); 

We can now reference the 'favourite' value with (add this just before the first <pattern> tag in home.rsml.php):

 <out data="favourite[name]"/> 

The above line will call the "name" method of the "favourite" value (which must not be an array) and print the returned value.

To summarise, <local> must be used within a <pattern> tag and refers to the members of an array specified by that tag, the <out> tag may be used anywhere and must refer to a value that is not an array.

View WEBROOT/yourdir/index.php?h=Home to see what we've done so far.