The Datarecord class is the most central object in Platform and therefore it is imperative to understand it. It is used to create most or all data objects used in your application.

In this tutorial we will use it to build a Department object representing the departments in our company and a Employee object representing the employees working in the different departments.

There is a class called Templateclass which holds a template structure for creating new Datarecord objects. We'll be extending that.

First we rename the class and overwrite the $database_table variable, which decides the name of the database table, that these objects are stored into.

department.php

class Department extends \Platform\Datarecord {
  protected static $database_table = 'departments';
  ...
}

Then we overwrite the buildStructure() function to build our desired data structure for a department.

department.php

class Department extends \Platform\Datarecord {
  ...
  protected static buildStructure() {
    $structure = array(
      'department_id' => array(
        'invisible' => true,
        'fieldtype' => self::FIELDTYPE_KEY
      ),
      'title' => array(
        'label' => 'Department title',
        'required' => true,
        'is_title' => true,
        'fieldtype' => self::FIELDTYPE_TEXT
      )
    );
    self::addStructure($structure);
    parent::buildStructure();
  }
}

This defines which fields we want in our object (and thereby our database). The structure is an array hashed by field names, which again refers to arrays defining the field with different keywords.

In line 5 we define we want a field called department_id. We define it should be invisible to the end user (line 6) and that the type should be the record key (line 7) which is required on each object.

Line 9 defines the next field called title, which we give a user-friendly name (line 10) and indicate that this field must be filled in every record (line 11) and that it contains the overall title of the record (line 12). Lastly we say that it should contain a text string (line 13).

That's it for the Department or almost… We need to go back to our Instance-object and add the following line to the initializeDatabase() function:

instance.php

  public function initializeDatabase() {
    parent::initializeDatabase();
    Department::ensureInDatabase();
  }

We create the employee object in a likewise manner:

employee.php

class Employee extends \Platform\Datarecord {
  ...
  protected static $database_table = 'employees';
  ...
  protected static buildStructure() {
    $structure = array(
      'employee_id' => array(
        'invisible' => true,
        'fieldtype' => self::FIELDTYPE_KEY
      ),
      'full_name' => array(
        'label' => 'Full name',
        'required' => true,
        'is_title' => true,
        'fieldtype' => self::FIELDTYPE_TEXT
      ),
      'department_ref' => array(
        'label' => 'Department',
        'fieldtype' => self::FIELDTYPE_REFERENCE_SINGLE,
        'foreign_class' => 'People\\Department'
    );
    self::addStructure($structure);
    parent::buildStructure();
  }
}

This is exactly the same, with only line 17-20 requiring further explanation. This field type is a reference to another datarecord object, where we name our just created Department class. In other words we use this field to link the employee to the department where they work.

Lastly we also add this class to the instance:

instance.php

  public function initializeDatabase() {
    parent::initializeDatabase();
    Department::ensureInDatabase();
    Employee::ensureInDatabase();
  }

And if we now call this code:

$instance_id = Platform\Instance::getActiveInstanceID();
$instance = new People\Instance();
$instance->loadForRead($instance_id);
$instance->initializeDatabase();

We will see that two new table suddenly appears in the instance database, ready to store data from our two datarecord objects. If you at some point wants to adjust the object definitions, then you can just adjust them and call the function above again. You will then see that the database automatically adjusts to your new definition, while trying to keep records already stored in it.

This was a little long, but now that's it.