Meet Sitellite's successor: Elefant CMS

A modern PHP framework and content management system based on the improved features of PHP 5.3+. Elefant is an extremely fast and easy to use CMS that inherits all the best of Sitellite, without the fat. Learn more »

---

boxes
conf
data
docs
forms
html
install
lang
lib
pix

<?php

echo 'Hello ' . $_GET['name'];

?>

sitellite_access = public
sitellite_status = approved
sitellite_action = on

<p>Hello {name}</p>

<?php

echo template_simple ('helloworld.spt', $_GET);

?>

boxes
    helloworld
        access.php
        index.php
conf
data
docs
forms
html
    helloworld.spt
install
lang
lib
pix

<?php

// get the names list from the session data
$names = session_get ('names');

// if there's no list yet, create a blank one
if (! is_array ($names)) {
    $names = array ();
}

// add the new name and save it to the session data
$names[] = $_GET['name'];
session_set ('names', $names);

// now we'll create a data array to pass to the template,
// since we're passing it the $names list as well as the
// current name
$data = array (
    'name' => $_GET['name'],
    'list' => $names,
);

// call the template and pass it $data this time
echo template_simple ('helloworld.spt', $data);

?>

<p>Hello {name}</p>

<p>I've said hello to:</p>

<ul>
{loop obj[list]}
    <li>{loop/_value}</li>
{end loop}
</ul>

<?php

// get the names list from the session data
$names = session_get ('names');

// if there's no list yet, create a blank one
if (! is_array ($names)) {
    $names = array ();
}

// add the new name and save it to the session data
$names[] = $_GET['name'];
session_set ('names', $names);

// now we'll create a data array to pass to the template,
// since we're passing it the $names list as well as the
// current name
$data = array (
    'name' => $_GET['name'],
    'list' => $names,
);

// set the page title
page_title ('Hello World Examples');

// call the template and pass it $data this time
echo template_simple ('helloworld.spt', $data);

?>

The MailForm library

Sitellite's form handling is provided by the MailForm libraries in SAF. MailForm handles generating forms based on simple INI-formatted files that define the form "widgets" (MailForm's name for fields) and a PHP script that does the handling.

MailForm has several built-in features for preventing spambot abuse, and also takes care of the input validation and translation issues automatically, including many built-in validation rules as well as the ability to create custom validation rules as PHP functions.

A simple contact form

[Form]

message = Please use this form to contact us.

[name]

type = text
alt = Your Name

[email]

type = text
alt = Email Address
rule 1 = "not empty, You must enter your email address."
rule 2 = "email, Your email address does not appear to be valid."

[message]

type = textarea
alt = Comments/Questions
labelPosition = left

[submit_button]

type = submit
setValues = Send

You'll also want to copy the 'access.php' file from the 'helloworld' box into your 'contact' folder as well. Forms need the same access settings as boxes.

Breaking down the above file, you'll see that it's divided into blocks using the square braces to denote block names.  It always starts with the [Form] block, which defines properties of the form itself, followed by subsequent blocks, each of which represents a single form field or widget.

Types 

Each widget must be given a type.  The types correspond to the list of available widgets in the Sitellite API references, and you can also make custom types and refer to them in individual apps.  For example, Sitellite's built-in WYSIWYG editor, called "xed" exposes a widget which can be called like this:

type = xed.Widget.Xeditor

This tells Sitellite to look in the 'xed' app's libraries for a Widget/Xeditor.php file where it should find a widget of the type 'xeditor'.  MailForm handles all the class loading behind-the-scenes, so you never have to worry about that in your form code.

Alt 

The alt setting defines the text to be displayed next to the field itself.  If not set, this will default to the widget name capitalized.  For example "widget_name" would become "Widget Name" if no alt setting is specified.

Rules

You can also see in the email field that two rules are defined for it.  The first tells MailForm that the field can't be empty, and the second puts it through some tests to try to make sure it's a valid email address.

You can have as many rules for each widget, and we'll look at some more of the rule types a bit later.  For now, it's enough to know that they take the form "rule # = rule, Error message."

<label for="name">Your Name</label>
<input type="text" name="name" />

The index.php file

<?php

class MyappContactForm extends MailForm {
    function MyappContactForm () {
        parent::MailForm (__FILE__);
    }

    function onSubmit ($vals) {
        // let's output the form data to the user
        echo 'You entered:<br /><br />';

        foreach ($vals as $key => $value) {
            echo $key . ' = ' . $value . '<br />';
        }
    }
}

?>

Sitellite knows to automatically import the MailForm library when a form is called, so you don't have to explicitly import it yourself.  In a box, you would need to first say:

loader_import ('saf.MailForm');

So the first thing to do is define a new class for our form.  Form classes are also automatically instantiated and called by Sitellite, but this means you need to name your form classes in a way that Sitellite expects.   The format of a class name is as follows:

• App name (e.g., Myapp if your app folder is named 'myapp') with the first letter capitalized.
• Folder name (e.g., Contact if your form is in 'forms/contact') also with the first letter capitalized.  Please note that if your form is in a sub-folder such as 'forms/contact/techsupport' you would name it MyappContactTechsupportForm, specifying each sub-folder in turn.
• The word 'Form'.

You class extends the MailForm class so that it can inherit all the functionality it needs to draw your form.

Next, you need to create a constructor method, which is a function named the same thing as your class name.  In more complex forms, you might put some additional processing here, but for now all this needs to call is:

parent::MailForm (__FILE__);

This tells MailForm where your class is, so it can find and parse your settings.php file for you automatically.

The last thing your class needs is an onSubmit() method, which will be given an associative array of the form data and does something with the results.  In this case, it simply displays them back for the visitor. 

Viewing the results

You're now ready to view the form you just created.  To load the form from your browser, go to:

http://www.example.com/myapp-contact-form

You should see your form appear there (changing 'www.example.com' to your own site address).  Feel free to try it out and see the results. 

Exercise: Modify the onSubmit() form handler to send you an email using PHP's mail() function when the form is submitted. You can upload your finished changes here.

A closer look at validation rules

Let's take a closer look at the input validation capabilities of MailForm.  As we saw before, validation rules take the following format:

rule # = "rule, Error message."

The rule itself has its own format as well, and there are many different types of rules you can use out-of-the-box.  These are:

• is 'some value' – The value must be equal to 'some value'
• contains 'some value' – The value entered must contain 'some value'
• regex 'pattern' – The value must match the regular expression defined in the 'pattern'
• equals 'fieldname' – The value must match the value from another form field, useful for verifying email addresses and passwords.
• empty – The field must be empty.  This is more often used with the prefix 'not' so you can verify that the field is 'not empty'.
• length 'value' – The value must be the specified length.  Some valid length examples are: 6, 6+, 6-12, 12- meaning 6 exactly, 6 or more, between 6 and 12, and 12 or less.
• gt 'value' – The value must be greater than 'value'
• ge 'value' –  The value must be greater than or equal to 'value'
• lt 'value' – The value must be less than 'value'
• le 'value' – The value must be less than or equal to 'value'
• func 'function_name' – The value must return true when passed to the specified function.  This enables you to easily define custom validation rules.
• unique 'table/column' – The value must not already exist in the specified database table in the specified column.  Useful for ensuring usernames are unique, for example, or that an email address isn't used to register for multiple accounts.
• exists 'path/to/directory' – The value must not exist as a file name in the specified folder.  This is useful for file uploads to ensure they don't overwrite an existing file.
• numeric – The value must be numeric, no letters.
• email – The value must be a valid email address.
• header – The value must validate for use in an HTTP header.  Useful for securing against header injection attacks.

You can also specify 'not' in front of any rule to change the rule to its opposite.  For example:

rule 1 = not empty, This field cannot be empty.

rule 2 = not numeric, This field must contain letters AND numbers.

rule 3 = "not equals 'other_field', This field must not be the same as other_field."

Custom validation rules

<?php

function myapp_rule_username_lowercase ($vals) {
    if ($vals['username'] != strtolower ($vals['username'])) {
        // the username must be lower case
        return false;
    }
    // the username is correct
    return true;
}

?>

To call this function as a rule, you would say:

rule 1 = "func 'myapp_rule_username_lowercase', Your chosen username must be lowercase."

Not necessarily the most useful example, but you could easily extend this for credit card format validation, ensuring dates are correct (ie. they didn't enter 1492/25/64), and so on.

Exercise: Add a custom validation rule to your form and call it via your settings.php file.