We call simple mapping, a mapping where a record is mapped to a single table. To declare the table, we use the tag <primarytable> with the following attributes:

• name: alias given to the table and that will be used in SQL queries
• realname (optional): real name of the table in the database. If this attribute is not specified, it takes the same value as the attribute name. In this case name must contain the real name of the table.
• primarykey indicates the primary key. You can specify multiple fields, separated by a space or a comma.

  <datasources>
      <primarytable name="p" realname="products" primarykey="id_product" />
  </datasources>

It says here that the record will be based on the table products, which has the alias p, and which contains the primary key id_product.

There is always a single table "primary" in a DAO (hence a single tag <primarytable>). You will see that you can specify other tables (foreign tables) farther.

Then we should declare the mapping between the record fields and the object properties.

The <record> section declares the properties of an object record. Each property corresponds to a field in the primary table, or one of those foreign tables as you will see later. Of course, you are not obliged to declare a property for all existing fields. We can make several DAO working on the same table but which are intended for different uses. For example make a specific DAO to recover slight registration lists (so the mapping is made on the essential properties), and an other to manage full datas (so the mapping is made on all fields).

The <record> section must contain one or more <property> element. Here is the <property> element with possible attributes:

  <property 
      name="simplificated name" 
      fieldname="filed name" 
      datatype="" required="true/false" minlength="" maxlength="" regexp="" 
      sequence="sequence name" autoincrement="true/false"
      updatepattern="" insertpattern="" selectpattern=""
      default="" comment=""
   />

The attribute name is the name of the property of the object.

The attribute fieldname is the field name on which the property is mapped. If name and fieldname are equals, we can leave fieldname.

The attributes datatype, required, minlength, maxlength and regexp are constraints. This allows the check() method to verify the values of properties (before storage for instance).

The attribute default allows you to specify a default value which will be stored in the property.

The attribute datatype indicates the type of the field. Here is the list of recognized types. You can see that there are many more types than in previous jelix version:

• varchar, varchar2, nvarchar2, character, character varying, char, nchar, name, longvarchar, string (deprecated),
• int, integer, tinyint, smallint, mediumint, bigint,
• serial, bigserial, autoincrement, bigautoincrement,
• double, double precision, float, real, number, binary_float, binary_double, money,
• numeric, decimal, dec,
• date, time, datetime, timestamp, utimestamp, year, interval
• boolean, bool, bit
• tinytext, text, mediumtext, longtext, long, clob, nclob
• tinyblob, blob, mediumblob, longblob, bfile,
• varbinary, bytea, binary, raw, long raw
• enum, set, xmltype, point, line, lsed, box, path, polygon, circle, cidr, inet, macaddr, bit varyong, arrays, complex types

Of course, some database doesn't recognize all of these types. Don't worry, jDao will use the corresponding type in the selected database. For example, bytea is a postgresql type. If you use a mysql database, jDao will use longblob.

Values of fields will be converted in the corresponding PHP type, most of time, in a string.

For auto-incremented fields, you can indicate serial or autoincrement as a type. But for some case, it is better to indicate one of integer types, and to set a autoincrement attribute to true. On some databases, an auto incremented field can be associated with a sequence. Then the attribute sequence should contain the sequence name.

The attribute comment allow to indicate a comment on the property. This comment can be used as label for form field, with the createform command.

The attributes updatepattern, insertpattern and selectpattern lets you specify a pattern to be applied during the update, the insert or the read of the field value. This pattern should really be a SQL expression, and can contain the string "%s", which will be replaced by the value or the name of the field. Default values of patterns is "%s". If it indicates an empty value, this corresponds to a null operation (so the field is not readed, inserted or updated). On primary keys you can use insertpattern and selectpattern , but not updatepattern.

Example 1 ¶

  <property name="date_update" datatype="datetime" insertpattern="NOW()" updatepattern="NOW()" />

Example 2 ¶

   <property Name="identite" datatype="string" selectpattern="CONCAT(name,' ',firstname)" insertpattern="" updatepattern="" />

Your class have the name you want, with the suffix DaoRecord, and it should be stored into the directory daos/ of a module, in the file <classname>.daorecord.php.

You indicate the class selector <modulename>~<classname> in the extends attribute on the <record> element.

Note that your class should inherit from jDaoRecordBase.

Example, in your dao file:

   <record extends="news~news">
   ...
   </record>

Records will be objects from the class newsDaoRecord stored in the file daos/news.daorecord.php in the module news.

class newsDaoRecord extends jDaoRecordBase {

   function calculateSomething() {
        $this->field1 = $this->field2 * 1.196;
   }

   function calculateTotal() {
      return $this->amount + $this->vat;
   }
}

Then you can call this method on each records:

   $maFactory = jDao::get("mymodule~news");
   $list = $maFactory->findAll();

   foreach ($list as $row) {
        $total = $row->calculateTotal();
        //...
   }

If your class has a namespace and is autoloadable, you should then indicate its full name into the extends attribute on the <record> element.

The class should inherit from jDaoRecordBase.

Example, in your dao file:

   <record extends="\MyCompany\MyDomain\News">
   ...
   </record>

Records will be objects from the class \MyCompany\MyDomain\News stored in a file News.php somewhere. Here is an example of source code:

class \MyCompany\MyDomain\News extends \jDaoRecordBase {

   function calculateSomething() {
        $this->field1 = $this->field2 * 1.196;
   }

   function calculateTotal() {
      return $this->amount + $this->vat;
   }
}

Then you can call this method on each records:

   $maFactory = jDao::get("mymodule~news");
   $list = $maFactory->findAll();

   foreach ($list as $row) {
        $total = $row->calculateTotal();
        //...
   }

• The DAO to import is readed first, so your dao will contain all of its datasource, properties or methods.
• Then your dao is readed. All of its datasource, properties or methods are added or overwrite existing properties/methods
• The PHP class is then generated

Note that an import is not an inheriting as in PHP.

Example:

A good is example is jauthdb: if you need to define your own DAO, documentation says that "it must have at least the same properties and methods defined into the jelixuser dao".

So, importing the dao of jauthdb into your own dao is a good thing:

<dao import="jauthdb~jelixuser">
	<datasources>
		<primarytable name="user" realname="myusertable" primarykey="login" />
	</datasources>
	<record>
		<property name="nationality" fieldname="nationality" datatype="string" maxlength="100" required="true">
	</record>
	<factory>
		<method name="findByNationality" type="select">
			<parameter name="nationality" />
			<conditions>
				<eq property="nationality" expr="$nationality" />
			</conditions>
		</method>
	</factory>
</dao>

Here you'll have a dao with same properties and methods than "jauthdb~jelixuser" (password, getByLoginPassword, getByLogin...) with this additionnal nationality property and findByNationality() method.