Quick Start Guide

In this quick start guide, we will see how you can use BCE to build a user form

Our playground data model

The first thing you have to know, is that BCE directy relies on your application's ORM system. For now, Mouf's ORM system is TDBM ((see documentatiopn here)[http://mouf-php.com/packages/mouf/database.tdbm/index.md]), but when others will be available, we will do our best to provide multi-ORM support. You will find a detailed description of BCE's architecture in the dedicated chapter Detailed Architecture

Requirement : BCE needs a specific TDBM setting. You must turn the defaultAutoSaveMode to false in the "tdbmService" instance (see TDBM's DAOs section)

Create and configure the form instance

First thing you have to do is creating a BCEForm instance. The BCEForm class represents a form. This is done, as usual, by hiting the "create a new instance" item of the ribbon menu. For example, we create a userForm instance :

Once you've done this, you reach the usual instance interface of Mouf. As explained in the readme, a dedicated interface assists you in creating and configuring your form : press the "configure form" button just under the title of the instance page.

You will reach the configuration screen. Now, as explained above, BCE relies on the ORM system. You will first have to choose the DAO that handles the main entity the form should manage, in our case, we will choose the UserDAO :

Once you choosed your DAO, the default form configuration will load automatically : each column of the user table will be mapped with a field descriptor (please read the Detailed Architecture for more information on field descriptors).

In this exemple, we will leave everything to default.

Simply configure the form's action to submit to the saveUser URL. To do so, click Configuration >> Form Attributes, then modify the "Form Action URL" field

Note : If the data model changes, and you add a column, it will be automatically detected and suggested. If you remove a column, you will have to remove the field descriptor manually

Write a simple controller & view

We will assume, you already now about Splash and its MVC implementation. If not, please refer to Splash documentation to understand what comes next.

Create a controller class (let's say the UserController), that has 2 actions: editUser and saveUser. Add a userFormInstance property of the BCEFormInstance class.

Note: the BCEFormInstance class represents a specific instance (with all the values) of a form, that is itself repsented by the BCEForm class. Each BCEFormInstance instance refers to a particular BCEForm.

    /**
     * @var BCEFormInstance
     */
    public $formInstance;

    /**
     * User edition page.
     * @param string $id the user's id (null for creation)
     * @URL editUser
     */
    public function editUser($id = null) {
        $this->formInstance->load($id);

        $this->content->addFile(ROOT_PATH."src/views/user/edit-user.php", $this);
        $this->template->toHtml();
    }

    /**
     * Save the user into DB.
     * @URL saveUser
     */
    public function saveUser() {
        $id = $this->formInstance->save();

        if ($id){
            set_user_message("User has been saved", UserMessageInterface::SUCCESS);
        }else{
            set_user_message("An error occured while saving the user", UserMessageInterface::ERROR);
        }

        header("location:".ROOT_URL."editUser?id=".$id);
        return;
    }

create the view for displaying the form :

<?php
use Test\Controllers\UserController;
/* @var $this UserController */
?>
<h1>Edit User</h1>
<?php 
$this->formInstance->toHtml();

Then, bind those instances together : the userController with the formInstance, and the userForm to the formInstance

ENJOY !!

Refresh the cache for registering the new URLs, and goto the /editUser page (or editUser?id=1 for user edition)

TROUBLESHOOTING

BCE is using Mouf's TDBM ORM. You will get a fatal error (PDO Exception) when trying to load a new object form because TDBM will try to save the bean by default.

To fix this, you will have to set the dbConnection instance's "defaultAutoSave" to false.

Continue

Using very few lines of code, and less than 5 minutes in mouf's configuration interface we manaaged creating a simple form, that contains every field of the user table (note that the role field is a dropdown list of items of the role table, and the birth date field is already a datepiker without any further configuration).

But this was just the begining : the generated form is missing some fields (only the ones directly related to the user table are displayed)...

Next Steps :

• In order to get a better understanding of the BCE library, you should read the "Detailed Architecture" chapter.
• Or you might rather like to continue the overview of BCE capabilities, next chapter is "Configuring BCE Forms" chapter.

Found a typo? Something is wrong in this documentation? Just fork and edit it!