silverstripe-framework/docs/en/reference/dataobject.md

DataObject

Introduction

A single database record & abstract class for the data-access-model.

Usage

• datamodel: The basic pricinples
• data-types: Casting and special property-parsing
• [api:DataObject]: A "container" for DataObjects

Basics

The call to DataObject->getCMSFields() is the centerpiece of every data administration interface in SilverStripe, which returns a [api:FieldList]''.

:::php
class MyPage extends Page {
  function getCMSFields() {
    $fields = parent::getCMSFields();
    $fields->addFieldToTab('Root.Content',new CheckboxField('CustomProperty'));
    return $fields;
  }
}

Scaffolding Formfields

These calls retrieve a [api:FieldList] for the area where you intend to work with the scaffolded form.

For the CMS

• Requirements: SilverStripe 2.3.*

  :::php $fields = singleton('MyDataObject')->getCMSFields();

For the Frontend

Used for simple frontend forms without relation editing or [api:TabSet] behaviour. Uses scaffoldFormFields()by default. To customize, either overload this method in your subclass, or extend it byDataExtension->updateFormFields()`.

• Requirements: SilverStripe 2.3.*

  :::php $fields = singleton('MyDataObject')->getFrontEndFields();

Customizing Scaffolded Fields

• Requirements: SilverStripe 2.3.*

This section covers how to enhance the default scaffolded form fields from above. It is particularly useful when used in conjunction with the [api:ModelAdmin] in the CMS to make relevant data administration interfaces.

Searchable Fields

• Requirements: SilverStripe 2.3.*

The $searchable_fields property uses a mixed array format that can be used to further customize your generated admin system. The default is a set of array values listing the fields.

Example: Getting predefined searchable fields

:::php
$fields = singleton('MyDataObject')->searchableFields();

Example: Simple Definition

:::php
class MyDataObject extends DataObject {
   static $searchable_fields = array(
      'Name',
      'ProductCode'
   );
}

Searchable fields will be appear in the search interface with a default form field (usually a [api:TextField]) and a default search filter assigned (usually an [api:ExactMatchFilter]). To override these defaults, you can specify additional information on $searchable_fields:

:::php
class MyDataObject extends DataObject {
   static $searchable_fields = array(
       'Name' => 'PartialMatchFilter',
       'ProductCode' => 'NumericField'
   );
}

If you assign a single string value, you can set it to be either a [api:FormField] or [api:SearchFilter]. To specify both, you can assign an array:

:::php
class MyDataObject extends DataObject {
   static $searchable_fields = array(
       'Name' => array(
          'field' => 'TextField',
          'filter' => 'PartialMatchFilter',
       ),
       'ProductCode' => array(
           'title' => 'Product code #',
           'field' => 'NumericField',
           'filter' => 'PartialMatchFilter',
       ),
   );
}

To include relations (''$has_one'', $has_many and $many_many) in your search, you can use a dot-notation.

:::php
class Team extends DataObject {
  static $db = array(
    'Title' => 'Varchar'
  );
  static $many_many = array(
    'Players' => 'Player'
  );
  static $searchable_fields = array(
      'Title',
      'Players.Name',
   );
}
class Player extends DataObject {
  static $db = array(
    'Name' => 'Varchar',
    'Birthday' => 'Date'
  );
  static $belongs_many_many = array(
    'Teams' => 'Team'
  );
}

Summary Fields

• Requirements: SilverStripe 2.3.*

Summary fields can be used to show a quick overview of the data for a specific [api:DataObject] record. Most common use is their display as table columns, e.g. in the search results of a [api:ModelAdmin] CMS interface.

Example: Getting predefined summary fields

:::php
$fields = singleton('MyDataObject')->summaryFields();

Example: Simple Definition

:::php
class MyDataObject extends DataObject {
  static $db = array(
    'Name' => 'Text',
    'OtherProperty' => 'Text',
    'ProductCode' => 'Int',
  ); 
  static $summary_fields = array(
      'Name',
      'ProductCode'
   );
}

To include relations in your summaries, you can use a dot-notation.

:::php
class OtherObject extends DataObject {
  static $db = array(
    'Title' => 'Varchar'
  );
}
class MyDataObject extends DataObject {
  static $db = array(
    'Name' => 'Text'
  );
  static $has_one = array(
    'OtherObject' => 'OtherObject'
  );
   static $summary_fields = array(
      'Name',
      'OtherObject.Title'
   );
}

API Documentation

[api:DataObject]