Jelix proposes a relational object-mapping system named jDao, based on DAO pattern.

The DAO pattern is based on two types of objects : a “record” object, container of the data, and a factory object, which makes it possible to retrieve lists of records, or to create, save, erase records, too.

Concretely with jDao, a DAO XML file enables you to define a record and a factory, which will act on one or more tables at the same time. You thus define the mapping in it: which field of the table will go in which property of the record, as well as the type of data, the keys, on which tables the mapping is carried out, according to which joints etc.

Starting from this file, jDao dynamically generates two classes, stored in a php file in the cache of jelix, and based respectively on jDaoRecordBase and jDaoFactoryBase. In the generated classes, all main methods and SQL requests are statically provided. Indeed, in contrary to other mapping systems, SQL requests are thus generated only once, and not dynamically with each page calls That allows better performances.

In the DAO XML file, you can also define your own access methods to data, and jDao will generate the corresponding methods and requests in the DAO factory.

creating a first DAO

You have a command to be able to create a DAO file, based on an existing table. It has this following syntax:

 module:create-dao [options] [--] <module> <daoname> [<table>] [<sequence>]

A “news” table has been created before, and we will create a DAO named “news”, in the “news” module. Then type:

   php dev.php module:create-dao news news news

You obtain an news.org/modules/news/daos/news.dao.xml file. (you can of course create it by hand). Here is its content:

<?xml version="1.0" encoding="UTF-8"?>
<dao xmlns="http://jelix.org/ns/dao/1.0">
  <datasources>
    <primarytable name="news" realname="news" primarykey="news_id" />
  </datasources>
  <record>
    <property name="news_id" fieldname="news_id" datatype="autoincrement"/>
    <property name="subject" fieldname="subject" datatype="string"/>
    <property name="text" fieldname="text" datatype="string"/>
    <property name="news_date" fieldname="news_date" datatype="date"/>
  </record>
</dao>

This is a very simple content, and of course there are other attributes and tags to enrich it and customize it. For the moment, we will leave it there.

List the news

We will now use this DAO to retrieve and display the list of news. We thus will request from jDao the factory of this DAO, and call its preset method findAll(). We use jDao::get() to do it:

  $fact = jDao::get('news~news');
  $list = $fact->findAll();

As parameter of jDao::get(), we give the DAO selector (which is named “news”, and is in the news module): “news~news”. It gives us the factory of this DAO. And by calling the findAll() method, we retrieve all the list of records.

Actually, this is not really a list, but a jDbResultSet, which is an iterator on the results of the corresponding request.

Let's integrate it in our controller :

    function index() {
        $rep = $this->getResponse('html');
        // the title of the page
        $rep->title = 'Last news';
 
        // let's instanciate a jTpl object
        $tpl = new jTpl();
 
        // retrieving of the data
        $fact = jDao::get('news~news');
        $list = $fact->findAll();
 
        // assing the list into the template
        $tpl->assign('list', $list);
 
        // assign the content of newslist.tpl to the variable $MAIN
        $rep->body->assign('MAIN', $tpl->fetch('newslist'));
 
        return $rep;
    }

We give the list of records to our newslist.tpl object, via the assign method of the template engine. We should then use this list variable to display the data, inside the template:

<h2>Last news</h2>

<table>
{foreach $list as $news}
<tr>
  <td>{$news->subject}</td><td>{$news->news_date}</td>
</tr>
{/foreach}
</table>

You discover here the {foreach} template tag, which is exactly like the php foreach statement.

To display some values, you only have to put the name of the template variable after a $ and between {}.

The list returned by findAll() is a list of record objects, as defined in the xml file. So each records have some news_id, subject, text and news_date properties.

Now refresh your browser at the url http://localhost:8080/index.php/news/. You should see the list of news.

If there are some issues with the charset encoding into your browser, add the parameter force_encoding=on into the profile into profiles.ini.php.