docs.roxen.com
main | demo | docs
download | community | pike
2000 Roxen Internet Software
Suggestions, Comments or Complaints
manuals@roxen.com

DocsRoxen2.0RXML TutorialIf tags


  • The basics of if-else
  • If tags syntax
  • If plugins
  • A basic example
  • <if> and <define>
  • <if supports>
  • Summary
  • Combining <if> and <define>

    This Section will show how to combine <if> and <define> to dynamically show contents of a web page.

    After reading this Section you will have knowledge of how to combine <if> and <define> when creating a web page. You will also know how to use <define> to define your own RXML macro.

    We will create a web page with a HTML form requesting the name and e-mail address of a user. On submit we will check if all fields are set and if the e-mail address is valid. The page will show a response depending on the test results.

    The <define> tag

    A very useful tag is the Variable tag <define>. It is used for creating your own macros such as tags, containers or If-callers. The most common use is to define an "alias" for a portion of code that will be inserted several times on a web page. We will not discuss <define> in depth here. See the Web Site Creator Manual for details.

    Let's create a tag that will work as a sum of some other tags.


    <define tag="multi-set">
      <set variable="var.foo" value="one" />
      <set variable="var.bar" value="two" />
      <set variable="var.gazonk" value="three" />
    </define>
    
    <pre>var.foo is "&var.foo;"
    var.bar is "&var.bar;"
    var.gazonk is "&var.gazonk;"
    </pre>
    
    <multi-set />
    
    <pre>var.foo is "&var.foo;"
    var.bar is "&var.bar;"
    var.gazonk is "&var.gazonk;"
    </pre>
    
    var.foo is ""
    var.bar is ""
    var.gazonk is ""
    
    var.foo is "one"
    var.bar is "two"
    var.gazonk is "three"
    

    Here <multi-set> is used to insert the three <set> tags. If we were to do this set operation in multiple places the value of <define> is quite obvious. We can also add values via attributes to our defined tag.


    <define tag="hello">
      Hello there, &_.name; !
    </define>
    
    <hello name="John Doe" />
    
    Hello there, John Doe !

    The attribute values are catched with entities and using the "_" scope, representing the current scope. Here the value of the name attribute is represented by the entity &_.name;. If we want to set default values to attributes (used when the attribute is left out) we use the container <attrib>.


    <define tag="hello">
      <attrib name="name">Mr Smith</attrib>
      Hello there, &_.name; !
    </define>
    
    <hello /><br />
    <hello name="John Doe" />
    
    Hello there, Mr Smith !
    Hello there, John Doe !

    An interesting feature is to define a macro for an If plugin or combinations of If plugins. You simply create an alias that can be used together with <if>.


    <define if="js">
      <if supports="javascript" and=""
          clientvar="javascript = 1.2" />    
    </define>
    
    <if js="js" />
    <then>
      Your browser supports javascript ver 1.2
    </then>
    <else>
      Your browser doesn't support javascript ver 1.2
    </else>
    
    Your browser doesn't support javascript ver 1.2

    Here <if js="js"> is replaced by <if supports="javascript" and="" clientvar="javascript = 1.2"> before the page is sent to the browser.

    Well, that is how far we go into <define> here. In the example part below we will use the <define tag> feature to insert a HTML form with dynamic content.

    Verifying an e-mail address

    We are going to create a simple e-mail address checker only using HTML and RXML. The first time the page is loaded a form is presented to the user for input of name and e-mail address. A submit sends the input and when the page is loaded again, we will first check that both name and e-mail address were added, and if so, check if the e-mail address matches the form "*@*.*". If any of the tests fail, an error message will be displayed together with the form for new input. Correct input will not be deleted. If all goes well, a nice welcome awaits the user.

    The source code is found by following the link. (It might be a good idea to open the source code file in a different window, so that it is easily read parallel to this Section. The code won't be displayed here to shorten the length of this Section.)

    First we define a RXML macro called mail-form that inserts a form. Four attributes are used: nameval, mailval, status and mess. We use <attrib> to set default values for nameval and mailval to the data entered in the field. This will save entered data so that the user won't have to retype it. The form will display a status message, an ordinary message and a form with two input fields and a submit button.


    <!-- DEFINING FORM TAG -->
    <define tag="mail-form">
      <attrib name="nameval">&form.name_;</attrib>
      <attrib name="mailval">&form.mail_;</attrib>
    
      <p><b>&_.status;</b><br />&_.mess;</p>
    
      <form method="POST">
        <table>
          <tr><td>Name:</td>
          <td><input type="input" size="30" name="name_"
                     value="&_.nameval;" /></td></tr>
          <tr><td>E-mail:</td>
          <td><input type="input" size="30" name="mail_"
                     value="&_.mailval;" /></td></tr>
          <tr><td><input type="submit" name="button"
                     value="OK" /></td></tr>
        </table>
      </form>
    </define>
    


    The start form

    To display the page dynamically we use <if> and <else>. The first test checks if the page is loaded for the first time or if the user pushed a submit button to get there. Only if the user clicked the "OK" button, &form.button; will represent "OK". The next test checks if both fields contain data. If so, var.ok will have the value 1. The last test checks if the e-mail address match the form "*@*.*". This test is really not sufficient in real life, since an address like "foo@foo@mail.gazonk" would be correct. Remember that anything goes with '*'. It is left for you to figure out a nice algorithm for a better check. Remember, practice makes the master.


    <if match="&form.button; = OK"><!-- OK clicked -->
      ...
      <if variable="var.ok = 1"><!-- Both not empty -->
        <if variable="var.mail_ = *@*.*"><!-- Success -->
          ...
        </if>
        <else><!-- Mail not on proper format -->
          ...
        </else>
      </if>
      <else><!-- name or e-mail empty -->
        ...
      </else>
    </if>
    <else><!-- First time or Again clicked -->
      ...
    </else> 
    

    The first time the page is loaded or if the user clicked the "Again" button we use our defined macro to display the start form.


    <else><!-- First time or Again clicked -->
      <mail-form status="" mess="Please state your name and
       e-mail address." />
    </else>
    

    When we are sure that the user clicked the "OK" button, we test the data entered. We use <set> to catch the data from the two input fields and then test if any of them where empty, <if variable="var.name_ = ">. If so, we use <append> to set var.ok to 0, which will give a false result in the "Both not emtpy" test. The form will then reappear with a message telling the user to fill in both fields.


    <set variable="var.ok" value="1" />
    <set variable="var.name_" value="&form.name_;" />
    <set variable="var.mail_" value="&form.mail_;" />
         
    <if variable="var.name_ = ">
      <append variable="var.ok" value="0" />
    </if>
    
    <if variable="var.mail_ = ">
      <append variable="var.ok" value="0" />
    </if>
    
    <if variable="var.ok = 1"><!-- Both not empty -->
      ...
    </if>
    <else><!-- name or e-mail empty -->
      <mail-form status="Error" mess="You must fill in both name and
       e-mail address." />
    </else>
    


    If any field is left empty the form reappears with an error messge

    Next we check the e-mail address. We use the Variable plugin although it looks like a typical Match test. This is done to avoid the problem with whitespaces when doing a Match. (See

    RXML run error: Emit dir couldn't find any contents.
     | <emit glob="*" source="dir">
    
    section, Eval part for a discussion on this special case.)


    <if variable="var.mail_ = *@*.*"><!-- Success -->
      ...
    </if>
    <else><!-- Mail not on proper format -->
      <mail-form status="Error" mess="E-mail not on format *@*.*"
       mailval="" />
    </else>
    

    If the test fails the form reappears. Note that the e-mail input filed is cleared by adding mailval="" to <mail-form>.


    This will be displayed if E-mail doesn't match the form "*@*.*"

    Finally, if all tests pass, we display a nice welcome message and add a button that will take the user back to the start form again.


    <if variable="var.mail_ = *@*.*"><!-- Success -->
      <p><b>E-mail address verified</b></p>
      <p>Welcome <b>&form.name_;!</b></p>
      <p>E-mail address &quot;&form.mail_;&quot; is OK.</p>
      <form method="POST">
        <input type="submit" name="button" value="Again" />
      </form>
    </if>
    


    If all goes well we welcome the user and display the input

    Summary

    This Section has taught you how to combine <if> and <define> to dynamically show contents of a web page.

    The <define> tag is used for creating your own macros such as tags, containers or If-callers. The code


    <define if="js">
      <if supports="javascript" and=""
          clientvar="javascript = 1.2" />
    </define>
    

    will create the macro "js" that can be used as an alias for the <if> tag inside the container. You simply use it like this, <if js="js"></if>.

    More details about <if> and <define> is found in the Web Site Creator Manual or by adding <help for="if" /> and/or <help for="define" /> in a web page.

    The next Section,

    RXML run error: Emit dir couldn't find any contents.
     | <emit glob="*" source="dir">
    
    will show the usage of the <if user> plugin and how to show contents in a page based on who is reading it.