Radria Core for PHP5

With PHP 5 we have introduced a new object: DataObject


====== DataObject ======

Its a [[wp>Data_Access_Object|Data Access Object]] that we uses as an [[wp>Object-relational_mapping|Object Relation Mapping]].

To illustrate its usage we will create a small movie database.


===== Movie Project =====

Create a new project called movie with the SiteManager, open the project install all the base packages and the following database related packages:
   
   pb_addon_database 
   report_template 
   phpmyadmin

Lets create the Movie table in the WebIDE or dump the SQL below in phpMyAdmin

<code sql>
CREATE TABLE `movie` (
  `idmovie` int(10) NOT NULL AUTO_INCREMENT,
  `name` varchar(60) NOT NULL,
  `type` varchar(60) NOT NULL,
  `format` varchar(10) NOT NULL,
  `director` varchar(70) NOT NULL,
  `release` date NOT NULL,
  `duration` time NOT NULL,
  PRIMARY KEY  (`idmovie`)
)
</code>

And a base class for our Movie object.
<code php>
<?php
   /**
    * Class movie
    */
    
  class Movie extends DataObject {
    public $table = "movie";
    protected $primary_key = "idmovie";
  }
?>

</code>

Save the class in the class folder of your project as **Movie.class.php**

Then you can create a configuration file for your project create a file as  **includes/movie.conf.inc.php** with
<code php>
<?php
 // Configuration of movie project

include_once("class/Movie.class.php");

?>
</code>


Now lets initiate a Movie object and display a form so we can add data into that table.

===== Basics =====

==== Default form and view ====

Open the PageBuilder, create a new page called **movies.php**, add a script, click on it and replace the code with the following:
<code php>
<?php 
    echo "Add a Movie"; 
   
    $do_movie = new Movie();
    $do_movie->form();
?>
</code>

Click on the save button of the syntax editor to save the source code and then the Save button in the main PageBuilder tool bar to save the page.
Finally click on Preview to test the form.

You can view the records you entered from the WebIDE in the Table Tab by selecting the table and clicking the View button.

Now lets display the content of the data we just entered. Lets create a new script in the PageBuilder and add the following:

<code php>
  
    $do_movie = new Movie();
    $do_movie->view();
</code>

Now if you want to edit one of the record in a form you can do the following

<code php>
<?php 

    $do_movie = new Movie();
    $do_movie->getId(1);
    echo "Editing movie:".$do_movie->name;
    $do_movie->form();
?>
</code>

$do_movie->getId(1) will load the record with primary key idmovie = 1.








==== Relations ====

=== Comments ===
Lets create a Comment object linked to the Movie. So each movies can have multiple comments.
<code sql>
CREATE TABLE `comments` (
  `idcomments` int(10) NOT NULL auto_increment,
  `idmovie` int(10) NOT NULL,
  `author_name` varchar(50) NOT NULL,
  `author_email` varchar(80) NOT NULL,
  `comment_content` text NOT NULL,
  PRIMARY KEY  (`idcomments`),
  UNIQUE KEY `idcomments_2` (`idcomments`),
  KEY `idcomments` (`idcomments`)
)
</code>

Then we create the class in **class/Comment.class.php**:
<code php>
<?php
   /**
    * Class Comment
    */
 
  class Comment extends DataObject {
    public $table = "comments";
    protected $primary_key = "idcomments";
  }
?>
</code>


in the movie configuration project **includes/movie.conf.inc.php** we add the new class:
<code php>
<?php
 // Configuration of movie project
 
include_once("class/Movie.class.php");
include_once("class/Comment.class.php");
?>

</code>


=== Movie comments ===

To display all the comments of a movie just insert in a web page:
<code php>
<?php
  $movie = new Movie();
  $movie->getId(1);
  $comment = $movie->getChildComments();

  echo "Comments for: ".$movie->name;
  while($comment->next()) {
     echo "<hr>".$comment->comment_content;

  }
?>
</code>


===== Forms and Views =====


==== Custom Forms ==== 

=== Registry (basics) ===
The registry is an object that describe how data elements (table fields) should be display in a form or a web page.

Each element is associated with a type and that type is described in a class that will generate the appropriate HTML.

If you have already open the Movie table in WebIDE you should have a registry that got auto generated for it and can view it in the Registry tab.

If not just execute the following PHP code in a web page:
<code php>
<?php
   $reg = new Registry($GLOBALS['conx']);
   $reg->registryFromTable("movie");
   $reg->serializeToXML("movie");
?>
</code>

it will create and serialize a registry for the movie object (or table) called movie.

We will get in more details about the registry later on.

<note important>
This is a very simple example, 
Registry object are quite useful some examples in 
[[core:by_example_php4]] and [[core:registry:registry_object]]
</note>

=== Update form ===
This example will display in details how to display a custom form using PHP and the Dataobject.

Add this code example to one of your web page:

<code php>
<?php
   $movie2 = new Movie();
   $movie2->newUpdateForm("movie2");  
   $movie2->getId(1);                 
   $movie2->setRegistry("movie");     
   $movie2->setApplyRegistry(true, "Form");  
   echo $movie2->form->getFormHeader();
   echo $movie2->form->getFormEvent();
?>
  this is a custom form.
<br>
  <?php echo $movie2->name; ?>

<?
   echo $movie2->form->getFormFooter("Save");
   $movie2->sessionPersistent("movie2", "index.php", 2333);
   
   
?>
</code>
Now lets explain a bit what this is doing.
Simply, it load a data record and display a form field with the value of that record and allow to edit it.


Now more details on what each lines does.

<code php>
   $movie2->newUpdateForm("movie2");
</code> 
Initiate a form object attached to the movie2 session Persistent object. (set a few lines down) 
The other possible method are:
      newAddForm();
      newForm();

<code php>
   $movie2->getId(1); 
</code>               
Load the first record in the movie2 instance.

<code php>
   $movie2->setRegistry("movie");   
</code>
Load a registry object called: movie


<code php>
   $movie2->setApplyRegistry(true, "Form");  
</code>
Apply the registry to all data access on the movie2 object in Form context. 
By default when calling a variable of the object it display its value, when you call this method it will then apply the Registry object field type associated with that variable. Currently we have 2 contexts: **Form** and **Disp** one for forms the other for web page display.

<code php>
   echo $movie2->form->getFormHeader(); 
   echo $movie2->form->getFormEvent();
</code>
**getFormHeader()** Generate and echo first the form header, this is simple the form tag, __<form...>___ you can replace it by your own form tag, the only requirement is the **action="eventcontroler.php"**

The **getFormEvent()** will add all the hidden fields needed by the eventcontroler to process the request.


<code php>
  <?php echo $movie2->name; ?>
</code>
This in general would just echo the value of the movie name variable. But since we have enabled the registry with **setApplyRegistry()** now a class will be loaded and executed to generate HTML code around the value.
In this case it will be a simple input text field.

<code php>
   echo $movie2->form->getFormFooter("Save");
</code>
This will simple display the **submit** tag and close the form. Nothing else so it can be replaced by your own html code.

<code php>
   $movie2->sessionPersistent("movie2", "index.php", 2333);
</code>
This is an important one. It will save in the session the object we just created with all its values.
The first parameter is the name of the object in the session. So it can be called any where with: $_SESSION['movie']
The second is on which page the movie2 object should die.
The third parameter is the number of second before that object is garbaged collected.

See [[core:by_example_php5#session_persistent]] for more details.


==== View templates ====
The examples above are using a template to display the view. A base set of templates are available in the **report_template** Radria package.

To know which is the default template you can do.

<code php>
<?php
echo RADRIA_DEFAULT_REPORT_TEMPLATE;
?>
</code>


==== Basic View templates ====
The **report_template** package has the following view templates

  * default_report: it display in a table with ordering and add/update and delete links.
  * default_report_disp: like default_report but without record editing, just display the records in a table.
  * default_report_one_row: display each field of a record on one line with update/delete links
  * default_report_one_row_disp: like above but without the update/delete links.
  * search_report: like the default report but in addition it display a search box on the top
  * search_report_detail: same as above and also add a **Detail** link to display details on the record.
  * search_report_disp: like the default_report_disp with in addition a search field.

You can load those templates with the **setViewTemplate()** method:
<code php>
<?php

  $do_movie = new Movie();
  $do_movie->setViewTemplate("search_report_detail");
  $do_movie->view();

?>
</code>



==== Custom Saved View ====

It is possible to save a view for customization and later reuse.
Views are stored in the report/ folder they are serialized Report Objects.

To save a view we serialize the view object in an XML file.
<code php>
<?php

  $do_movie = new Movie();
  $do_movie->setViewTemplate("search_report_detail");
  $do_movie->view->serializeToXML("movie_listing");
  $do_movie->view();

?>
</code>
This will create an xml file in the **report/** folder called: **report/movie_listing.report.xml**
If you open that file you will see that the view is composed of a __HEADER__, __ROW__ and __FOOTER__ section.
In those section you have a mix of PHP and HTML code that you can modify and customize to your need. 

To display a saved view just call it with the view prefix: 

     $do_movie->view_<name of your saved view>()

Example:
<code php>

    $do_movie = new Movie();
    $do_movie->getAll();  // run a query that create a resource with all the records
    $do_movie->view_movie_listing();

</code>

<note note>
In this example the method view_movie_listing() doesn't exists its a magic method.
</note>


The view_ magic method will instantiate a Report object using serialized object from the /report/movie_listing.report.xml file.


==== Form templates ====

The same way you can save and customize view you can save and customize forms.

<code php>

    $do_movie = new Movie();
    $do_movie->getid(3);  // run a query that create a resource with all the records
    $do_movie->form_short_form();

</code>


<note note>
In this example the method form_short_form() doesn't exists its a __magic method.
</note>

The view_ magic method will instantiate a ReportForm object using serialized object from the /form/short_form.form.xml file.

===== Persistence =====




==== Session persistent ====

<code php>
<?php
 
    $my_movie = new Movie();
    $my_movie->getid(1);
    $my_movie->sessionPersistent("my_session_movie", "index.php", 300);
?>
</code>

This will make this **$my_movie** object accessible in the session for 300 seconds or until the user reach the index.php page.

After the code above is executed the **$my_movie** object can be accessed with all its variables and properties with **$_SESSION['my_session_movie']** 

<code php>
<?php
  echo $_SESSION['my_session_movie']->name;
?>
</code>
This will display the name of the movie with idmovie=1.

===== EventAction Method =====

You can create method that will be triggered by Event objects in the user interface.

Update your **class/Movie.class.php**
<code php>
<?php
   /**
    * Class movie
    */
    
  class Movie extends DataObject {
    public $table = "movie";
    protected $primary_key = "idmovie";


    function eventIncreaseDuration(EventControler $evctl) {
         $this->duration = $this->duration*2+1;
         $this->update();
         $evctl->SetUrlNext($evctl->getParam("goto"));
    }
  }
?>

</code>

Once this method is created it can be used in Event objects on a web page to let the user trigger that event.
Add this script in a web page called **movies.php**
<code php>
<?php

    $my_movie = new Movie();
    $my_movie->getid(1);
    $my_movie->sessionPersistent("my_movie", "index.php", 300);
 
    $e_calc = new Event("my_movie->eventIncreaseDuration");
    $e_calc->addParam("goto", "movies.php");
   
?>
<?php echo $e_calc->getLink("Increase duration")." for ";
     echo $_SESSION['my_movie']->name; ?>

</code>
This will display a link and when the user click on the link: Recalculate duration it will double the duration or the movie with primary key is 3.


===== Add/Delete/Edit =====


==== Add ====

<code php>
     
    $do_movie = new Movie();
    $do_movie->addNew();
    $do_movie->name = "Blade Runner";
    $do_movie->type = "SF"; 
    $do_movie->format = "DVD";
    $do_movie->director = "Ridley Scott";
    $do_movie->release = "1981";
    $do_movie->duration = "2:30";
    $do_movie->add();
</code>


==== Update ====

<code php>
     
    $do_movie = new Movie();
    $do_movie->getId(3); // Primarykey id of the record to update
    $do_movie->release = "1984";
    $do_movie->duration = "1:40";
    $do_movie->update();

</code>


==== Delete ====
<code php>
     
    $do_movie = new Movie();
    $do_movie->getId(3); // Primarykey id of the record to delete
    $do_movie->delete();

</code>


---------------------------------------

====== Sandbox plug-in ======


<note note> Testing </note>

<box>Testing a bog</box>

{{indexmenu>..#1|js navbar nocookie}}