Getting Started

These tutorials assume that you are starting with a copy of the app-blank directory and that you can see the default page. Please replace http://yoururl with the URL for your site.

Basic PHP/HTML

First we will add just basic web pages. The blank application is setup so that any file put on the root construct will show up. For example, create a new file call test.php in the constructs/root directory containing:
<h1>now in test.php</h1>  

If you now load http://yoururl/root/test you will see the contents of the test.php file. You can also access HTML files in the same way. This simple method of accessing code and HTML files. Note that there is no security built into this type of action.
If you need learn more about this type of construct action review the Ox_FlatAction and Routing.

Assemblers

Most modern web pages need more complex behaviors that are related together. For example you may want to build a user management screen. This might consist of an index that lists the users, then you would need to add a way to add, edit, and delete users as well. This functionally is all related and can be put into a single construct.
Ox has an assembler action that allows you to organize your code together and structure that enforces role based security. In this example we will create a very basic user manager. We will be assuming that users are stored in a MongoDB collection called "users".
To get start start a new construct, create a new directory in constructs called UserManager. Then create a new file in that directory call assembler.php. It is setup this way so you can easily pick out the code that does the assembly work versus the template files that we will be creating as well.
asembler.php

<?php

class UserManager extends Ox_AssemblerConstruct
{
    public function 
__construct()
    {
      
$this->roles = array(
            
'index'=> array('anonymous'),
            
'edit'=> array('anonymous'),
            
'save'=> array('anonymous'),
            
'remove'=> array('admin'),
        );
    }

    public function 
index()
    {
        print 
'In index';
    }

    public function 
edit()
    {
        print 
'In edit';
    }

    public function 
save()
    {
        print 
'In save';
    }

    public function 
remove()
    {
        print 
'In remove';
    }
}

To set the code you can use following URLs: http://yoururl/UserManager/ and that will run the index function. http://yoururl/UserManager/index and that will run the index function. http://yoururl/UserManager/edit/ and that will run the edit function. http://yoururl/UserManager/save/ and that will run the save function. http://yoururl/UserManager/remove/ and that will run the remove function.
Note the assignment in the constructor (__construct function). This section tells the system which roles can access the method. The system has built in two roles: "su", and "anonymous". The "su" role has access to ALL part of the system, no mater what you set the role list to. The "anonymous" role is the default that any person coming to your site is setup as (no authentication required). You can have any roles that you want and you can refer to the Security system for more detail.
So you can send direct output in the functions, but it is best to use a template files. For example what we really want on the index page is a list of users that are already in the system. First lets change the index function:

public function index()

    {
        //get users from the database
        $users = $this->db->users->find();
        //create a variable for the template to use.
        $this->set('users',$users);
    }

This gets all of the user docs from MongoDB (really just a cursor) and passes that to the template. Now to create the template, create a file called index.php in this construct directory.
<ul>

    <?php foreach ($users as $user): ?>

        <li><a href="/UserManager/edit?id=<?php echo $user['_id'];?>"><?php echo $user['username'];?></li>

    <?php endforeach; ?>

</ul>

<a href="/UserManager/edit">Add a new user</a>


Now when we call http://yoururl/UserManager/ we will get a list of user in the database plus a add new user link. The AssemblerAction will automatically load a template file with the same name as the method called if it exists. You can override which template will be loaded by manually setting the $this->template property.
Notice in the hrefs that edit does not end with "php". For this action that is the method name.
Next you can create the edit part by changing the edit function:

public function edit()

    {
        $user = array();
        if (isset($_GET['id'])) {
            //fetch a single doc from MongoDB as an array
            $user = $this->db->users->findOne(array('_id'=>new MongoId($_GET['id'])));
        }
        $this->set('user',$user);
    }

In this example we are using edit for both creating a new user and editing a current user. If we have an id, then it is an edit.
For the template we would have:
<form method="post" action="/UserManager/save">

    <label>User Name:</label>

    <input type="text" name="user[username]" value="<?php echo $user['username']?>"/><br/>

    <label>Password:</label>

    <input type="text" name="user[password]" value="<?php echo $user['password']?>"/><br/>



    <input type="hidden" name="user[_id]" value="<?php echo $user['_id']?>"/><br/>

    <input type="submit" value="Submit"/>

</form>


This sets up a simple form to get the information from the user. When the form is submitted, the data will be processed by the save function. There is a trick in the name attribute which will pass the values back in PHP as an array user on the _POST variable. Normally the password entry would be of type password and you would setup a way to check to make sure it is correct.
For the last step we need to finish the save function:

public function save()

    {
        //See if we where passed an id.
        if (empty($_POST['user']['_id'])) {
            //unset so MongoDB will create a new record.
            unset($_POST['user']['_id']);
        } else {
            //we have an id, but we need to convert it to a MongoId
            $_POST['user']['_id'] = new MongoId($_POST['user']['_id']);
        }

        //If you are saving a password in you need to use the hashAndSaltString provided by the security object.
        //Get the security object by using the Ox_LibraryLoader
        $_POST['user']['password']= Ox_LibraryLoader::Security()->hashAndSaltString($_POST['user']['password']);

        //Upsert the data to mongo.
        $this->db->users->update(
            array('_id' => $_POST['user']['_id']),
            $_POST['user'],
            array('upsert'=>true)
        );

        //return the user to the index screen.
        Ox_Router::redirect('/UserManager');
    }

You should now have a very simple running construct.